seiche 0.7.0__tar.gz

seiche-0.7.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: seiche
+Version: 0.7.0
+Summary: Funding-stress and leveraged-positioning early-warning terminal (money market + capital market), built on free keyless public APIs.
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: scipy>=1.11
+Requires-Dist: arch>=7
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-memray>=1.7; sys_platform != "win32" and extra == "dev"
+Requires-Dist: pytest-pystack>=1.0; sys_platform == "linux" and extra == "dev"
+Provides-Extra: notary
+Requires-Dist: opentimestamps>=0.4; extra == "notary"
+
+# Seiche
+
+Funding-stress early warning for US money markets, built entirely from free,
+keyless public data (Fed H.4.1, NY Fed operations, OFR repo, Treasury cash). It
+reads the plumbing so you don't have to: one stress board, honest backtests,
+published misses, updated twice a day.
+
+Full project, the terminal UI, and deployment: https://github.com/beepboop2025/seiche
+Live: https://seiche.info
+
+## As an agent tool (MCP)
+
+Seiche is a Model Context Protocol server. Any MCP-capable agent can read the
+live board as tools — the current stress regime, forward event odds, historical
+analogs, and the honest backtest.
+
+```bash
+pip install seiche
+seiche-mcp                 # stdio MCP server
+```
+
+Or connect to the hosted, metered endpoint at `https://api.seiche.info/mcp`.
+See [docs/MCP.md](https://github.com/beepboop2025/seiche/blob/main/docs/MCP.md).
+
+mcp-name: io.github.beepboop2025/seiche

seiche-0.7.0/README.md

@@ -0,0 +1,25 @@
+# Seiche
+
+Funding-stress early warning for US money markets, built entirely from free,
+keyless public data (Fed H.4.1, NY Fed operations, OFR repo, Treasury cash). It
+reads the plumbing so you don't have to: one stress board, honest backtests,
+published misses, updated twice a day.
+
+Full project, the terminal UI, and deployment: https://github.com/beepboop2025/seiche
+Live: https://seiche.info
+
+## As an agent tool (MCP)
+
+Seiche is a Model Context Protocol server. Any MCP-capable agent can read the
+live board as tools — the current stress regime, forward event odds, historical
+analogs, and the honest backtest.
+
+```bash
+pip install seiche
+seiche-mcp                 # stdio MCP server
+```
+
+Or connect to the hosted, metered endpoint at `https://api.seiche.info/mcp`.
+See [docs/MCP.md](https://github.com/beepboop2025/seiche/blob/main/docs/MCP.md).
+
+mcp-name: io.github.beepboop2025/seiche

seiche-0.7.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "seiche"
+version = "0.7.0"
+description = "Funding-stress and leveraged-positioning early-warning terminal (money market + capital market), built on free keyless public APIs."
+readme = "README.md"
+license = "AGPL-3.0-or-later"
+# 3.12+ only: the MCP bridge calls the async assembler via asyncio.run() per
+# call, and on 3.10/3.11 the module-level asyncio.Lock in assemble.py raises
+# "bound to a different event loop" across loops. 3.12 relaxed that binding;
+# prod runs 3.12. Keep this floor so a PyPI install can't land on 3.11.
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "httpx>=0.27",
+    "numpy>=1.26",
+    "pandas>=2.2",
+    "scikit-learn>=1.4",
+    "scipy>=1.11",        # microseism MLE (was transitive via sklearn; now direct)
+    "arch>=7",            # regatta: Model Confidence Set bootstrap
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-memray>=1.7; sys_platform != 'win32'",
+    "pytest-pystack>=1.0; sys_platform == 'linux'",
+]
+notary = ["opentimestamps>=0.4"]   # Bitcoin anchoring for the record ledger
+
+[project.scripts]
+seiche = "seiche.cli:main"
+seiche-mcp = "seiche.mcp_server:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["seiche*"]

seiche-0.7.0/seiche/accounts.py

@@ -0,0 +1,163 @@
+"""Subscriber accounts — stdlib-only auth for the gated endpoints.
+
+The public window (api.seiche.info) serves the live board to everyone; the
+Time Machine replay is the subscriber feature. Design matches the project's
+ethos: no new dependencies, fail loud, nothing clever.
+
+  * passwords: hashlib.scrypt (n=2^14, r=8, p=1), per-user 16-byte salt;
+  * tokens: HMAC-SHA256 over "username|tier|expiry" with a secret that lives
+    in DATA_DIR/auth_secret (created 0600 on first use) or SEICHE_AUTH_SECRET;
+  * the gate is OPT-IN: SEICHE_ASOF_AUTH=1 turns it on (the box); dev and
+    tests run open unless they say otherwise.
+
+Accounts are provisioned by the operator (`seiche user add NAME`), not by
+self-signup — payments come later; this is the lock, not the till.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import sqlite3
+import time
+
+from seiche.config import DATA_DIR, DB_PATH
+
+_SCRYPT = dict(n=2**14, r=8, p=1)
+TOKEN_TTL_S = 30 * 24 * 3600  # 30 days
+
+
+def _conn() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB_PATH)
+    conn.execute(
+        """CREATE TABLE IF NOT EXISTS users (
+               username TEXT PRIMARY KEY,
+               salt_hex TEXT NOT NULL,
+               hash_hex TEXT NOT NULL,
+               tier TEXT NOT NULL DEFAULT 'pro',
+               created_utc REAL NOT NULL
+           )"""
+    )
+    # idempotent migration: subscriber alert prefs
+    cols = {r[1] for r in conn.execute("PRAGMA table_info(users)")}
+    if "email" not in cols:
+        conn.execute("ALTER TABLE users ADD COLUMN email TEXT DEFAULT ''")
+    if "alerts_on" not in cols:
+        conn.execute("ALTER TABLE users ADD COLUMN alerts_on INTEGER DEFAULT 0")
+    return conn
+
+
+def _secret() -> bytes:
+    env = os.getenv("SEICHE_AUTH_SECRET")
+    if env:
+        return env.encode()
+    path = DATA_DIR / "auth_secret"
+    if not path.exists():
+        path.write_text(secrets.token_hex(32))
+        os.chmod(path, 0o600)
+    return path.read_text().strip().encode()
+
+
+def _hash(password: str, salt: bytes) -> str:
+    return hashlib.scrypt(password.encode(), salt=salt, **_SCRYPT).hex()
+
+
+def add_user(username: str, password: str, tier: str = "pro") -> None:
+    if not username or not username.replace("_", "").replace("-", "").isalnum():
+        raise ValueError("username must be alphanumeric (plus - _)")
+    if len(password) < 10:
+        raise ValueError("password must be at least 10 characters")
+    salt = os.urandom(16)
+    with _conn() as conn:
+        conn.execute(
+            "INSERT OR REPLACE INTO users (username, salt_hex, hash_hex, tier, created_utc) "
+            "VALUES (?,?,?,?,?)",
+            (username, salt.hex(), _hash(password, salt), tier, time.time()),
+        )
+
+
+def verify_user(username: str, password: str) -> dict | None:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT salt_hex, hash_hex, tier FROM users WHERE username=?", (username,)
+        ).fetchone()
+    if row is None:
+        return None
+    salt_hex, hash_hex, tier = row
+    if hmac.compare_digest(_hash(password, bytes.fromhex(salt_hex)), hash_hex):
+        return {"username": username, "tier": tier}
+    return None
+
+
+def user_exists(username: str) -> bool:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT 1 FROM users WHERE username=?", (username,)
+        ).fetchone()
+    return row is not None
+
+
+def list_users() -> list[dict]:
+    with _conn() as conn:
+        rows = conn.execute("SELECT username, tier, created_utc FROM users").fetchall()
+    return [{"username": u, "tier": t, "created_utc": c} for u, t, c in rows]
+
+
+# ---- tokens -----------------------------------------------------------------
+
+def issue_token(username: str, tier: str, now: float | None = None) -> dict:
+    exp = int((now or time.time()) + TOKEN_TTL_S)
+    body = f"{username}|{tier}|{exp}"
+    sig = hmac.new(_secret(), body.encode(), hashlib.sha256).hexdigest()
+    return {"token": f"{body}|{sig}", "expires_utc": exp, "tier": tier}
+
+
+def verify_token(token: str, now: float | None = None) -> dict | None:
+    parts = token.split("|")
+    if len(parts) != 4:
+        return None
+    username, tier, exp_s, sig = parts
+    body = f"{username}|{tier}|{exp_s}"
+    want = hmac.new(_secret(), body.encode(), hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(want, sig):
+        return None
+    if int(exp_s) < (now or time.time()):
+        return None
+    return {"username": username, "tier": tier}
+
+
+def get_alert_prefs(username: str) -> dict:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT email, alerts_on FROM users WHERE username=?", (username,)
+        ).fetchone()
+    if row is None:
+        return {"email": "", "alerts_on": False}
+    return {"email": row[0] or "", "alerts_on": bool(row[1])}
+
+
+def set_alert_prefs(username: str, email: str, alerts_on: bool) -> dict:
+    email = (email or "").strip()
+    if email and ("@" not in email or len(email) > 254):
+        raise ValueError("invalid email")
+    if alerts_on and not email:
+        raise ValueError("an email is required to turn alerts on")
+    with _conn() as conn:
+        conn.execute("UPDATE users SET email=?, alerts_on=? WHERE username=?",
+                     (email, 1 if alerts_on else 0, username))
+    return {"email": email, "alerts_on": alerts_on}
+
+
+def alert_recipients() -> list[str]:
+    """Emails of subscribers who have alerts on — the notify fan-out list."""
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT email FROM users WHERE alerts_on=1 AND email != ''"
+        ).fetchall()
+    return [r[0] for r in rows]
+
+
+def asof_gate_enabled() -> bool:
+    return os.getenv("SEICHE_ASOF_AUTH", "0") == "1"

seiche-0.7.0/seiche/ai.py

@@ -0,0 +1,267 @@
+"""The desk assistant — an LLM strictly moored to the board.
+
+Architecture: a deterministic CONTEXT PACK (compact JSON of the live board —
+composite decomposition, headline, Tell/Turn/ML summaries, calendar, movers,
+faults, staleness) is the model's ONLY source of truth. The system prompt
+forbids outside numbers, requires an engine + as-of citation for every figure,
+and mandates "not in the pack" over improvisation. Temperature low. This is a
+reading assistant for the instrument, not an oracle.
+
+Routing: free-llm-router (Groq→Cerebras→Google→Mistral→OpenRouter free tiers)
+when importable and keyed; otherwise any OpenAI-compatible endpoint via
+SEICHE_LLM_BASE_URL / SEICHE_LLM_API_KEY / SEICHE_LLM_MODEL; otherwise the
+call fails open and returns the context pack itself — still useful, paste it
+into any chat you like.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+
+import httpx
+
+
+_META_OPENERS = re.compile(
+    r"^\s*(we need to|the user|let'?s|i need to|i should|we should|okay[, ]|first[, ])",
+    re.IGNORECASE,
+)
+
+
+def _strip_reasoning(text: str) -> str:
+    """Free-tier reasoning models leak chain-of-thought. Three passes:
+    <think> blocks, 'Final answer:' markers, and the gpt-oss-style pattern
+    where plain-text deliberation precedes the real answer — there, the final
+    paragraph is the deliverable."""
+    text = re.sub(r"<think>.*?</think>", "", text, flags=re.DOTALL).strip()
+    m = re.search(r"(?:final answer|answer)\s*[:\-]\s*", text, flags=re.IGNORECASE)
+    if m and m.start() > 80:  # only treat as a marker if real preamble precedes it
+        return text[m.end():].strip()
+    if _META_OPENERS.match(text):
+        paras = [p.strip() for p in text.split("\n\n") if p.strip()]
+        # walk from the end past any trailing meta paragraphs
+        for p in reversed(paras):
+            if not _META_OPENERS.match(p):
+                return p
+    return text
+
+SYSTEM_PROMPT = """You are the desk assistant inside SEICHE, a funding-stress terminal.
+You will receive a CONTEXT PACK (JSON) describing the live board, then a question.
+
+Hard rules:
+1. The context pack is your ONLY source of numbers. Never use outside data or memory of markets.
+2. Cite the engine and as-of date for every figure you use, like: (composite, 2026-07-06).
+3. If the pack does not contain what is asked, say "not on the board" — do not improvise.
+4. Plain prose, tight, desk-note voice. No headers unless asked. Max ~180 words unless asked for more.
+5. You describe readings and mechanics; you do not give investment advice. If asked for a trade, restate what the Playbook table shows (with n) and say the decision is the operator's.
+6. Respect the tool's honesty: mention coverage %, DEAD inputs, staleness or backtest caveats when they materially qualify the answer.
+7. Output ONLY the final answer. No reasoning preamble, no "we need to", no meta-commentary about the task."""
+
+
+def context_pack(snap: dict) -> dict:
+    """Compact, deterministic extract of the payload — the model's whole world."""
+    eng = snap.get("engines", {})
+    deep = snap.get("deep", {})
+    comp = eng.get("composite", {})
+    tell = deep.get("tell", {})
+    turn = (deep.get("turn") or {}).get("next_turn")
+    ml = deep.get("ml", {})
+    bt = (deep.get("backtest") or {}).get("event_capture", {})
+    sonar = eng.get("sonar", {})
+    basins = eng.get("basins", {})
+    moor = eng.get("moorings", {})
+    prov = snap.get("provenance", [])
+    stale_counts: dict[str, int] = {}
+    for p in prov:
+        stale_counts[p.get("staleness", "?")] = stale_counts.get(p.get("staleness", "?"), 0) + 1
+
+    return {
+        "generated_at": snap.get("generated_at"),
+        "version": snap.get("version"),
+        "composite": {
+            "value": comp.get("value"), "regime": comp.get("regime"),
+            "coverage_pct": comp.get("coverage_pct"), "dead_inputs": comp.get("dead_inputs"),
+            "decomposition": comp.get("decomposition"),
+        },
+        "headline": snap.get("headline"),
+        "tell": {k: tell.get(k) for k in ("tell", "plumbing_pctl", "market_pctl", "reading", "asof")} if tell.get("ok") else None,
+        "next_turn": turn,
+        "ml": {k: ml.get(k) for k in ("p_event_5bd", "verdict", "asof")} if ml.get("ok") else None,
+        "kink": {k: eng.get("kink", {}).get(k) for k in ("kink_reserves_b", "current_reserves_b", "distance_b", "days_to_kink", "r2", "asof")} if eng.get("kink", {}).get("ok") else None,
+        "weather_crunches": eng.get("weather", {}).get("crunch_windows", [])[:5],
+        "resonance": {
+            "score": eng.get("resonance", {}).get("score"),
+            "worst_mode": eng.get("resonance", {}).get("worst_mode"),
+        } if eng.get("resonance", {}).get("ok") else None,
+        "warehouse": {k: eng.get("warehouse", {}).get(k) for k in ("total_net_b", "total_pctl", "long_end_share_pct", "asof")} if eng.get("warehouse", {}).get("ok") else None,
+        "echo_top": eng.get("echo", {}).get("top"),
+        "book": {
+            "today": deep.get("book", {}).get("today"),
+            "verdict": (deep.get("book", {}).get("backtest") or {}).get("verdict"),
+            "live": deep.get("book", {}).get("live"),
+        } if (deep.get("book") or {}).get("ok") else None,
+        "stacker": {
+            "p_now": deep.get("stacker", {}).get("p_now"),
+            "published": deep.get("stacker", {}).get("published"),
+            "dispersion_now": deep.get("stacker", {}).get("dispersion_now"),
+            "verdict": deep.get("stacker", {}).get("verdict"),
+        } if (deep.get("stacker") or {}).get("ok") else None,
+        "farbasin": {
+            "channels": {k: {kk: vv for kk, vv in (v or {}).items() if kk != "series"}
+                          for k, v in (eng.get("farbasin", {}).get("channels") or {}).items()},
+            "status": eng.get("farbasin", {}).get("status"),
+        } if eng.get("farbasin", {}).get("ok") else None,
+        "tidetables": {
+            "event_odds": deep.get("tidetables", {}).get("event_odds"),
+            "novelty": deep.get("tidetables", {}).get("novelty"),
+            "skill_verdict": (deep.get("tidetables", {}).get("skill") or {}).get("verdict"),
+            "asof": deep.get("tidetables", {}).get("asof"),
+        } if (deep.get("tidetables") or {}).get("ok") else None,
+        "undertow": {
+            "score": eng.get("undertow", {}).get("score"),
+            "per_series": {
+                k: {kk: v.get(kk) for kk in ("ac1_pctl", "tau_bd", "var_pctl")}
+                for k, v in (eng.get("undertow", {}).get("per_series") or {}).items()
+            },
+            "asof": eng.get("undertow", {}).get("asof"),
+        } if eng.get("undertow", {}).get("ok") else None,
+        "bathymetry": {
+            "p_event_5bd": deep.get("bathymetry", {}).get("p_event_5bd"),
+            "mfpt_bd": deep.get("bathymetry", {}).get("mfpt_bd"),
+            "floor": {
+                k: (deep.get("bathymetry", {}).get("floor") or {}).get(k)
+                for k in ("well_bp", "stiffness", "barrier_kt")
+            },
+            "tau_bd": (deep.get("bathymetry", {}).get("spectrum") or {}).get("tau_bd"),
+            "tau_pctl": (deep.get("bathymetry", {}).get("spectrum") or {}).get("tau_pctl"),
+            "entropy_pctl": (deep.get("bathymetry", {}).get("arrow") or {}).get("pctl"),
+            "validation_verdict": (deep.get("bathymetry", {}).get("validation") or {}).get("verdict"),
+            "asof": deep.get("bathymetry", {}).get("asof"),
+        } if (deep.get("bathymetry") or {}).get("ok") else None,
+        "swell": {
+            "p_event_5bd": deep.get("swell", {}).get("p_event_5bd"),
+            "event_by_horizon": deep.get("swell", {}).get("event_by_horizon"),
+            "peak": deep.get("swell", {}).get("peak"),
+            "validation_verdict": (deep.get("swell", {}).get("validation") or {}).get("verdict"),
+            "asof": deep.get("swell", {}).get("asof"),
+        } if (deep.get("swell") or {}).get("ok") else None,
+        "merian": {
+            "instability": eng.get("merian", {}).get("instability"),
+            "modes": (eng.get("merian", {}).get("modes") or [])[:3],
+            "asof": eng.get("merian", {}).get("asof"),
+        } if eng.get("merian", {}).get("ok") else None,
+        "gyre": {
+            "determinism_verdict": (deep.get("gyre", {}).get("determinism") or {}).get("verdict"),
+            "nonlinearity_verdict": (deep.get("gyre", {}).get("nonlinearity") or {}).get("verdict"),
+            "stability": deep.get("gyre", {}).get("stability"),
+            "forecast": deep.get("gyre", {}).get("forecast"),
+            "asof": deep.get("gyre", {}).get("asof"),
+        } if (deep.get("gyre") or {}).get("ok") else None,
+        "roguewave": {
+            "tail_verdict": eng.get("roguewave", {}).get("tail_verdict"),
+            "fit": eng.get("roguewave", {}).get("fit"),
+            "return_levels": eng.get("roguewave", {}).get("return_levels"),
+            "sample_max_bp": eng.get("roguewave", {}).get("sample_max_bp"),
+            "asof": eng.get("roguewave", {}).get("asof"),
+        } if eng.get("roguewave", {}).get("ok") else None,
+        "basins": basins.get("basins") if basins.get("ok") else None,
+        "swap_lines_30d_m": (basins.get("swap_lines") or {}).get("ops_30d_total_m") if basins.get("ok") else None,
+        "moorings": {
+            "usdt_dev_bp": (moor.get("usdt") or {}).get("dev_bp"),
+            "stable_total_b": (moor.get("demand") or {}).get("total_b"),
+            "stable_chg_30d_pct": (moor.get("demand") or {}).get("chg_30d_pct"),
+        } if moor.get("ok") else None,
+        "communique": {
+            "latest": eng.get("communique", {}).get("latest"),
+            "flags": eng.get("communique", {}).get("flags"),
+            "n_statements": eng.get("communique", {}).get("n_statements"),
+        } if eng.get("communique", {}).get("ok") else None,
+        "riptide": {
+            "live": deep.get("riptide", {}).get("live"),
+            "flat_water": deep.get("riptide", {}).get("flat_water"),
+            "asof": deep.get("riptide", {}).get("asof"),
+        } if (deep.get("riptide") or {}).get("ok") else None,
+        "breakwater": {
+            "rescue_proximity": eng.get("breakwater", {}).get("rescue_proximity"),
+            "revealed_threshold": eng.get("breakwater", {}).get("revealed_threshold"),
+            "reading": eng.get("breakwater", {}).get("reading"),
+        } if eng.get("breakwater", {}).get("ok") else None,
+        "sonar_flagged": [m for m in sonar.get("movers", []) if m.get("flag")][:6],
+        "calendar": snap.get("calendar", {}),
+        "playbook": deep.get("playbook", {}).get("tables") if (deep.get("playbook") or {}).get("ok") else None,
+        "playbook_state": (deep.get("playbook") or {}).get("state"),
+        "backtest_headline": {
+            "recall": bt.get("recall"), "precision": bt.get("precision"),
+            "base_rate": bt.get("base_rate"), "median_lead_d": bt.get("median_lead_d"),
+        },
+        "backtest_caveats": (deep.get("backtest") or {}).get("caveats"),
+        "faults": snap.get("faults"),
+        "provenance_staleness": stale_counts,
+    }
+
+
+async def _via_router(messages: list[dict]) -> str | None:
+    try:
+        from free_llm_router import FreeLLMRouter
+    except ImportError:
+        return None
+    router = FreeLLMRouter()
+    try:
+        # router envelope: {"text", "model", "provider", "tokens", ...}.
+        # fast tier first (non-reasoning models: clean output for a read-the-
+        # pack task); smart as fallback, with _strip_reasoning as the net for
+        # chain-of-thought leakage.
+        last: Exception | None = None
+        for tier in ("fast", "smart"):
+            try:
+                resp = await router.chat_completion(messages, tier=tier, temperature=0.2, max_tokens=700)
+                return resp["text"]
+            except Exception as e:  # noqa: BLE001 — try the other tier
+                last = e
+        if last:
+            raise last
+        return None
+    finally:
+        await router.close()
+
+
+async def _via_env(messages: list[dict]) -> str | None:
+    base = os.environ.get("SEICHE_LLM_BASE_URL")
+    if not base:
+        return None
+    key = os.environ.get("SEICHE_LLM_API_KEY", "")
+    model = os.environ.get("SEICHE_LLM_MODEL", "gpt-4o-mini")
+    async with httpx.AsyncClient(timeout=60) as client:
+        r = await client.post(
+            f"{base.rstrip('/')}/chat/completions",
+            headers={"Authorization": f"Bearer {key}"} if key else {},
+            json={"model": model, "messages": messages, "temperature": 0.2, "max_tokens": 700},
+        )
+        r.raise_for_status()
+        return r.json()["choices"][0]["message"]["content"]
+
+
+async def ask(question: str, snap: dict) -> dict:
+    pack = context_pack(snap)
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": "CONTEXT PACK:\n" + json.dumps(pack, default=str)
+                                    + f"\n\nQUESTION: {question}"},
+    ]
+    errors = []
+    for route, fn in (("free-llm-router", _via_router), ("env-endpoint", _via_env)):
+        try:
+            answer = await fn(messages)
+            if answer:
+                return {"ok": True, "route": route, "answer": _strip_reasoning(answer),
+                        "grounding": "answers are restricted to the context pack; verify against the board"}
+        except Exception as e:
+            errors.append(f"{route}: {type(e).__name__}: {str(e)[:80]}")
+    return {
+        "ok": False,
+        "reason": "no LLM route available (" + ("; ".join(errors) if errors else
+                  "free-llm-router unkeyed and SEICHE_LLM_BASE_URL unset") + ")",
+        "context_pack": pack,
+        "hint": "the context pack above is self-contained — paste it into any chat model",
+    }