Update src/guideline_annotator.py

src/guideline_annotator.py

@@ -1,16 +1,17 @@
 # src/guideline_annotator.py
 from __future__ import annotations
 
+# NOTE (V2): This annotator is POST-HOC ONLY.
+# Do not pre-generate citations; use after the Plan is generated and unedited.
+
 from dataclasses import dataclass
-from typing import Dict, List, Tuple, Any
-import os
+from typing import Dict, List, Any
 
-# We depend on the project's FAISS index helpers if available.
+# Optional FAISS/RAG integration is not required for tests; we provide a safe fallback.
 try:
-    from src.rag_index import load_index_bundle, search_index  # type: ignore
-except Exception:
-    load_index_bundle = None  # type: ignore
-    search_index = None  # type: ignore
+    from src import rag_index  # type: ignore
+except Exception:  # pragma: no cover - optional
+    rag_index = None  # type: ignore
 
 from .explainability import segment_claims
 
@@ -21,38 +22,21 @@ class GuidelineRef:
     excerpt: str
     score: float
 
-def _bundle_ok() -> bool:
-    return callable(load_index_bundle) and callable(search_index)
-
-def _dedup_refs(refs: List[GuidelineRef]) -> List[GuidelineRef]:
-    seen = set()
-    out: List[GuidelineRef] = []
-    for r in refs:
-        key = (r.doc, r.page, r.excerpt.strip()[:80])
-        if key in seen:
-            continue
-        seen.add(key)
-        out.append(r)
-    return out
-
-def find_guideline_refs_for_section(
-    section_text: str,
-    *,
-    top_k_per_claim: int = 3,
-    max_refs_per_claim: int = 2,
-) -> List[GuidelineRef]:
-    """Retrieve post-hoc guideline references for a section by claim-level retrieval."""
-    claims = segment_claims(section_text)
-    if not claims:
-        return []
+def annotate_guidelines(plan_text: str, top_k_per_claim: int = 3, max_refs_per_claim: int = 2) -> Dict[str, Any]:
+    """Return guideline references for the plan text, post-hoc only.
 
+    If a FAISS index is unavailable, returns an empty list and a helpful warning.
+    """
+    claims = segment_claims(plan_text)
     refs: List[GuidelineRef] = []
+    warning: str = ""
 
-    if _bundle_ok():
+    # Attempt a search when a working index is present
+    if rag_index and hasattr(rag_index, "load_index_bundle") and hasattr(rag_index, "search_index"):
         try:
-            embedder, bundle = load_index_bundle()
+            embedder, bundle = rag_index.load_index_bundle()  # type: ignore
             for c in claims:
-                results = search_index(c, embedder, bundle, top_k=top_k_per_claim)  # type: ignore
+                results = rag_index.search_index(c, embedder, bundle, top_k=top_k_per_claim)  # type: ignore
                 for r in (results or [])[:max_refs_per_claim]:
                     refs.append(GuidelineRef(
                         doc=str(r.get("doc_name") or r.get("doc") or r.get("source") or "Guideline"),
@@ -61,39 +45,13 @@ def find_guideline_refs_for_section(
                         score=float(r.get("score", 0.0)),
                     ))
         except Exception:
-            # fallthrough to mock
-            pass
-
-    # Fallback mock if index isn't available
-    if not refs:
-        # Provide deterministic placeholders so the UI remains usable.
-        stub = [
-            GuidelineRef(doc="ACC/AHA 2022", page=7, excerpt="Use high-intensity statins unless contraindicated.", score=0.71),
-            GuidelineRef(doc="ESC 2021", page=12, excerpt="Consider PCSK9 inhibitors for very high LDL-C despite therapy.", score=0.66),
-            GuidelineRef(doc="KDIGO 2020", page=3, excerpt="Dose-adjust renally cleared drugs in CKD stages 3-5.", score=0.64),
-        ]
-        for c in claims:
-            refs.extend(stub[:max_refs_per_claim])
+            warning = "⚠️ No guideline index found – Build one → Go to RAG Prep page"
+    else:
+        warning = "⚠️ No guideline index found – Build one → Go to RAG Prep page"
 
-    return _dedup_refs(refs)
+    return {
+        "refs": [vars(r) for r in refs],
+        "warning": warning,
+        "endnotes": [{"n": i+1, "doc": r.doc, "page": r.page} for i, r in enumerate(refs)],
+    }
 
-def assign_endnotes(registry: Dict[str, int], refs: List[GuidelineRef]) -> Tuple[Dict[str, int], List[Dict[str, Any]]]:
-    """Assign stable endnote numbers using (doc,page) keys. Returns updated registry and serializable refs."""
-    reg = dict(registry or {})
-    next_n = 1 + max(reg.values()) if reg else 1
-    out: List[Dict[str, Any]] = []
-    for r in refs:
-        key = f"{r.doc}::p{r.page}"
-        if key not in reg:
-            reg[key] = next_n
-            next_n += 1
-        out.append({
-            "n": reg[key],
-            "doc": r.doc,
-            "page": r.page,
-            "excerpt": r.excerpt,
-            "score": round(r.score, 3),
-        })
-    # Sort by endnote number
-    out.sort(key=lambda d: int(d["n"]))
-    return reg, out