fix(advice): a race in the shared repository, and the prompt naming the wrong reading

Two findings from the re-review of PR #14.

A race that recreated the leak
-------------------------------
`get_shared_repository()` did an unsynchronised check-then-set on a
module global.  Eight concurrent advice threads on a cold process each
saw None and each built their own repository - so eight MongoClients and
twenty-five threads.  The fix that was meant to remove the leak
reintroduced it, just bounded by a race instead of by the number of
readings.

Measured before: 8 repositories built, 25 threads.
Measured after:  1 repository built,  4 threads.

There is a lock, and the check is repeated inside it.

The prompt was about the wrong reading
--------------------------------------
The advice targeted the right reading, but the PROMPT said "give advice
for the most recent reading" - and when the brewer corrects an OLDER
reading, the most recent one in the history is a different reading.  So
the model was asked about the wrong number while the advice was filed
against the right one.

The reading is now named in the instruction (with its date and gravity),
marked in the reading list as the one to advise on, and the system prompt
says to advise about the marked reading because it may not be the most
recent one.

A corrected reading is also flagged as such, so the model knows it may
differ from what it said before.

167 tests (up from 164).

src/flask/brew_advice.py

@@ -67,6 +67,9 @@ temperature?
 - Should they rack, add more hops, raise the temperature, or wait?
 
 Rules:
+- Advise about the reading that is marked as the one to advise on.  It
+  may not be the most recent one - the brewer may be correcting an older
+  reading - and the advice must be about the reading they asked about.
 - If everything looks normal, say so briefly and say what to expect next.
 - If something looks wrong, say what it is and what to do about it.
 - Be specific to the numbers given. Do not give generic advice.
@@ -81,8 +84,13 @@ Write two to five sentences of plain prose.
 """
 
 
-def _reading_lines(readings: list[dict]) -> str:
-    """The readings, as the compact list the model reads."""
+def _reading_lines(readings: list[dict], subject_id: str | None = None) -> str:
+    """The readings, as the compact list the model reads.
+
+    The reading being advised about is marked, so the model does not have
+    to work out which one from the dates - the brewer may be correcting
+    an older reading.
+    """
     lines = []
     for r in readings:
         parts = [f"- {r.get('date')}: gravity {r.get('sg_decimal')} ({r.get('point_scale')})"]
@@ -90,12 +98,19 @@ def _reading_lines(readings: list[dict]) -> str:
             parts.append(f"brewer's comment: {r['comment']}")
         if r.get("final"):
             parts.append("(marked as the FINAL reading)")
+        if subject_id is not None and str(r.get("_id")) == str(subject_id):
+            parts.append("<<< THIS IS THE READING TO ADVISE ON")
         lines.append(" ".join(parts))
     return "\n".join(lines)
 
 
-def build_prompt(run: dict, reading: dict, history: list[dict]) -> str:
-    """The user-message content for one observation."""
+def build_prompt(run: dict, reading: dict, history: list[dict],
+                 corrected: bool = False) -> str:
+    """The user-message content for one observation.
+
+    *corrected* says the reading has just been edited, so the advice
+    should take that into account.
+    """
     name = run.get("canonical_name") or run.get("name") or "this brew"
     og = run.get("og_decimal")
     if og is None and run.get("og_points"):
@@ -113,10 +128,23 @@ def build_prompt(run: dict, reading: dict, history: list[dict]) -> str:
 
     parts.append("")
     parts.append("Readings so far (oldest first):")
-    parts.append(_reading_lines(history))
+    parts.append(_reading_lines(history, subject_id=reading.get("_id")))
 
     parts.append("")
-    parts.append("Give advice for the most recent reading.")
+    # The reading being advised about is NAMED, not just described as
+    # "the most recent one".  The brewer may be editing an older reading,
+    # and the advice is about THAT reading - so the prompt has to say
+    # which one, or the model advises about the newest instead.
+    parts.append(
+        f"Give advice about the reading dated {reading.get('date') or 'unknown'}"
+        f" (gravity {reading.get('sg_decimal')}),"
+        + (" which the brewer has just corrected." if corrected else "")
+    )
+    if corrected:
+        parts.append(
+            "It is the reading they have just corrected, so it may differ "
+            "from what it said before."
+        )
     return "\n".join(parts)
 
 
@@ -139,7 +167,7 @@ def call_ollama(prompt: str, *, url: str | None = None, model: str | None = None
         # allowance and the reply came back empty - which looked like a
         # broken model rather than a budget problem.  2000 leaves room for
         # the reasoning AND the advice.
-        "max_tokens": 2000,
+        "max_tokens": 3000,
         "stream": False,
     }).encode("utf-8")
 
@@ -163,6 +191,7 @@ def call_ollama(prompt: str, *, url: str | None = None, model: str | None = None
 
 
 def generate_advice(run: dict, reading: dict, history: list[dict], *,
+                     corrected: bool = False,
                      url: str | None = None, model: str | None = None,
                      timeout: float | None = None) -> tuple[bool, str]:
     """Generate the advice for one reading.
@@ -171,7 +200,7 @@ def generate_advice(run: dict, reading: dict, history: list[dict], *,
     short note explaining what went wrong, so the reading carries a
     visible reason instead of silently having no advice.
     """
-    prompt = build_prompt(run, reading, history)
+    prompt = build_prompt(run, reading, history, corrected=corrected)
     try:
         return True, call_ollama(prompt, url=url, model=model, timeout=timeout)
     except urllib.error.HTTPError as exc:
@@ -197,14 +226,15 @@ def generate_advice(run: dict, reading: dict, history: list[dict], *,
 
 
 def generate_advice_in_background(run: dict, reading: dict,
-                                   history: list[dict], writer) -> None:
+                                   history: list[dict], writer,
+                                   corrected: bool = False) -> None:
     """Generate the advice and hand it to *writer* when it is ready.
 
     *writer* is called as ``writer(reading_id, ok, text)``.  It runs in a
     background thread, so it must not touch the request context - the
     caller is responsible for giving it a way to reach Mongo.
     """
-    ok, text = generate_advice(run, reading, history)
+    ok, text = generate_advice(run, reading, history, corrected=corrected)
     try:
         writer(reading.get("_id"), ok, text)
     except Exception:  # noqa: BLE001 - never let the thread die noisily

src/flask/mongo/repository.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import logging
 import os
+import threading
 from typing import Any
 
 from pymongo import MongoClient
@@ -380,13 +381,30 @@ def _as_id(value: object) -> str:
 #: repository does too.
 _shared_repository: "BeerRepository | None" = None
 
+#: Guards the check-then-set above.
+#:
+#: Without it, concurrent advice threads each saw ``None`` and each
+#: built their own repository - so the fix reintroduced the very leak it
+#: was meant to remove, just bounded by a race instead of by the number
+#: of readings.  Eight threads on a cold process built eight clients and
+#: twenty-five threads.
+_shared_repository_lock = threading.Lock()
+
 
 def get_shared_repository() -> "BeerRepository":
-    """The process-wide repository, built on first use."""
+    """The process-wide repository, built on first use.
+
+    Thread-safe: the first caller builds it, the rest wait and get the
+    same one.
+    """
     global _shared_repository
 
     if _shared_repository is None:
-        _shared_repository = BeerRepository()
+        with _shared_repository_lock:
+            # Checked again inside the lock - another thread may have
+            # built it while this one was waiting.
+            if _shared_repository is None:
+                _shared_repository = BeerRepository()
     return _shared_repository
 
 

src/flask/views/brews.py

@@ -53,7 +53,7 @@ def advice_enabled() -> bool:
     return os.getenv("LLM_ADVICE", "1").strip().lower() not in {"0", "false", "no"}
 
 
-def _start_advice(run_id: str, reading_id: str) -> None:
+def _start_advice(run_id: str, reading_id: str, corrected: bool = False) -> None:
     """Generate the LLM's advice for a reading, in the background.
 
     The advice is a separate field on the reading, so the brewer's own
@@ -131,7 +131,7 @@ def _start_advice(run_id: str, reading_id: str) -> None:
 
     thread = threading.Thread(
         target=brew_advice.generate_advice_in_background,
-        args=(run_info, latest, readings, write),
+        args=(run_info, latest, readings, write, corrected),
         daemon=True,
     )
     thread.start()
@@ -208,6 +208,14 @@ def index():
                     "warning",
                 )
         run_id = str(form.beer_run_id.data)
+        # Whether the reading was already there: a re-submitted reading
+        # is a CORRECTION, and the advice should say so.
+        existing = repo().reading_docs_for_run(run_id)
+        was_existing = any(
+            str(doc.get("date")) == form.Date.data.isoformat()
+            for doc in existing
+        )
+
         reading_id = repo().upsert_reading(
             beer_run_id=run_id,
             beer_type=(form.beer_run_type.data or "").strip(),
@@ -221,7 +229,7 @@ def index():
         # The advice is generated in the background: recording a reading
         # must not block on the model.  The page shows the reading straight
         # away and the advice is there on a later visit.
-        _start_advice(run_id, reading_id)
+        _start_advice(run_id, reading_id, corrected=was_existing)
         return redirect(url_for("brews.index"))
 
     runs = repo().runs()