eli5 response quality revamp

components/handlers/whatsapp_handlers.py

@@ -1,12 +1,12 @@
 # handlers/whatsapp_handlers.py
 import logging
+import os
 import re
 from typing import Optional, Dict
 
 from fastapi.responses import JSONResponse
 
 from components.gateways.headlines_to_wa import fetch_cached_headlines, send_to_whatsapp
-from components.indexers.news_indexer import load_news_index  # should return a LlamaIndex VectorStoreIndex
 from components.LLMs.Mistral import MistralTogetherClient, build_messages
 
 # ------------------------------------------------------------
@@ -98,7 +98,7 @@ def handle_small_talk(from_number: str) -> JSONResponse:
 
 
 # ------------------------------------------------------------
-# Chat Question → “Explain by number” flow
+# Chat Question → “Explain by number” flow (structured + quality-guarded)
 # ------------------------------------------------------------
 
 _HEADLINE_LINE_RE = re.compile(r"^\s*(\d+)\.\s+(.*)$")
@@ -142,18 +142,28 @@ def _parse_rendered_digest(rendered: str) -> Dict[int, str]:
     return mapping
 
 
-def _retrieve_context_for_headline(headline_text: str, top_k: int = 5) -> str:
+def _retrieve_context_for_headline(headline_text: str, top_k: int = 15) -> str:
     """
     Use the vector index to pull contextual passages related to the headline.
-    Gracefully degrades if index is unavailable.
+    - Uses a higher top_k to widen coverage (quality over speed).
+    - Gracefully degrades if index is unavailable or not yet built.
     """
+    # Defer the import so a missing/invalid index module won't break imports
+    try:
+        from components.indexers.news_indexer import load_news_index  # type: ignore
+    except Exception as e:
+        logging.warning(f"Index module not available yet: {e}")
+        return ""
+
+    # Try to load the index; if persist_dir is wrong/missing, swallow and return ""
     try:
         index = load_news_index()
         try:
+            # LlamaIndex v0.10+
             qe = index.as_query_engine(similarity_top_k=top_k)
         except Exception:
-            # Older LlamaIndex fallback
-            from llama_index.core.query_engine import RetrievalQueryEngine
+            # Older API fallback
+            from llama_index.core.query_engine import RetrievalQueryEngine  # type: ignore
             qe = RetrievalQueryEngine(index=index, similarity_top_k=top_k)
 
         query = (
@@ -164,33 +174,99 @@ def _retrieve_context_for_headline(headline_text: str, top_k: int = 5) -> str:
         resp = qe.query(query)
         return str(resp)
     except Exception as e:
-        logging.exception(f"Vector retrieval failed: {e}")
+        # Avoid noisy tracebacks in normal operation; index may simply not exist yet
+        persist_dir = os.getenv("NEWS_INDEX_PERSIST_DIR") or os.getenv("PERSIST_DIR") or "<unset>"
+        logging.warning(f"Vector retrieval skipped (no index at {persist_dir}): {e}")
         return ""
 
 
-def _eli5_answer(question: str, context: str) -> str:
+def _eli5_answer_structured(question: str, context: str, headline_only: Optional[str] = None) -> str:
     """
-    Ask Mistral (via Together) to explain using simple words.
+    Generate a structured, quality-guarded ELI5 answer.
+    Format:
+    Headline #N — <short title>
+    Key points:
+    • ...
+    • ...
+    Numbers & facts:
+    • ...
+    Why it matters:
+    • ...
+    Caveats:
+    • ...
+    Confidence: High/Medium/Low
+
+    Rules:
+    - 120–180 words total.
+    - Use ONLY the provided context/headline; if missing, write “Not in context”.
+    - No speculation; keep neutral tone; be brief.
     """
     sys_prompt = (
-        "You are a concise explainer for a news assistant. "
-        "Answer like the person is 5 years old (ELI5): short sentences, simple words, "
-        "and 3–6 bullet points max. Be accurate and neutral. If unsure, say so."
-    )
-    user_prompt = (
-        f"QUESTION:\n{question}\n\n"
-        f"CONTEXT (may be partial):\n{context}\n\n"
-        "Now give a short ELI5 explanation. Avoid jargon. If numbers matter, include them."
+        "You are a rigorous, concise explainer for a news assistant. "
+        "Produce clear, structured outputs with bullet points. "
+        "If any detail is not present in context, write 'Not in context'. "
+        "Avoid flowery language; be factual and neutral."
     )
 
+    if context.strip():
+        user_prompt = (
+            f"QUESTION:\n{question}\n\n"
+            f"CONTEXT (may be partial, use ONLY this):\n{context}\n\n"
+            "Write 120–180 words in this exact structure:\n"
+            "Headline:\n"
+            "Key points:\n"
+            "• ...\n• ...\n• ...\n"
+            "Numbers & facts:\n"
+            "• ...\n• ...\n"
+            "Why it matters:\n"
+            "• ...\n"
+            "Caveats:\n"
+            "• ...\n"
+            "Confidence: High | Medium | Low\n"
+            "Rules:\n"
+            "- If you can't find a detail in CONTEXT, write 'Not in context'.\n"
+            "- Do NOT add sources or links unless they appear in CONTEXT.\n"
+            "- Keep it short, precise, and neutral.\n"
+        )
+    else:
+        # fallback: rely on the headline only
+        headline_text = headline_only or question
+        user_prompt = (
+            "CONTEXT is empty. You must base the answer ONLY on the HEADLINE below; "
+            "write 'Not in context' for any missing specifics.\n\n"
+            f"HEADLINE:\n{headline_text}\n\n"
+            "Write 90–140 words in this exact structure:\n"
+            "Headline:\n"
+            "Key points:\n"
+            "• ...\n• ...\n"
+            "Numbers & facts:\n"
+            "• Not in context\n"
+            "Why it matters:\n"
+            "• ...\n"
+            "Caveats:\n"
+            "• Limited details available\n"
+            "Confidence: Low\n"
+        )
+
     try:
         llm = MistralTogetherClient()
         msgs = build_messages(user_prompt, sys_prompt)
-        out, _usage = llm.chat(msgs, temperature=0.2, max_tokens=350)
+        out, _usage = llm.chat(msgs, temperature=0.2, max_tokens=400)
         return out.strip()
     except Exception as e:
-        logging.exception(f"Mistral ELI5 generation failed: {e}")
-        return "I couldn’t generate a simple explanation right now. Please try again."
+        logging.exception(f"Mistral structured ELI5 generation failed: {e}")
+        return (
+            "Headline:\n"
+            "Key points:\n"
+            "• I couldn’t generate an explanation right now.\n"
+            "Numbers & facts:\n"
+            "• Not in context\n"
+            "Why it matters:\n"
+            "• Not in context\n"
+            "Caveats:\n"
+            "• System error\n"
+            "Confidence: Low"
+        )
 
 
 def handle_chat_question(from_number: str, message_text: str) -> JSONResponse:
@@ -199,8 +275,8 @@ def handle_chat_question(from_number: str, message_text: str) -> JSONResponse:
       - If the user references a headline number (“explain 14 like I’m 5”),
         1) Parse the number
         2) Look up that numbered line from the rendered digest
-        3) Retrieve vector context
-        4) Generate an ELI5 answer with Mistral (Together.ai)
+        3) Retrieve vector context (top_k widened for coverage)
+        4) Generate a STRUCTURED ELI5 answer (with quality guardrails)
       - Otherwise, provide a gentle hint (for now).
     """
     logging.info(f"Chat question from {from_number}: {message_text}")
@@ -221,12 +297,12 @@ def handle_chat_question(from_number: str, message_text: str) -> JSONResponse:
             )
             return JSONResponse(status_code=200, content={"status": "success", "message": "Number not found"})
 
-        # 3) Retrieve context from the vector index using the headline line
-        ctx = _retrieve_context_for_headline(target_line, top_k=5)
+        # 3) Retrieve broader context from the vector index using the headline line
+        ctx = _retrieve_context_for_headline(target_line, top_k=15)
 
-        # 4) Generate ELI5 answer
+        # 4) Generate STRUCTURED ELI5 answer (works even if ctx == "")
         question = f"Explain headline #{number}: {target_line}"
-        answer = _eli5_answer(question, ctx)
+        answer = _eli5_answer_structured(question, ctx, headline_only=target_line)
 
         # 5) Send back
         _safe_send(answer, to=from_number)