Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="backend/apps/ai/embeddings/google.py">

<violation number="1" location="backend/apps/ai/embeddings/google.py:51">
P0: Bug: `genai.configure()` and `genai.embed_content()` are APIs from the deprecated `google.generativeai` package, not the new `google.genai` SDK imported on line 5. When the new SDK is installed, this will raise `AttributeError` at runtime.

The new `google.genai` SDK uses a `Client` object pattern:
```python
client = genai.Client(api_key=self.api_key)
result = client.models.embed_content(model=self.model, contents=text)

The genai.configure() + genai.embed_content() pattern only works with the old deprecated google.generativeai package. Since the primary import on line 5 is the new SDK, this code will fail in the happy path.

(Based on your team's feedback about maintaining consistent and accurate naming.) [FEEDBACK_USED]

backend/apps/ai/common/llm_config.py (1)

36-47: Simplify the fallback guard — "openai" and "google" are unreachable here.

Since both known providers already return on lines 23 and 29, the provider not in ("openai", "google") check on line 37 is always true when reached. You can simplify to just if provider:.

♻️ Suggested simplification

-    if provider and provider not in ("openai", "google"):
+    if provider:

backend/settings/base.py (1)

221-232: LGTM — good documentation on the Value() vs SecretValue() trade-off for GOOGLE_API_KEY.

The comment clearly explains why SecretValue() isn't used. One thing to note: when LLM_PROVIDER=google but GOOGLE_API_KEY is unset, it will be None at runtime, which will surface as an opaque API error. Consider adding an early startup check (e.g., in AppConfig.ready() or in get_llm()) that raises a clear ImproperlyConfigured error. Based on learnings, the redundant environ_name removal on OPEN_AI_SECRET_KEY is correct.

backend/tests/apps/ai/common/llm_config_test.py (1)

54-78: Consider adding a test for unset/empty LLM_PROVIDER to cover the silent fallback path.

The current unsupported-provider test verifies warning + fallback, but there's no test for when LLM_PROVIDER is None or "" (the "not specified" path in llm_config.py that falls back to OpenAI without logging a warning). This is a distinct code path worth covering.

backend/apps/ai/embeddings/google.py (1)

224-267: Per-item REST fallback in the new SDK path defeats batching and duplicates logic.

When the new SDK path fails for individual documents (lines 252-266), each item falls back to individual REST calls instead of collecting failures and using the batch endpoint. Additionally, the REST call logic and SDK response parsing are duplicated across embed_query and embed_documents.

Consider extracting a _embed_single_rest(text) helper and a _parse_sdk_result(result) helper to reduce duplication and centralize error handling.

backend/settings/base.py (1)

221-232: Good cleanup on OPEN_AI_SECRET_KEY and well-documented rationale for GOOGLE_API_KEY.

The removal of the redundant environ_name is correct. The comment explaining why Value() is used instead of SecretValue() for GOOGLE_API_KEY is helpful.

One consideration: since OPEN_AI_SECRET_KEY uses SecretValue(), it must be set in the environment at startup — even for Google-only deployments — because SecretValue raises ImproperlyConfigured during class resolution. This is consistent with the fallback-to-OpenAI design, but it means a pure Google-only setup isn't possible without also providing an OpenAI key (or a dummy value). If that's intentional, it might be worth a brief comment. If Google-only setups should be supported in the future, OPEN_AI_SECRET_KEY would need the same Value(default=None) treatment.

Based on learnings, the redundant environ_name removal on OPEN_AI_SECRET_KEY aligns with the established pattern that django-configurations automatically prefixes with DJANGO_ and uses the setting name by default.

backend/apps/ai/common/llm_config.py (2)

36-47: Simplify the redundant guard on line 37.

At this point in the function, provider is guaranteed to be neither "openai" nor "google" (both returned early). The provider not in ("openai", "google") check is always True here. Simplify to just if provider:.

♻️ Suggested simplification

     # Fallback to OpenAI if provider not recognized or not specified
-    if provider and provider not in ("openai", "google"):
+    if provider:
         logger.error(
             "Unrecognized LLM_PROVIDER '%s'. Falling back to OpenAI. "
             "Supported providers: 'openai', 'google'",
             provider,
         )

---

22-47: Consider extracting the repeated OpenAI LLM construction.

The OpenAI LLM(...) call on lines 23–27 is duplicated in the fallback on lines 43–47. If this grows (e.g., adding more kwargs), you'd need to update both. A small helper or variable could reduce drift risk.

♻️ One possible approach

 def get_llm() -> LLM:
-    """Get configured LLM instance.
-
-    Returns:
-        LLM: Configured LLM instance based on settings.
-
-    """
+    """Get configured LLM instance based on settings."""
     provider = settings.LLM_PROVIDER
 
+    def _openai_llm() -> LLM:
+        return LLM(
+            model=settings.OPEN_AI_MODEL_NAME,
+            api_key=settings.OPEN_AI_SECRET_KEY,
+            temperature=0.1,
+        )
+
     if provider == "openai":
-        return LLM(
-            model=settings.OPEN_AI_MODEL_NAME,
-            api_key=settings.OPEN_AI_SECRET_KEY,
-            temperature=0.1,
-        )
+        return _openai_llm()
     if provider == "google":
         return LLM(
             model=settings.GOOGLE_MODEL_NAME,
             base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
             api_key=settings.GOOGLE_API_KEY,
             temperature=0.1,
         )
 
     # Fallback to OpenAI if provider not recognized or not specified
-    if provider and provider not in ("openai", "google"):
+    if provider:
         logger.error(
             "Unrecognized LLM_PROVIDER '%s'. Falling back to OpenAI. "
             "Supported providers: 'openai', 'google'",
             provider,
         )
-    return LLM(
-        model=settings.OPEN_AI_MODEL_NAME,
-        api_key=settings.OPEN_AI_SECRET_KEY,
-        temperature=0.1,
-    )
+    return _openai_llm()

backend/tests/apps/ai/common/llm_config_test.py (2)

54-78: Good coverage of the fallback path with logger verification.

The decorator ordering and parameter mapping (mock_llm, mock_logger) are correct. The test properly verifies both the error logging and the OpenAI fallback.

One gap worth noting: there's no test for when LLM_PROVIDER is empty/falsy (e.g., ""). In that case the code silently falls back to OpenAI without logging an error — a subtly different path from the unsupported-provider case. Consider adding a test for that edge case to lock down the behavior.

---

80-125: Good coverage for Google provider paths.

Both default and custom model tests for the Google provider look correct. The expected base_url, api_key, and temperature values match the implementation in llm_config.py.

One edge case to consider: what happens when DJANGO_LLM_PROVIDER=google but DJANGO_GOOGLE_API_KEY is not set? The setting defaults to None, so get_llm() would pass api_key=None to LLM(...), which would likely fail at call time. A test covering this scenario could document whether that's an expected failure mode or whether get_llm() should validate the key and fall back.

backend/apps/ai/embeddings/google.py (3)

57-62: Return type should be NoReturn, not implicit None.

The other two helper functions (_raise_deprecated_api_error, _raise_deprecated_api_dict_error) correctly use -> NoReturn. This one always raises but declares no return type, which means type checkers infer -> None.

Fix

-def _raise_embedding_extraction_error() -> None:
+def _raise_embedding_extraction_error() -> NoReturn:

---

234-235: Remove "placeholder" comment before merging.

Line 235 says "this is a placeholder implementation" — this should be removed or replaced with accurate documentation, as it undermines confidence in the code path.

---

232-253: Duplicated new-SDK extraction logic — extract to a helper.

The embedding extraction pattern (lines 244-253 and 322-333) is duplicated between embed_query and embed_documents. Consider extracting it to a helper function similar to _extract_embedding_from_result for the deprecated path, to keep the methods focused and reduce duplication.

Also applies to: 310-333

backend/apps/ai/embeddings/google.py (3)

57-62: Return type should be NoReturn, not None.

This function unconditionally raises. The other two helpers (_raise_deprecated_api_error, _raise_deprecated_api_dict_error) correctly annotate -> NoReturn. This one should match for consistency and to help static analysis.

Suggested fix

-def _raise_embedding_extraction_error() -> None:
+def _raise_embedding_extraction_error() -> NoReturn:

---

282-357: embed_documents mixes per-item SDK calls with per-item REST fallback — consider batch REST as the fallback.

Currently, in the new SDK path (lines 306-357), if the SDK fails for one text, the code falls back to individual REST calls per item. However, the pure REST path (lines 359-381) already uses the batch batchEmbedContents endpoint, which is more efficient. If the SDK consistently fails (e.g., incompatible version), every item will trigger a separate REST call instead of a single batch request.

Consider collecting failed items and batch-calling the REST endpoint once, rather than issuing per-item REST requests inside the loop.

---

337-337: Falsy check if embedding_values: will treat a valid empty embedding [] as failure.

While unlikely in practice (embeddings should always be non-empty), using if embedding_values is not None: is semantically more correct and avoids a subtle bug if the API ever returns an empty list.

Suggested fix

-                if embedding_values:
+                if embedding_values is not None:

backend/apps/ai/embeddings/google.py (2)

52-60: embed_documents can use a single batched SDK call instead of N sequential calls.

The google.genai SDK accepts a list for the contents parameter, returning all embeddings in one API round-trip. The current per-text loop makes N separate calls, which adds latency and quota overhead proportional to document count.

♻️ Proposed refactor

 def embed_documents(self, texts: list[str]) -> list[list[float]]:
-    results = []
-    for text in texts:
-        result = self.client.models.embed_content(
-            model=self.model,
-            contents=text,
-            config=types.EmbedContentConfig(output_dimensionality=1536),
-        )
-        results.append(result.embeddings[0].values)
-    return results
+    result = self.client.models.embed_content(
+        model=self.model,
+        contents=texts,
+        config=types.EmbedContentConfig(output_dimensionality=1536),
+    )
+    return [emb.values for emb in result.embeddings]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` around lines 52 - 60, The
embed_documents implementation currently loops and calls
self.client.models.embed_content per text; change it to make one batched call by
passing the entire texts list as contents to self.client.models.embed_content
(keep model=self.model and output_dimensionality=1536), then iterate over the
returned response.embeddings to extract each embedding.values into the results
list and return that list; update any variable names in the embed_documents
method to reflect the single response handling instead of per-text calls.

---

14-23: Extract the hardcoded 1536 as a class-level constant to keep _dimensions and output_dimensionality in sync.

The value 1536 appears independently in _dimensions (line 23) and both embed_content calls (lines 38, 57). If they drift, get_dimensions() will report a dimension that differs from what the API actually returns.

♻️ Proposed refactor

+_EMBEDDING_DIMENSIONS = 1536
+
 class GoogleEmbedder(Embedder):
     def __init__(self, model: str = "gemini-embedding-001") -> None:
         self.client = genai.Client(api_key=settings.GOOGLE_API_KEY)
         self.model = model
-        self._dimensions = 1536
+        self._dimensions = _EMBEDDING_DIMENSIONS

Then reference _EMBEDDING_DIMENSIONS in the config of both embed_content calls.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` around lines 14 - 23, Extract the
hardcoded 1536 into a class-level constant named _EMBEDDING_DIMENSIONS (on the
Google embedder class) and set self._dimensions = self._EMBEDDING_DIMENSIONS in
__init__; then update both calls to genai.Client().embed_content (the
embed_content usages in this file) to pass
output_dimensionality=self._EMBEDDING_DIMENSIONS in their config so
embed_content and get_dimensions() remain in sync; verify references in methods
embed_content and get_dimensions (or any other place using the literal 1536) are
replaced with the constant.

backend/apps/ai/embeddings/google.py (2)

14-23: Extract the hardcoded dimension 1536 into a single module-level constant.

The value 1536 appears three times independently — on lines 23, 38, and 57. A future change to the dimension (e.g. switching to 3072 or 768) requires three separate edits with no guarantee they stay in sync.

♻️ Proposed refactor

+DEFAULT_MODEL = "gemini-embedding-001"
+DEFAULT_DIMENSIONS = 1536
+
 class GoogleEmbedder(Embedder):
     def __init__(self, model: str = "gemini-embedding-001") -> None:
+    def __init__(self, model: str = DEFAULT_MODEL) -> None:
         self.client = genai.Client(api_key=settings.GOOGLE_API_KEY)
         self.model = model
-        self._dimensions = 1536
+        self._dimensions = DEFAULT_DIMENSIONS

Then reference DEFAULT_DIMENSIONS in the two config= calls as well.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` around lines 14 - 23, Extract the
hardcoded 1536 into a module-level constant named DEFAULT_DIMENSIONS and use it
everywhere instead of literal numbers: set DEFAULT_DIMENSIONS = 1536 at top of
the module, replace self._dimensions = 1536 in __init__ with self._dimensions =
DEFAULT_DIMENSIONS, and update both config= calls that currently pass 1536 to
reference DEFAULT_DIMENSIONS so all three places (the __init__ assignment and
the two config parameters) use the single constant.

---

52-60: embed_documents makes N sequential API calls; the SDK supports a single batched call.

The Google GenAI SDK accepts a list of strings as contents, returning one embedding per entry in a single request. The current loop multiplies latency and API quota consumption linearly with document count.

♻️ Proposed batch refactor

     def embed_documents(self, texts: list[str]) -> list[list[float]]:
         ...
-        results = []
-        for text in texts:
-            result = self.client.models.embed_content(
-                model=self.model,
-                contents=text,
-                config={"output_dimensionality": 1536},
-            )
-            results.append(result.embeddings[0].values)
-        return results
+        if not texts:
+            return []
+        result = self.client.models.embed_content(
+            model=self.model,
+            contents=texts,
+            config={"output_dimensionality": 1536},
+        )
+        if not result.embeddings:
+            msg = f"Google embedding API returned no embeddings for model {self.model!r}"
+            raise ValueError(msg)
+        return [embedding.values for embedding in result.embeddings]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` around lines 52 - 60, The
embed_documents implementation is making N sequential calls; change it to a
single batched call by passing the full texts list as the contents argument to
self.client.models.embed_content (instead of looping), then map the returned
embeddings to the same shape (extracting embedding.values for each item) and
return that list; update the method named embed_documents (and any helper using
the per-text loop) to call self.client.models.embed_content once with
contents=texts and config={"output_dimensionality": 1536} and convert
result.embeddings into the list of lists expected by the caller.

backend/apps/ai/embeddings/google.py (2)

38-38: output_dimensionality should reference self._dimensions instead of a hardcoded literal.

_dimensions is set once in __init__ but the config dict in both embed_query (line 38) and embed_documents (line 60) repeat the literal 1536. These two values will silently diverge if _dimensions is ever changed.

♻️ Proposed fix

-            config={"output_dimensionality": 1536},
+            config={"output_dimensionality": self._dimensions},

(Apply in both embed_query and embed_documents.)

Also applies to: 60-60

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` at line 38, Replace the hardcoded 1536
in the config dicts with the instance field so the embed functions always use
the initialized dimension: update the config={"output_dimensionality": 1536}
entries in both embed_query and embed_documents to reference self._dimensions
(e.g., config={"output_dimensionality": self._dimensions}) so the methods use
the class's _dimensions value rather than a literal.

---

55-66: embed_documents makes N serial API calls — use a single batch call instead.

The google-genai SDK supports passing a list of strings to contents in client.models.embed_content(), returning all embeddings in one response.

♻️ Proposed batch refactor

 def embed_documents(self, texts: list[str]) -> list[list[float]]:
     ...
-    results = []
-    for text in texts:
-        result = self.client.models.embed_content(
-            model=self.model,
-            contents=text,
-            config={"output_dimensionality": self._dimensions},
-        )
-        if not result.embeddings:
-            msg = f"Google embedding API returned no embeddings for model {self.model!r}"
-            raise ValueError(msg)
-        results.append(result.embeddings[0].values)
-    return results
+    if not texts:
+        return []
+    result = self.client.models.embed_content(
+        model=self.model,
+        contents=texts,
+        config={"output_dimensionality": self._dimensions},
+    )
+    if not result.embeddings or len(result.embeddings) != len(texts):
+        msg = f"Google embedding API returned {len(result.embeddings) if result.embeddings else 0} embeddings for {len(texts)} texts using model {self.model!r}"
+        raise ValueError(msg)
+    return [emb.values for emb in result.embeddings]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@backend/apps/ai/embeddings/google.py` around lines 55 - 66, The current loop
in embed_documents that calls self.client.models.embed_content per text should
be replaced with a single batched call: call self.client.models.embed_content
once with contents=texts and the same config ({"output_dimensionality": 1536}),
then validate the response (ensure result.embeddings exists and length matches
len(texts)), extract each embedding's .values into a list in the original order,
and return that list; update error handling to raise a ValueError if embeddings
are missing or counts mismatch.