feat(llm-chain): KI-078 — tighten per-link timeout + narrow exception catch + stamp fallback reason for telemetry

Three related LLM-chain hardening fixes that together close the loop on
KI-075's fact-find brain failure root cause:

1. nvidia_nim_llm.py — per-link timeout 12s → 6s in get_fast_brain_llm().
With a 22s total chain budget, a 12s per-link meant only 1 candidate
could complete before the budget expired — i.e. the entire fallback
chain was effectively dead. Healthy paths (Groq LPU, NIM Nemotron
Nano, NIM Qwen) all TTFT in <2s, so 6s catches a degraded link fast
and lets the chain try 3-4 candidates inside the 22s budget. NIM
cold-start still has Groq's cross-provider link (no NIM cold-start
exposure) + the outer fact_find_brain wait_for=25s.

2. nvidia_nim_llm.py — narrow the broad `except Exception` in
NimChainLLM.chat() loop to re-raise asyncio.CancelledError,
KeyboardInterrupt, SystemExit. The previous broad catch was
swallowing CancelledError, so when fact_find_brain's outer
asyncio.wait_for(_TIMEOUT_S=25s) fired, this loop kept burning the
full chain budget instead of bubbling cancellation up — the fact-
find turn lost its fallback window every time.

3. fact_find_brain.py + orchestrator.py — stamp _fallback_reason on
FactFindOutcome when _canonical_fallback fires (one of: "timeout",
"llm_error", "no_trailer", "empty_reply"). Orchestrator now builds
brain_used = "fact_find_brain::fallback:timeout" instead of just
"fact_find_brain::fallback". Admin telemetry / usage logs can now
measure the fallback-cause mix, which is essential for verifying
KI-075 + KI-078 impact in production.

Verification:
- py_compile all 3 files: OK
- inline FactFindOutcome shape + orchestrator tag wiring tests: OK
- pytest tests/test_routing_regression.py -x -q: 15 passed, 13 subtests passed

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/fact_find_brain.py

@@ -55,6 +55,16 @@ class FactFindOutcome:
     slot_driving: Optional[str] = None
     fact_find_complete: bool = False
     ambiguous: bool = False
+    # KI-078 (2026-05-15) — when `ambiguous=True` because the LLM brain
+    # bailed and `_canonical_fallback` was used, this stamps WHY so the
+    # orchestrator can append it to `brain_used` and admin telemetry can
+    # measure the fallback-reason mix. One of:
+    #   "timeout"     — asyncio.wait_for(_TIMEOUT_S) expired
+    #   "llm_error"   — chain raised (non-timeout) before returning
+    #   "no_trailer"  — reply had no <FF>...</FF> JSON block, or it failed parse
+    #   "empty_reply" — trailer stripped to an empty user-facing reply
+    # None when the brain succeeded.
+    _fallback_reason: Optional[str] = None
 
 
 # ----------------------------------------------------------------------------
@@ -612,6 +622,7 @@ def _canonical_fallback(session, user_text: str, *, reason: str) -> FactFindOutc
             slot_driving=slot,
             fact_find_complete=False,
             ambiguous=True,
+            _fallback_reason=reason,  # KI-078 — telemetry stamp
         )
     # Nothing left to ask — gentle hand-off.
     reply = (
@@ -625,4 +636,5 @@ def _canonical_fallback(session, user_text: str, *, reason: str) -> FactFindOutc
         slot_driving=None,
         fact_find_complete=False,
         ambiguous=True,
+        _fallback_reason=reason,  # KI-078 — telemetry stamp
     )

backend/orchestrator.py

@@ -473,7 +473,12 @@ async def handle_turn(
                 pass
 
         if outcome.ambiguous:
-            brain_tag = "fact_find_brain::fallback"
+            # KI-078 (2026-05-15) — append fallback reason so admin telemetry
+            # can measure the fallback-cause mix (timeout vs llm_error vs
+            # no_trailer vs empty_reply). Essential for measuring KI-075 +
+            # KI-078 impact in production.
+            reason = getattr(outcome, "_fallback_reason", None) or "unknown"
+            brain_tag = f"fact_find_brain::fallback:{reason}"
         elif outcome.fact_find_complete:
             brain_tag = "fact_find_brain::complete"
         else:

backend/providers/nvidia_nim_llm.py

@@ -422,6 +422,14 @@ class NimChainLLM(LLMProvider):
                     httpx.ConnectError, httpx.NetworkError, asyncio.TimeoutError) as e:
                 last_err = e
                 continue  # try next model in chain
+            except (asyncio.CancelledError, KeyboardInterrupt, SystemExit):
+                # KI-078 (2026-05-15) — must re-raise these. The previous
+                # broad `except Exception` swallowed CancelledError, so when
+                # fact_find_brain's outer `asyncio.wait_for(_TIMEOUT_S)`
+                # fired, this loop kept consuming budget instead of bubbling
+                # the cancellation up. That cost the entire fact-find turn
+                # its fallback window.
+                raise
             except Exception as e:
                 # Unexpected error — record + try next, but surface eventually if all fail
                 last_err = e
@@ -525,11 +533,22 @@ def get_brain_llm() -> NimChainLLM:
 def get_fast_brain_llm() -> NimChainLLM:
     """Fast brain — multi-model NIM chain optimized for low TTFT.
     Primary: Qwen 3-Next 80B (50%) or Groq Llama-3.3-70B (50%). See
-    FAST_BRAIN_CHAIN for fallback order. KI-021 — per-link 12s, total chain
-    budget 22s. KI-025 — provider-balanced for 2× fast-brain throughput;
-    Groq LPU's sub-1s TTFT is actually faster than NIM Qwen on average,
-    so this rotation is a strict win for fact-find / QA latency."""
-    return NimChainLLM(chain=_balanced_brain_chain(FAST_BRAIN_CHAIN), timeout=12.0,
+    FAST_BRAIN_CHAIN for fallback order.
+
+    KI-078 (2026-05-15) — per-link timeout tightened 12s → 6s. With a 22s
+    total chain budget and a 12s per-link, only 1 candidate could complete
+    before the budget expired — i.e. the fallback chain was effectively
+    dead. Groq LPU + NIM Nemotron Nano + NIM Qwen all hit TTFT in <2s on
+    healthy paths, so 6s catches a degraded link fast and lets the chain
+    try 3-4 candidates inside the 22s budget. The cold-start case (NIM
+    pool warm-up taking 10-15s) is still handled by the outer
+    fact_find_brain `_TIMEOUT_S=25s` wait_for + Groq's cross-provider link
+    which has no NIM cold-start exposure.
+
+    KI-025 — provider-balanced for 2× fast-brain throughput; Groq LPU's
+    sub-1s TTFT is actually faster than NIM Qwen on average, so this
+    rotation is a strict win for fact-find / QA latency."""
+    return NimChainLLM(chain=_balanced_brain_chain(FAST_BRAIN_CHAIN), timeout=6.0,
                        role="fast_brain", total_budget_s=22.0)