feat(v0.3.0): LLM-augmented chat, validation, and follow-up Q&A

Adds an optional LLM layer on top of the deterministic SCI engine.
The engine still works without an LLM key (graceful degradation).

New modules under src/sci_case_tracker/:
  - llm_client.py   provider-agnostic httpx wrapper (Groq / OpenAI /
                    Anthropic / OpenRouter via env vars LLM_PROVIDER,
                    LLM_MODEL, *_API_KEY)
  - validator.py    LLM-based reply validator. Catches mismatches like
                    'user asked about case X but reply is about case Y'.
                    Fail-open: passes the original reply through if LLM
                    is down or response is unparseable.
  - memory.py       per-user SQLite store. Keeps last 10 conversation
                    turns + last uploaded report (24h TTL).
  - router.py       message classifier + chat fallback + report-followup
                    Q&A. Heuristic classify(), then LLM dispatch.

Bot wiring (bot/telegram_bot.py):
  - on_text now decides: sci_lookup | report_followup | chat
  - SCI lookups go through validator before sending
  - 'hi' / 'hello' / general questions get a friendly LLM reply
  - 'from this report list cases where ...' answers from the cached
    last upload (no re-fetch from SCI)
  - on_document caches the enriched rows in memory for follow-ups

Config (in .env, all optional):
  LLM_PROVIDER=groq                          (default: groq)
  LLM_MODEL=llama-3.3-70b-versatile
  GROQ_API_KEY=gsk_...
  LLM_VALIDATION_ENABLED=true
  LLM_CHAT_FALLBACK_ENABLED=true
  LLM_MEMORY_TURNS=10
  LLM_MEMORY_REPORT_TTL_HOURS=24

Tests:
  - 20 new tests (test_router, test_memory, test_validator)
  - All 48 tests pass (mock LLM via unittest.mock.patch)

Live integration verified with Groq llama-3.3-70b:
  - 'hi' returns a friendly Hindi/English greeting
  - 'CA 7395/2024' returns SCI data, validator says 'ok'
  - intentional mismatch correctly flagged
  - Diary-vs-CaseNumber alias collision NOT flagged (false-positive
    fix in validator system prompt)

Provider-agnostic: swap to Claude/OpenAI by changing LLM_PROVIDER and
the matching *_API_KEY env var. No code changes needed.

Author: CyberWarrior9

bot/telegram_bot.py

@@ -36,6 +36,7 @@
 from sci_case_tracker import lookup, parse, SCIError  # noqa: E402
 from sci_case_tracker.batch import process_queries, write_xlsx  # noqa: E402
 from sci_case_tracker.extract import extract_from_bytes  # noqa: E402
+from sci_case_tracker import llm_client, memory, router, validator  # noqa: E402
 
 MAX_UPLOAD_BYTES = 20 * 1024 * 1024
 MAX_CASES_PER_UPLOAD = 200
@@ -159,19 +160,82 @@ async def cmd_list(update: Update, _: ContextTypes.DEFAULT_TYPE):
 async def on_text(update: Update, _: ContextTypes.DEFAULT_TYPE):
     if not _allowed(update):
         return
-    text = update.message.text or ""
-    parsed = parse(text)
-    if parsed.get("kind") == "unknown":
-        return  # ignore non-SCI chatter
-    await update.message.chat.send_action("typing")
-    try:
-        result = lookup(text, as_text=True)
-    except SCIError as e:
-        await update.message.reply_text(f"⚠️ SCI portal error: {e}")
+    text = (update.message.text or "").strip()
+    if not text:
+        return
+
+    user_id = update.effective_user.id
+
+    # Always remember what the user just said (for chat context)
+    memory.add_message(user_id, "user", text)
+
+    # Check if user has a recent uploaded report (for follow-up Q&A)
+    report = memory.get_report(user_id)
+    has_report = report is not None
+
+    # Decide which path to take
+    kind = router.classify(text, has_recent_report=has_report)
+
+    # ── Path 1: SCI case lookup (deterministic engine + optional LLM validation)
+    if kind == "sci_lookup":
+        try:
+            result = lookup(text, as_text=True)
+        except SCIError as e:
+            reply = f"⚠️ SCI portal error: {e}"
+            await update.message.reply_text(reply)
+            memory.add_message(user_id, "assistant", reply)
+            return
+        except ValueError as e:
+            reply = f"⚠️ Could not parse: {e}"
+            await update.message.reply_text(reply)
+            memory.add_message(user_id, "assistant", reply)
+            return
+
+        # Validate the engine's reply matches the user's question
+        try:
+            v = await validator.validate(text, result)
+        except Exception as e:  # noqa: BLE001
+            log.warning("validator threw: %s", e)
+            v = {"verdict": "ok", "skipped": True}
+
+        if v.get("verdict") == "mismatch":
+            issue = v.get("issue", "reply may not match the question")
+            suggestion = v.get("suggestion", "")
+            warning = f"\n\n⚠️ Heads up: {issue}"
+            if suggestion:
+                warning += f"\nDid you mean: {suggestion}"
+            result = result + warning
+
+        await update.message.reply_text(result, disable_web_page_preview=True)
+        memory.add_message(user_id, "assistant", result)
         return
-    except ValueError:
+
+    # ── Path 2: Follow-up question on the last uploaded report
+    if kind == "report_followup" and report:
+        try:
+            reply = await router.report_followup_reply(text, report)
+        except llm_client.LLMError as e:
+            reply = f"⚠️ LLM unavailable: {e}\nTry again in a moment."
+        await update.message.reply_text(reply, disable_web_page_preview=True)
+        memory.add_message(user_id, "assistant", reply)
         return
-    await update.message.reply_text(result, disable_web_page_preview=True)
+
+    # ── Path 3: General chat (LLM fallback)
+    if not llm_client.is_available():
+        # No LLM configured → silent (preserves v0.2.x behavior)
+        return
+    try:
+        history = memory.recent_messages(user_id, limit=10)
+        # Drop the just-added current message from history (we'll send it explicitly)
+        if history and history[-1].get("content") == text:
+            history = history[:-1]
+        reply = await router.chat_reply(text, history=history)
+    except llm_client.LLMError as e:
+        log.warning("chat fallback failed: %s", e)
+        return  # silent on chat failure (don't spam errors for greetings)
+
+    await update.message.reply_text(reply, disable_web_page_preview=True)
+    memory.add_message(user_id, "assistant", reply)
 
 
 async def on_document(update: Update, _: ContextTypes.DEFAULT_TYPE):
@@ -224,6 +288,12 @@ async def on_document(update: Update, _: ContextTypes.DEFAULT_TYPE):
         workers=8,
         sources=[r["source"] for r in refs],
     )
+    # Cache the enriched report so the user can ask follow-up questions
+    try:
+        memory.store_report(update.effective_user.id, rows, filename=filename)
+    except Exception as e:  # noqa: BLE001
+        log.warning("memory.store_report failed: %s", e)
+
     successes = sum(1 for r in rows if not r["remarks"])
     failures = len(rows) - successes
     summary_lines = [f"✅ {successes} fetched · ❌ {failures} failed · {len(rows)} total\n"]