feat(llm-chain): KI-085 — proactive credit tracking; election gates by quota not just liveness

WHY: KI-084 (commit 119e0fd) demotes a candidate for 1h AFTER the first
HTTP 429 — that's REACTIVE. Cost: one user-facing failure per dead quota
before the elector knows to skip it. KI-085 is PROACTIVE: every probe +
every real call updates our view of remaining quota from response headers
+ provider endpoints; election filters by `is_alive AND has_credits`
BEFORE suggesting a primary, so a quota-exhausted Groq is sidelined the
moment headers say `remaining_tokens_day < 5000`, not after a 429 hits.

SIGNAL SOURCES (priority order):
1) GROQ — response headers on every successful call.
Parse `x-ratelimit-remaining-tokens-day` (the one that bit us today;
free-tier daily TPD cap) + `x-ratelimit-reset-tokens-day` (duration
string `"1h2m"` / bare seconds / unix epoch — all three shapes
handled). Low-water 5000 tokens (≥ one fact-find ~2K-input + ~400-
output round-trip with margin).
2) OPENROUTER — dedicated GET /api/v1/credits endpoint, polled every
~10 min from the probe loop (piggybacked on a tick counter so we
don't need a second long-running task). Low-water 0.05 USD
(5¢ safety margin). Per-call response headers stamp a between-poll
`requests_min` signal as a finer-grained backup.
3) NIM — no clean header. Local 60s rate-meter per candidate (deque of
monotonic success timestamps, trimmed on read). 40 req/min free-tier
cap; gate at >= 35 in-window calls (low-water 5 remaining-slots).
Window auto-resets via `credits_reset_at` 60s after oldest call.

ELECTION GATE (`_is_election_eligible`):
Existing checks (status != down, fresh probe, not in degraded sin-bin)
PLUS new `_has_credits(h, now_mono)`:
- reset_at elapsed → permissive (signal stale; next call refreshes)
- credits_remaining is None → permissive (cold-start)
- else gate on credits_remaining > credits_low_water
Skipped candidates are logged via `logging.info("election: skipping
{model} — credits {x}/{unit} below water {y}")`.

WIRING:
- GroqLLM.chat() + OpenRouterLLM.chat() get new `chain_name=` kw +
plumb it from NimChainLLM._get_worker_for(self._chain_name).
- After resp.raise_for_status() on success, providers call
`llm_health.update_credits_from_*(chain, model, dict(resp.headers))`.
- NimChainLLM._try() success path bumps `record_nim_call()` for any
NIM-prefixed candidate (also covered in the post-reprobe path).
- background_probe_loop runs `poll_openrouter_credits()` once on
startup + every OPENROUTER_CREDITS_POLL_EVERY_N_TICKS (2) ticks.

PERSISTENCE: 5 new fields on ModelHealth (credits_remaining /
credits_unit / credits_reset_at / credits_observed_at / credits_low_water)
+ `_load_into_memory` defaults each one to tolerate pre-KI-085 records.
status_summary surfaces credits to the admin UI.

TESTING (tests/test_credits_election.py — 11 inline scenarios):
- Groq header parser: 546 tokens (gated) / 50000 tokens (eligible) /
missing (no-op) / malformed (no-op + log) / reset string variants
(1h2m / 45s / 30m / "120" / "" / None).
- NIM rate-meter: 30 calls (eligible, 10 remaining), 36 calls (gated,
4 remaining), 60s-elapse stale-reset (eligible again).
- Election integration: groq with credits=100 below water → elector
picks NIM despite slower latency; groq with credits=10000 → elector
picks groq; credits=None (cold start) → eligible.
- test_routing_regression suite (15 cases) — green.

EXPECTED IMPACT (vs KI-084-only baseline):
- Zero user-facing 429s from daily-quota exhaustion: elector knows to
skip the candidate the moment its headers drop below 5K tokens.
- Same elector responsiveness post-reset: reset_at elapse flips the
candidate back to "permissive — None credits" without waiting for a
fresh probe, so quota that resets at midnight UTC is available on
the very next election.
- No new traffic to providers: Groq + OpenRouter signals are scraped
from existing response headers; the OpenRouter credits poll adds
one cheap GET every 10 min.

backend/llm_health.py

@@ -64,7 +64,9 @@ from __future__ import annotations
 
 import asyncio
 import json
+import logging
 import os
+import re
 import threading
 import time
 from dataclasses import dataclass, field, asdict
@@ -73,6 +75,8 @@ from typing import Optional
 
 import httpx
 
+logger = logging.getLogger(__name__)
+
 ROOT = Path(__file__).resolve().parent.parent
 HEALTH_FILE = ROOT / "40-data" / "llm_health.json"
 HEALTH_FILE.parent.mkdir(parents=True, exist_ok=True)
@@ -106,6 +110,31 @@ DEGRADED_WINDOW_SEC = 30          # report_failure sidelines a model this long
 # bouncing back to the dead candidate on every chat turn.
 DEGRADE_DURATION_LONG_S = 3600.0
 
+# KI-085 (2026-05-15) — proactive credit tracking. KI-084 demotes a candidate
+# for 1h AFTER a 429 hits; that costs one user-facing failure per dead quota.
+# KI-085 promotes llm_health to liveness+credits so election excludes
+# quota-exhausted candidates BEFORE the user gets stuck behind a 429.
+#
+# Three signal sources:
+#   1) GROQ — response headers (x-ratelimit-remaining-tokens-day etc.) on
+#      every successful Groq call. Low-water 5000 tokens (>= one fact-find
+#      ~2K-input + ~400-output round-trip with margin).
+#   2) OPENROUTER — dedicated GET /api/v1/credits endpoint, polled every
+#      10min from the probe loop. Low-water 0.05 USD (5¢ safety margin —
+#      OpenRouter free models charge $0 but the account-level signal still
+#      tells us if the user's prepaid credits are gone).
+#   3) NIM — no clean header. Local rate-meter: count successful calls in
+#      the last 60s. Free tier is 40 req/min; gate at >=35 to stay clear.
+GROQ_TOKENS_LOW_WATER = 5000.0          # tokens-per-day remaining
+OPENROUTER_USD_LOW_WATER = 0.05         # USD balance remaining
+NIM_REQ_PER_MIN_CAP = 40                # free-tier hard cap
+NIM_REQ_PER_MIN_HEADROOM = 5            # gate at cap - headroom = 35
+NIM_REQ_PER_MIN_LOW_WATER = 5.0         # below this remaining-in-window, gate
+
+# OpenRouter credits poll cadence — every ~10 min, piggybacked on the
+# probe loop tick counter. With PROBE_INTERVAL_SEC=300 that's every 2 ticks.
+OPENROUTER_CREDITS_POLL_EVERY_N_TICKS = 2
+
 # Per-provider endpoints + env-var names. The chain entries embed the
 # provider via a prefix ('openrouter:<id>' / 'groq:<id>'); unprefixed entries
 # fall through to NIM. Keep these dicts in sync with the providers in
@@ -182,6 +211,17 @@ class ModelHealth:
     # KI-080 — set by report_failure(); model is excluded from election
     # while monotonic time < degraded_until_monotonic.
     degraded_until_monotonic: float = 0.0
+    # KI-085 (2026-05-15) — proactive credit tracking. Stamped by
+    # update_credits_from_groq / update_credits_from_openrouter (response
+    # headers + account endpoint) and by the NIM local rate-meter. The
+    # elector gates on `credits_remaining is None OR > credits_low_water`
+    # so None (no signal yet) is permissive (cold-start = electable).
+    credits_remaining: Optional[float] = None    # tokens / USD / req-slots
+    credits_unit: Optional[str] = None           # "tokens_day" / "tokens_min" /
+                                                 # "usd_balance" / "requests_min"
+    credits_reset_at: Optional[float] = None     # monotonic time when quota resets
+    credits_observed_at: Optional[float] = None  # monotonic time of snapshot
+    credits_low_water: float = 0.0               # below this, gated out
 
 
 def _now_iso() -> str:
@@ -248,9 +288,15 @@ def _load_into_memory() -> None:
                 raw = json.loads(HEALTH_FILE.read_text())
                 for k, v in raw.get("models", {}).items():
                     # Tolerate older schema (pre-KI-080 records missing
-                    # probe_history / degraded_until_monotonic).
+                    # probe_history / degraded_until_monotonic; pre-KI-085
+                    # records missing the five credits_* fields).
                     v.setdefault("probe_history", [])
                     v.setdefault("degraded_until_monotonic", 0.0)
+                    v.setdefault("credits_remaining", None)
+                    v.setdefault("credits_unit", None)
+                    v.setdefault("credits_reset_at", None)
+                    v.setdefault("credits_observed_at", None)
+                    v.setdefault("credits_low_water", 0.0)
                     _STATE[k] = ModelHealth(**v)
             except Exception:
                 _STATE = {}
@@ -314,6 +360,8 @@ def _is_election_eligible(h: ModelHealth, now_mono: float) -> bool:
       - status is healthy (or degraded with a recent success)
       - last probe was within HEALTHY_PROBE_AGE_SEC
       - it is NOT currently in the degraded-window sin-bin
+      - KI-085 (2026-05-15): it has credits remaining above its low-water
+        mark, OR no credit signal yet (cold-start = permissive).
     """
     if h.degraded_until_monotonic > now_mono:
         return False
@@ -324,9 +372,34 @@ def _is_election_eligible(h: ModelHealth, now_mono: float) -> bool:
         return False
     if h.latency_ms is None:
         return False
+    if not _has_credits(h, now_mono):
+        logger.info(
+            "election: skipping %s — credits %s/%s below water %s",
+            h.model, h.credits_remaining, h.credits_unit, h.credits_low_water,
+        )
+        return False
     return True
 
 
+def _has_credits(h: ModelHealth, now_mono: float) -> bool:
+    """KI-085 — credit-gate predicate for election eligibility.
+
+    Rules:
+      - If `credits_reset_at` has elapsed, treat the signal as stale and
+        permissive (next call will refresh). We don't auto-zero the
+        snapshot here so other readers (admin UI / status_summary) still
+        see the LAST observed value with its observed_at timestamp.
+      - If `credits_remaining is None` (no signal yet), return True —
+        cold-start must not penalize a fresh candidate.
+      - Otherwise gate on `credits_remaining > credits_low_water`.
+    """
+    if h.credits_reset_at is not None and now_mono >= h.credits_reset_at:
+        return True
+    if h.credits_remaining is None:
+        return True
+    return h.credits_remaining > h.credits_low_water
+
+
 def _ranked_candidates(chain_name: str) -> list[ModelHealth]:
     """Return the chain's election-eligible candidates, best-score first."""
     _load_into_memory()
@@ -491,6 +564,291 @@ async def _reprobe_one(model: str) -> None:
         pass
 
 
+# ---------------------------------------------------------------------------
+# KI-085 — proactive credit tracking. Three signal sources:
+#   (1) Groq response headers (per-call, real-time)
+#   (2) OpenRouter dedicated /credits endpoint (10-min poll)
+#   (3) NIM local rate-meter (no clean header; count successes in last 60s)
+# ---------------------------------------------------------------------------
+
+# Match formats observed in the wild for Groq reset headers. Three shapes
+# coexist on the Groq API:
+#   - duration string: "1h2m"  /  "30m"  /  "45s"  /  "1h2m30s"
+#   - bare seconds-from-now (float-ish): "60.5"  /  "3600"
+#   - epoch unix seconds (only when value is large enough): "1747326123"
+_DURATION_RE = re.compile(r"^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+(?:\.\d+)?)s)?$")
+
+
+def _parse_reset_seconds(raw: Optional[str], now_mono: float) -> Optional[float]:
+    """Parse a Groq-style reset header into a monotonic deadline.
+
+    Returns the monotonic timestamp at which the quota resets (or None
+    when the value is missing/malformed). Accepts three shapes:
+      - "1h2m30s" / "30m" / "60s"   → seconds offset from now
+      - "60.5"                       → seconds offset (bare numeric)
+      - "1747326123"                 → unix epoch (treated as absolute
+                                       wall-clock; converted to monotonic
+                                       relative to current time.time()).
+    """
+    if raw is None:
+        return None
+    s = raw.strip()
+    if not s:
+        return None
+    # Duration string ("1h2m" / "30m45s" / "45s")
+    m = _DURATION_RE.match(s)
+    if m and any(m.groups()):
+        h = int(m.group(1) or 0)
+        mn = int(m.group(2) or 0)
+        sec = float(m.group(3) or 0)
+        offset = h * 3600 + mn * 60 + sec
+        if offset > 0:
+            return now_mono + offset
+        return None
+    # Bare numeric — seconds-from-now or unix epoch
+    try:
+        v = float(s)
+    except ValueError:
+        return None
+    # Heuristic: > 1e9 means it's almost certainly a unix epoch (after 2001).
+    # Convert to seconds-from-now first, then to monotonic.
+    if v > 1e9:
+        offset = v - time.time()
+        if offset <= 0:
+            return now_mono  # already reset
+        return now_mono + offset
+    if v <= 0:
+        return None
+    return now_mono + v
+
+
+def update_credits_from_groq(chain_name: str, model: str, headers: dict) -> None:
+    """Stamp credits_remaining from a Groq response's x-ratelimit-* headers.
+
+    Called from GroqLLM.chat() after a successful HTTP response. The
+    `headers` dict is the response's headers (case-insensitive via httpx).
+    We prefer the DAILY tokens signal (`x-ratelimit-remaining-tokens-day`)
+    because Groq's free-tier daily TPD cap is what bit us in KI-084.
+
+    Missing header → no-op. Malformed value → log warning + no-op.
+    """
+    if not headers:
+        return
+    # httpx headers are case-insensitive; index defensively for plain dicts.
+    def _h(k: str) -> Optional[str]:
+        try:
+            v = headers.get(k)
+        except AttributeError:
+            return None
+        if v is not None:
+            return v
+        # Plain dict fallback — case-fold lookup.
+        for hk, hv in headers.items():
+            if hk.lower() == k.lower():
+                return hv
+        return None
+
+    remaining_raw = _h("x-ratelimit-remaining-tokens-day")
+    reset_raw = _h("x-ratelimit-reset-tokens-day")
+
+    if remaining_raw is None:
+        # No daily-tokens header — Groq sometimes only sends the minute
+        # window; that's not the signal we care about for KI-085 (KI-084's
+        # 1h sin-bin already covers minute-window blips).
+        return
+
+    try:
+        remaining = float(remaining_raw)
+    except (TypeError, ValueError):
+        logger.warning(
+            "update_credits_from_groq: malformed remaining value %r for %s",
+            remaining_raw, model,
+        )
+        return
+
+    now_mono = time.monotonic()
+    reset_at = _parse_reset_seconds(reset_raw, now_mono)
+
+    _load_into_memory()
+    with _STATE_LOCK:
+        h = _STATE.get(model) or ModelHealth(model=model)
+        h.credits_remaining = remaining
+        h.credits_unit = "tokens_day"
+        h.credits_reset_at = reset_at
+        h.credits_observed_at = now_mono
+        h.credits_low_water = GROQ_TOKENS_LOW_WATER
+        _STATE[model] = h
+
+
+def update_credits_from_openrouter_headers(chain_name: str, model: str, headers: dict) -> None:
+    """OpenRouter sometimes surfaces per-call remaining credits on response
+    headers (`x-ratelimit-remaining` etc.). Lower fidelity than the
+    dedicated /credits endpoint but useful as a between-poll signal so the
+    elector reacts inside the 10-min poll window.
+
+    Header shape varies by model — we accept `x-ratelimit-remaining` (raw
+    count, no unit semantics) and treat it as request-slots so the gate
+    catches a near-empty bucket. Missing header → no-op.
+    """
+    if not headers:
+        return
+
+    def _h(k: str) -> Optional[str]:
+        try:
+            v = headers.get(k)
+        except AttributeError:
+            return None
+        if v is not None:
+            return v
+        for hk, hv in headers.items():
+            if hk.lower() == k.lower():
+                return hv
+        return None
+
+    remaining_raw = _h("x-ratelimit-remaining")
+    if remaining_raw is None:
+        return
+    try:
+        remaining = float(remaining_raw)
+    except (TypeError, ValueError):
+        logger.warning(
+            "update_credits_from_openrouter_headers: malformed remaining value %r for %s",
+            remaining_raw, model,
+        )
+        return
+
+    now_mono = time.monotonic()
+    _load_into_memory()
+    with _STATE_LOCK:
+        h = _STATE.get(model) or ModelHealth(model=model)
+        # Only stamp from headers if we DON'T already have a fresher
+        # account-level signal from the dedicated endpoint. usd_balance is
+        # the authoritative truth for OpenRouter; per-call requests_min is
+        # a between-poll approximation.
+        if h.credits_unit != "usd_balance":
+            h.credits_remaining = remaining
+            h.credits_unit = "requests_min"
+            h.credits_observed_at = now_mono
+            # Low-water: stay 5 slots above zero so a near-empty bucket
+            # gates out the candidate.
+            h.credits_low_water = float(NIM_REQ_PER_MIN_LOW_WATER)
+            _STATE[model] = h
+
+
+# NIM local rate-meter (no clean header). Per-chain-entry deque of monotonic
+# success timestamps; we trim to last 60s on each read.
+_NIM_CALL_TIMES_LOCK = threading.Lock()
+_NIM_CALL_TIMES: dict[str, list[float]] = {}
+
+
+def record_nim_call(chain_name: str, model: str) -> None:
+    """Bump the local NIM rate-meter on a successful call. Also stamps
+    credits_remaining on the ModelHealth so the elector can gate.
+
+    NIM free tier = 40 req/min per API key. We gate at >= 35 in-window
+    calls (`NIM_REQ_PER_MIN_CAP - NIM_REQ_PER_MIN_HEADROOM`) so the
+    elector sidelines the candidate before we burn the cap.
+    """
+    if not model:
+        return
+    now_mono = time.monotonic()
+    cutoff = now_mono - 60.0
+    with _NIM_CALL_TIMES_LOCK:
+        times = _NIM_CALL_TIMES.get(model, [])
+        times = [t for t in times if t > cutoff]
+        times.append(now_mono)
+        _NIM_CALL_TIMES[model] = times
+        in_window = len(times)
+
+    remaining = max(0.0, float(NIM_REQ_PER_MIN_CAP - in_window))
+    # Window resets 60s after the OLDEST in-window call.
+    reset_at = (times[0] + 60.0) if times else (now_mono + 60.0)
+
+    _load_into_memory()
+    with _STATE_LOCK:
+        h = _STATE.get(model) or ModelHealth(model=model)
+        h.credits_remaining = remaining
+        h.credits_unit = "requests_min"
+        h.credits_reset_at = reset_at
+        h.credits_observed_at = now_mono
+        h.credits_low_water = float(NIM_REQ_PER_MIN_LOW_WATER)
+        _STATE[model] = h
+
+
+async def poll_openrouter_credits() -> Optional[dict]:
+    """Hit GET https://openrouter.ai/api/v1/credits and stamp every
+    OpenRouter-prefixed candidate with the account-level USD balance.
+
+    Returns the parsed `{total_credits, total_usage}` dict on success, or
+    None on any failure (missing key / HTTP error / parse fail). Best-
+    effort: never raises. Called from background_probe_loop on a counter
+    every OPENROUTER_CREDITS_POLL_EVERY_N_TICKS ticks.
+    """
+    api_key = os.environ.get("OPENROUTER_API_KEY", "")
+    if not api_key:
+        return None
+    url = "https://openrouter.ai/api/v1/credits"
+    headers = {"Authorization": f"Bearer {api_key}"}
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            r = await client.get(url, headers=headers)
+            if r.status_code != 200:
+                logger.info(
+                    "poll_openrouter_credits: HTTP %d — skipping update",
+                    r.status_code,
+                )
+                return None
+            payload = r.json()
+    except Exception as e:
+        logger.info("poll_openrouter_credits: exception %s — skipping update", type(e).__name__)
+        return None
+
+    data = payload.get("data") or payload
+    try:
+        total_credits = float(data.get("total_credits", 0.0))
+        total_usage = float(data.get("total_usage", 0.0))
+    except (TypeError, ValueError):
+        logger.warning("poll_openrouter_credits: malformed payload %r", payload)
+        return None
+
+    remaining = max(0.0, total_credits - total_usage)
+    now_mono = time.monotonic()
+
+    _load_into_memory()
+    # Stamp every OpenRouter-prefixed candidate in every known chain.
+    with _STATE_LOCK:
+        for model in list(_STATE.keys()):
+            if not model.startswith("openrouter:"):
+                continue
+            h = _STATE[model]
+            h.credits_remaining = remaining
+            h.credits_unit = "usd_balance"
+            # OpenRouter credits don't auto-reset on a clock — they're a
+            # prepaid wallet. Use None to mean "no scheduled reset"; the
+            # elector treats None reset_at as a static gate (recheck on
+            # every election; refreshed by next poll).
+            h.credits_reset_at = None
+            h.credits_observed_at = now_mono
+            h.credits_low_water = OPENROUTER_USD_LOW_WATER
+            _STATE[model] = h
+        # Also seed entries that haven't been probed yet (chain entries
+        # discovered at import time but no probe completed).
+        for chain_model in _all_known_models():
+            if not chain_model.startswith("openrouter:"):
+                continue
+            if chain_model in _STATE:
+                continue
+            h = ModelHealth(model=chain_model)
+            h.credits_remaining = remaining
+            h.credits_unit = "usd_balance"
+            h.credits_observed_at = now_mono
+            h.credits_low_water = OPENROUTER_USD_LOW_WATER
+            _STATE[chain_model] = h
+
+    return {"total_credits": total_credits, "total_usage": total_usage,
+            "remaining": remaining}
+
+
 # ---------------------------------------------------------------------------
 # Probing (mostly unchanged from pre-KI-080 — extended to record
 # probe_history + skip degraded-window models on the regular tick).
@@ -639,6 +997,10 @@ def status_summary() -> dict:
             "last_failure_at": h.last_failure_at,
             "last_error": h.last_error,
             "tested_at": h.tested_at,
+            # KI-085 — surface credits state for the admin UI.
+            "credits_remaining": h.credits_remaining,
+            "credits_unit": h.credits_unit,
+            "credits_low_water": h.credits_low_water,
         })
     summary["models"].sort(key=lambda x: (x["status"] != "healthy", x["model"]))
     if summary["models"]:
@@ -654,12 +1016,32 @@ def status_summary() -> dict:
 
 async def background_probe_loop() -> None:
     """Long-running task — probes every PROBE_INTERVAL_SEC (300s; KI-084).
-    Started from main.py."""
+    Started from main.py.
+
+    KI-085 (2026-05-15) — also polls OpenRouter's account-level credits
+    endpoint every OPENROUTER_CREDITS_POLL_EVERY_N_TICKS ticks (10 min by
+    default at the 300s probe cadence). Groq + NIM signals come from the
+    chat hot path (response headers + local rate-meter respectively) so
+    only OpenRouter needs an out-of-band poll.
+    """
+    tick = 0
+    # Initial credits poll on startup so the elector has a non-None
+    # account-level signal before the first chat call.
+    try:
+        await poll_openrouter_credits()
+    except Exception:
+        pass
     while True:
         try:
             await probe_all()
         except Exception:
             pass  # never let one bad probe kill the loop
+        tick += 1
+        if tick % OPENROUTER_CREDITS_POLL_EVERY_N_TICKS == 0:
+            try:
+                await poll_openrouter_credits()
+            except Exception:
+                pass
         await asyncio.sleep(PROBE_INTERVAL_SEC)
 
 

backend/providers/groq_llm.py

@@ -45,10 +45,14 @@ class GroqLLM(LLMProvider):
         model: str = DEFAULT_MODEL,
         api_key: Optional[str] = None,
         timeout: float = 120.0,
+        chain_name: str = "unknown",
     ):
         self.api_key = api_key or getattr(settings, "GROQ_API_KEY", "")
         self.model = model
         self.timeout = timeout
+        # KI-085 — chain_name plumbs through so update_credits_from_groq
+        # can route the response-header signal to the right chain state.
+        self.chain_name = chain_name
         if not self.api_key:
             raise RuntimeError(
                 "GROQ_API_KEY not set. Get a key at https://console.groq.com/keys "
@@ -100,6 +104,21 @@ class GroqLLM(LLMProvider):
                     continue
                 resp.raise_for_status()
                 break
+            # KI-085 (2026-05-15) — stamp credits_remaining from Groq's
+            # x-ratelimit-* headers BEFORE we drop the response. Groq is
+            # the highest-fidelity provider on this front: every successful
+            # call returns the daily-tokens remaining, so we get a
+            # continuously-updated election signal at zero extra cost.
+            try:
+                from backend import llm_health
+                chain_for_credits = (
+                    f"groq:{self.model}"  # chain entries are prefixed
+                )
+                llm_health.update_credits_from_groq(
+                    self.chain_name, chain_for_credits, dict(resp.headers)
+                )
+            except Exception:
+                pass  # credit tracking must never break the chat path
             payload = resp.json()
 
         choice = payload["choices"][0]

backend/providers/nvidia_nim_llm.py

@@ -384,16 +384,22 @@ class NimChainLLM(LLMProvider):
           - 'openrouter:<model>' -> OpenRouterLLM
           - 'groq:<model>'       -> GroqLLM
           - <anything else>      -> NvidiaNimLLM (existing default)
+
+        KI-085 — passes `chain_name=self._chain_name` so the credit
+        trackers in the provider clients route their response-header
+        signals to the right chain state.
         """
         if model_id.startswith("openrouter:"):
             return OpenRouterLLM(
                 model=model_id[len("openrouter:"):],
                 timeout=timeout,
+                chain_name=self._chain_name,
             )
         if model_id.startswith("groq:"):
             return GroqLLM(
                 model=model_id[len("groq:"):],
                 timeout=timeout,
+                chain_name=self._chain_name,
             )
         return NvidiaNimLLM(model=model_id, api_key=self.api_key, timeout=timeout)
 
@@ -578,6 +584,16 @@ class NimChainLLM(LLMProvider):
                 llm_health.report_success(self._chain_name, model, latency_ms)
             except Exception:
                 pass
+            # KI-085 (2026-05-15) — NIM has no clean rate-limit header, so
+            # we maintain a local 60s rate-meter for every NIM-prefixed
+            # candidate (i.e. anything without an openrouter:/groq: prefix).
+            # Groq + OpenRouter stamp credits from response headers inside
+            # their own .chat() methods.
+            if not model.startswith(("openrouter:", "groq:")):
+                try:
+                    llm_health.record_nim_call(self._chain_name, model)
+                except Exception:
+                    pass
             self.model = model
             self.name = f"nim-chain::{self._short_id(model)}"
             total_ms = int((time.time() - call_t0) * 1000)
@@ -650,6 +666,12 @@ class NimChainLLM(LLMProvider):
                     )
                 except Exception:
                     pass
+                # KI-085 — bump NIM rate-meter on post-reprobe successes too.
+                if not model.startswith(("openrouter:", "groq:")):
+                    try:
+                        llm_health.record_nim_call(self._chain_name, model)
+                    except Exception:
+                        pass
                 self.model = model
                 self.name = f"nim-chain::{self._short_id(model)}"
                 total_ms = int((time.time() - call_t0) * 1000)

backend/providers/openrouter_llm.py

@@ -48,10 +48,13 @@ class OpenRouterLLM(LLMProvider):
         model: str = DEFAULT_MODEL,
         api_key: Optional[str] = None,
         timeout: float = 120.0,
+        chain_name: str = "unknown",
     ):
         self.api_key = api_key or getattr(settings, "OPENROUTER_API_KEY", "")
         self.model = model
         self.timeout = timeout
+        # KI-085 — chain_name plumbs through to update_credits_*.
+        self.chain_name = chain_name
         if not self.api_key:
             raise RuntimeError(
                 "OPENROUTER_API_KEY not set. Get a key at https://openrouter.ai/keys "
@@ -109,6 +112,19 @@ class OpenRouterLLM(LLMProvider):
                     continue
                 resp.raise_for_status()
                 break
+            # KI-085 (2026-05-15) — opportunistic between-poll signal from
+            # OpenRouter response headers. The authoritative truth (usd_balance)
+            # comes from poll_openrouter_credits() every 10 min; this is a
+            # finer-grained per-call backup that catches per-minute bucket
+            # exhaustion before the next poll tick.
+            try:
+                from backend import llm_health
+                chain_for_credits = f"openrouter:{self.model}"
+                llm_health.update_credits_from_openrouter_headers(
+                    self.chain_name, chain_for_credits, dict(resp.headers)
+                )
+            except Exception:
+                pass
             payload = resp.json()
 
         choice = payload["choices"][0]

tests/test_credits_election.py

@@ -0,0 +1,210 @@
+"""KI-085 (2026-05-15) — proactive credit tracking + election gate.
+
+Tests:
+  1. update_credits_from_groq parser variants (valid / threshold / missing / malformed)
+  2. NIM local rate-meter increments + 60s reset
+  3. _is_election_eligible gates by credits_remaining vs credits_low_water
+  4. elect_primary_and_backup integration: credit-exhausted candidates skipped
+
+Run:
+    .venv/bin/python -m unittest tests.test_credits_election -v
+"""
+
+from __future__ import annotations
+
+import time
+import unittest
+from unittest import mock
+
+from backend import llm_health
+from backend.llm_health import (
+    GROQ_TOKENS_LOW_WATER,
+    ModelHealth,
+    NIM_REQ_PER_MIN_LOW_WATER,
+    _has_credits,
+    _is_election_eligible,
+    record_nim_call,
+    update_credits_from_groq,
+)
+
+
+def _fresh_state():
+    """Wipe in-memory state + mark loaded so tests don't trigger disk reads."""
+    llm_health._STATE.clear()
+    llm_health._STATE_LOADED = True
+    llm_health._NIM_CALL_TIMES.clear()
+
+
+def _healthy_now(model: str) -> ModelHealth:
+    """Build a ModelHealth that passes every check EXCEPT credits — so
+    flipping credits is the only failure surface in these tests."""
+    h = ModelHealth(model=model)
+    h.status = "healthy"
+    h.latency_ms = 200
+    h.tested_at = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    return h
+
+
+class TestGroqHeaderParser(unittest.TestCase):
+    def setUp(self) -> None:
+        _fresh_state()
+
+    def test_546_tokens_remaining_gates_out(self) -> None:
+        """546 < 5000 low water → credit-gate fails."""
+        model = "groq:llama-3.3-70b-versatile"
+        update_credits_from_groq("brain", model, {
+            "x-ratelimit-remaining-tokens-day": "546",
+            "x-ratelimit-reset-tokens-day": "1h2m",
+        })
+        h = llm_health._STATE[model]
+        self.assertEqual(h.credits_remaining, 546.0)
+        self.assertEqual(h.credits_unit, "tokens_day")
+        self.assertEqual(h.credits_low_water, GROQ_TOKENS_LOW_WATER)
+        self.assertFalse(_has_credits(h, time.monotonic()))
+
+    def test_50000_tokens_remaining_is_eligible(self) -> None:
+        """50K >> 5K low water → credit-gate passes."""
+        model = "groq:llama-3.3-70b-versatile"
+        update_credits_from_groq("brain", model, {
+            "x-ratelimit-remaining-tokens-day": "50000",
+            "x-ratelimit-reset-tokens-day": "5h",
+        })
+        h = llm_health._STATE[model]
+        self.assertEqual(h.credits_remaining, 50000.0)
+        self.assertTrue(_has_credits(h, time.monotonic()))
+
+    def test_missing_header_is_noop(self) -> None:
+        """No daily-tokens header → state untouched (credits_remaining stays None)."""
+        model = "groq:llama-3.3-70b-versatile"
+        update_credits_from_groq("brain", model, {})
+        self.assertNotIn(model, llm_health._STATE)
+
+    def test_malformed_value_is_noop(self) -> None:
+        """Garbage in the header → no-op + warning logged (not raised)."""
+        model = "groq:llama-3.3-70b-versatile"
+        update_credits_from_groq("brain", model, {
+            "x-ratelimit-remaining-tokens-day": "not-a-number",
+        })
+        # State remains absent because update bailed before stamping.
+        self.assertNotIn(model, llm_health._STATE)
+
+    def test_reset_string_parses_duration(self) -> None:
+        """`1h2m` → ~3720s offset; `45s` → ~45s offset; `30m` → ~1800s."""
+        now_mono = time.monotonic()
+        from backend.llm_health import _parse_reset_seconds
+        v = _parse_reset_seconds("1h2m", now_mono)
+        self.assertIsNotNone(v)
+        self.assertAlmostEqual(v - now_mono, 3720, delta=2)
+        v = _parse_reset_seconds("45s", now_mono)
+        self.assertAlmostEqual(v - now_mono, 45, delta=2)
+        v = _parse_reset_seconds("30m", now_mono)
+        self.assertAlmostEqual(v - now_mono, 1800, delta=2)
+        # Bare seconds-from-now
+        v = _parse_reset_seconds("120", now_mono)
+        self.assertAlmostEqual(v - now_mono, 120, delta=2)
+        # Empty / None
+        self.assertIsNone(_parse_reset_seconds("", now_mono))
+        self.assertIsNone(_parse_reset_seconds(None, now_mono))
+
+
+class TestNimRateMeter(unittest.TestCase):
+    def setUp(self) -> None:
+        _fresh_state()
+
+    def test_30_calls_in_60s_eligible(self) -> None:
+        """30 successful calls → 40-30=10 remaining, > 5 low water → eligible."""
+        model = "qwen/qwen3-next-80b-a3b-instruct"
+        for _ in range(30):
+            record_nim_call("brain", model)
+        h = llm_health._STATE[model]
+        self.assertEqual(h.credits_remaining, 10.0)
+        self.assertEqual(h.credits_unit, "requests_min")
+        self.assertTrue(_has_credits(h, time.monotonic()))
+
+    def test_36_calls_in_60s_gated_out(self) -> None:
+        """36 successful calls → 40-36=4 remaining, < 5 low water → gated."""
+        model = "qwen/qwen3-next-80b-a3b-instruct"
+        for _ in range(36):
+            record_nim_call("brain", model)
+        h = llm_health._STATE[model]
+        self.assertEqual(h.credits_remaining, 4.0)
+        self.assertFalse(_has_credits(h, time.monotonic()))
+
+    def test_60s_window_resets(self) -> None:
+        """After 60s elapses, _has_credits flips back to True via stale-reset."""
+        model = "qwen/qwen3-next-80b-a3b-instruct"
+        for _ in range(36):
+            record_nim_call("brain", model)
+        h = llm_health._STATE[model]
+        self.assertFalse(_has_credits(h, time.monotonic()))
+        # Simulate 65 seconds passing: credits_reset_at is now in the past.
+        future_now = (h.credits_reset_at or time.monotonic()) + 5.0
+        self.assertTrue(_has_credits(h, future_now))
+
+
+class TestElectionCreditGate(unittest.TestCase):
+    """Integration: elect_primary skips quota-exhausted candidates."""
+
+    def setUp(self) -> None:
+        _fresh_state()
+
+    def test_groq_below_water_skipped_in_election(self) -> None:
+        """Groq has fast probe latency but is below daily-tokens water →
+        elector falls through to next candidate."""
+        groq_model = "groq:llama-3.3-70b-versatile"
+        nim_model = "qwen/qwen3-next-80b-a3b-instruct"
+        # Both healthy + fresh probe + low latency. Groq is faster (100ms).
+        gh = _healthy_now(groq_model)
+        gh.latency_ms = 100
+        gh.credits_remaining = 100.0  # < 5000 low_water
+        gh.credits_unit = "tokens_day"
+        gh.credits_low_water = GROQ_TOKENS_LOW_WATER
+        gh.credits_observed_at = time.monotonic()
+        llm_health._STATE[groq_model] = gh
+
+        nh = _healthy_now(nim_model)
+        nh.latency_ms = 300
+        llm_health._STATE[nim_model] = nh
+
+        with mock.patch.object(
+            llm_health, "_chain_for", return_value=[groq_model, nim_model]
+        ):
+            primary = llm_health.get_primary("brain")
+        self.assertEqual(primary, nim_model,
+                         "Quota-exhausted Groq should be skipped despite faster latency.")
+
+    def test_groq_above_water_picked_in_election(self) -> None:
+        """Groq has plenty of credits → elector picks it (fastest healthy)."""
+        groq_model = "groq:llama-3.3-70b-versatile"
+        nim_model = "qwen/qwen3-next-80b-a3b-instruct"
+        gh = _healthy_now(groq_model)
+        gh.latency_ms = 100
+        gh.credits_remaining = 10000.0  # >> 5000 low_water
+        gh.credits_unit = "tokens_day"
+        gh.credits_low_water = GROQ_TOKENS_LOW_WATER
+        gh.credits_observed_at = time.monotonic()
+        llm_health._STATE[groq_model] = gh
+
+        nh = _healthy_now(nim_model)
+        nh.latency_ms = 300
+        llm_health._STATE[nim_model] = nh
+
+        with mock.patch.object(
+            llm_health, "_chain_for", return_value=[groq_model, nim_model]
+        ):
+            primary = llm_health.get_primary("brain")
+        self.assertEqual(primary, groq_model,
+                         "Healthy + credit-rich Groq should win election.")
+
+    def test_none_credits_is_permissive(self) -> None:
+        """Cold-start: a candidate with credits_remaining=None must be electable."""
+        model = "qwen/qwen3-next-80b-a3b-instruct"
+        h = _healthy_now(model)
+        # credits_remaining is None by default — leave it alone.
+        llm_health._STATE[model] = h
+        self.assertTrue(_is_election_eligible(h, time.monotonic()),
+                        "Cold-start (None credits) must NOT gate out a healthy candidate.")
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)