feat(backend): retry once when an interpretation reads flat

Small models sometimes return a generic one-liner or describe "the photo"
despite the prompt. Detect that (min length + banned-phrase regex) and retry
once with the refined prompt and a hotter temperature, keeping whichever pass
is stronger. Adds an explicit `refined` override to system_prompt() and a
per-call temperature to providers.

backend/oracle.py

@@ -21,6 +21,20 @@ from .providers import Provider, get_provider
 MAX_IMAGES = 4
 MAX_TOKENS = 2048
 
+# Below this, an interpretation reads as a flat one-liner rather than a reading.
+MIN_INTERPRETATION_CHARS = 180
+# A slightly hotter retry to shake a generic first pass loose.
+RETRY_TEMPERATURE = 0.95
+
+# Phrases the prompt forbids — describing "the image" instead of the felt moment.
+# Word-bounded so we don't trip on "imagery", "depict", etc.
+_BANNED = re.compile(
+    r"\bthe (images?|photos?|photographs?|pictures?)\b"
+    r"|\b(this|these) (image|images|photo|photos|picture|pictures)\b"
+    r"|\bthe (image|photo|picture) shows?\b",
+    re.IGNORECASE,
+)
+
 
 class OracleError(Exception):
     """Raised when the model reply can't be coerced into the contract."""
@@ -111,17 +125,45 @@ def _validate(data: dict[str, Any]) -> dict[str, Any]:
     return {"interpretation": interp.strip(), "films": clean_films[:3]}
 
 
+def _is_weak(interpretation: str) -> bool:
+    """A flat or rule-breaking interpretation worth one retry."""
+    text = interpretation.strip()
+    return len(text) < MIN_INTERPRETATION_CHARS or bool(_BANNED.search(text))
+
+
+def _run(provider: Provider, content, *, refined: bool, temperature=None) -> dict[str, Any]:
+    raw = provider.complete(system_prompt(refined=refined), content, MAX_TOKENS, temperature)
+    if not raw.strip():
+        raise OracleError("The model returned an empty reply.")
+    return _validate(_extract_json(raw))
+
+
 def interpret(
     images: list[str],
     fragment: str = "",
     provider: Provider | None = None,
 ) -> dict[str, Any]:
-    """Run the full flow. `images` are data URLs or raw base64 JPEG strings."""
+    """Run the full flow. `images` are data URLs or raw base64 JPEG strings.
+
+    If the first interpretation reads flat or breaks the "never describe the
+    photo" rule, retry once with the refined prompt and a hotter temperature,
+    then keep whichever pass is stronger.
+    """
     if not images:
         raise OracleError("Bring at least one image.")
     provider = provider or get_provider()
     content = _build_content(images, fragment)
-    raw = provider.complete(system_prompt(), content, MAX_TOKENS)
-    if not raw.strip():
-        raise OracleError("The model returned an empty reply.")
-    return _validate(_extract_json(raw))
+
+    result = _run(provider, content, refined=False)
+    if not _is_weak(result["interpretation"]):
+        return result
+
+    try:
+        retry = _run(provider, content, refined=True, temperature=RETRY_TEMPERATURE)
+    except OracleError:
+        return result  # a bad retry shouldn't lose a usable first pass
+
+    if not _is_weak(retry["interpretation"]):
+        return retry
+    # Both flagged — return the meatier of the two.
+    return retry if len(retry["interpretation"]) > len(result["interpretation"]) else result

backend/prompt.py

@@ -39,12 +39,19 @@ _FILM_REFINEMENT = (
 )
 
 
-def system_prompt() -> str:
-    refined = os.environ.get("CHALCHITRA_REFINED_PROMPT", "").lower() in (
-        "1",
-        "true",
-        "yes",
-    )
+def system_prompt(refined: bool | None = None) -> str:
+    """Build the system prompt.
+
+    `refined=None` reads the env flag (default baseline). Pass `refined=True`
+    explicitly to force the refinements — used by the oracle's one-shot retry
+    when a first interpretation reads flat.
+    """
+    if refined is None:
+        refined = os.environ.get("CHALCHITRA_REFINED_PROMPT", "").lower() in (
+            "1",
+            "true",
+            "yes",
+        )
     return _BASE.format(
         interp_extra=_INTERP_REFINEMENT if refined else "",
         film_extra=_FILM_REFINEMENT if refined else "",

backend/providers.py

@@ -31,7 +31,13 @@ class Provider(Protocol):
     name: str
     model: str
 
-    def complete(self, system: str, content: list[dict[str, Any]], max_tokens: int) -> str: ...
+    def complete(
+        self,
+        system: str,
+        content: list[dict[str, Any]],
+        max_tokens: int,
+        temperature: float | None = None,
+    ) -> str: ...
 
 
 class OpenAICompatibleProvider:
@@ -56,11 +62,17 @@ class OpenAICompatibleProvider:
         self.temperature = temperature
         self._client = OpenAI(base_url=base_url, api_key=api_key)
 
-    def complete(self, system: str, content: list[dict[str, Any]], max_tokens: int) -> str:
+    def complete(
+        self,
+        system: str,
+        content: list[dict[str, Any]],
+        max_tokens: int,
+        temperature: float | None = None,
+    ) -> str:
         resp = self._client.chat.completions.create(
             model=self.model,
             max_tokens=max_tokens,
-            temperature=self.temperature,
+            temperature=self.temperature if temperature is None else temperature,
             messages=[
                 {"role": "system", "content": system},
                 {"role": "user", "content": content},
@@ -98,7 +110,13 @@ class HFLocalProvider:
         self.name = "hf_local"
         self.model = model
 
-    def complete(self, system: str, content: list[dict[str, Any]], max_tokens: int) -> str:
+    def complete(
+        self,
+        system: str,
+        content: list[dict[str, Any]],
+        max_tokens: int,
+        temperature: float | None = None,
+    ) -> str:
         raise NotImplementedError(
             "HFLocalProvider (ZeroGPU/transformers) is not implemented yet. While "
             "developing, use CHALCHITRA_PROVIDER=openai_compatible against LM Studio."