hypermind 0.11.0__py3-none-any.whl

hypermind/responders/router.py

@@ -0,0 +1,254 @@
+"""Pluggable model routing for consult panels.
+
+A :class:`ResponderRouter` decides *which responder* to dispatch to *for a
+given panel member and query*. This unblocks three patterns at once:
+
+1. **Cost-aware routing** (:class:`CostAwareRouter`) — try the strongest
+   model first; fall back to cheaper models on rate-limits, errors, or
+   when the per-call budget would be exceeded.
+
+2. **Multi-model panels** (:class:`MultiModelPanelRouter`) — assign
+   different LLMs to different panel members so the panel reflects
+   genuine model diversity, not just role-prompt theatre.
+
+3. **Per-archetype routing** (:class:`ArchetypeMappedRouter`) — each
+   analyst archetype gets its own model (e.g., intel-agency → claude-opus,
+   social-intel → llama-3.3).
+
+A router is itself a :class:`Responder` — it satisfies
+``Callable[[bytes, str], Awaitable[ResponderResult]]`` so callers can pass
+it directly to ``consult(responder=router)``.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable, Iterable
+from typing import Any, Protocol
+
+from hypermind.responders.base import (
+    LLMResponderError,
+    Responder,
+    ResponderResult,
+    unpack_responder_result,
+)
+
+
+class ResponderRouter(Protocol):
+    """Routes one ``(agent_kid, query)`` to the appropriate underlying responder.
+
+    A router is callable like a responder, so it can be passed directly
+    as ``consult(responder=router)``.
+    """
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult: ...
+
+
+# ---------------------------------------------------------------------------
+# CostAwareRouter — strongest-first, fallback on error or budget breach
+# ---------------------------------------------------------------------------
+
+
+class CostAwareRouter:
+    """Try ``primary`` first; fall back through the chain on errors.
+
+    Useful pattern: ``[claude-opus, claude-sonnet, claude-haiku]`` —
+    if Opus times out or rate-limits, the panel doesn't collapse, it
+    just gets a cheaper answer for that member.
+
+    Each fallback emits a recorder event (if a recorder is attached) so
+    operators can spot which models are flapping.
+
+    ``budget_usd_per_call`` is a soft cap: if the *previous* call's cost
+    exceeded this, the router skips the most expensive model for the
+    next call. (We can't predict cost ahead of time without prompts.)
+    """
+
+    def __init__(
+        self,
+        chain: list[Responder],
+        *,
+        budget_usd_per_call: float | None = None,
+        recorder: Any = None,
+    ) -> None:
+        if not chain:
+            raise ValueError("CostAwareRouter chain must contain at least one responder")
+        self.chain = list(chain)
+        self.budget_usd_per_call = budget_usd_per_call
+        self.recorder = recorder
+        # When the last successful call cost more than budget, mark it
+        # so the next call skips the heaviest model.
+        self._last_call_exceeded_budget = False
+
+    def _emit(self, event_type: str, fields: dict[str, Any]) -> None:
+        if self.recorder is None:
+            return
+        try:
+            self.recorder.emit(
+                event_type=event_type,
+                severity="info",
+                fields=fields,
+            )
+        except Exception:
+            pass
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        chain = self.chain
+        if self._last_call_exceeded_budget and len(chain) > 1:
+            # Skip the most expensive (assumed first) — fall straight
+            # through to the cheaper tier for one call.
+            chain = chain[1:]
+            self._last_call_exceeded_budget = False
+
+        last_exc: BaseException | None = None
+        for idx, responder in enumerate(chain):
+            try:
+                result = await responder(agent_kid, query)
+            except LLMResponderError as exc:
+                last_exc = exc
+                self._emit(
+                    "router_fallback",
+                    {
+                        "tier": idx,
+                        "reason": "llm_responder_error",
+                        "error": str(exc)[:160],
+                    },
+                )
+                continue
+            except Exception as exc:
+                last_exc = exc
+                self._emit(
+                    "router_fallback",
+                    {
+                        "tier": idx,
+                        "reason": "unexpected_error",
+                        "error_type": type(exc).__name__,
+                    },
+                )
+                continue
+
+            # Check budget — only meaningful on tuple results with token_usage
+            try:
+                _unc, structured = unpack_responder_result(result)
+            except TypeError:
+                # Pass through whatever responder returned; budget check skipped
+                return result
+
+            if (
+                self.budget_usd_per_call is not None
+                and structured is not None
+                and structured.token_usage is not None
+                and structured.token_usage.cost_usd is not None
+                and structured.token_usage.cost_usd > self.budget_usd_per_call
+            ):
+                self._last_call_exceeded_budget = True
+                self._emit(
+                    "router_budget_exceeded",
+                    {
+                        "tier": idx,
+                        "cost_usd": structured.token_usage.cost_usd,
+                        "budget_usd": self.budget_usd_per_call,
+                    },
+                )
+            return result
+
+        # Every tier failed → re-raise as LLMResponderError
+        raise LLMResponderError(
+            f"CostAwareRouter exhausted all {len(self.chain)} tiers; last error: {last_exc}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# MultiModelPanelRouter — different model per panel member
+# ---------------------------------------------------------------------------
+
+
+class MultiModelPanelRouter:
+    """Assign each ``agent_kid`` a stable responder from a pool.
+
+    The mapping is deterministic in the kid — re-running the same
+    cohort produces the same model assignments — but spread evenly
+    across the pool. Useful for genuine model diversity (mix Claude,
+    GPT-4o, Llama, Gemini in one panel).
+
+    The pool order is preserved; assignment uses
+    ``int.from_bytes(kid[:4]) % len(pool)``.
+    """
+
+    def __init__(self, pool: Iterable[Responder]) -> None:
+        self.pool = list(pool)
+        if not self.pool:
+            raise ValueError("MultiModelPanelRouter pool cannot be empty")
+
+    def _select(self, agent_kid: bytes) -> Responder:
+        if not agent_kid:
+            return self.pool[0]
+        idx = int.from_bytes(agent_kid[:4], "big") % len(self.pool)
+        return self.pool[idx]
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        responder = self._select(agent_kid)
+        return await responder(agent_kid, query)
+
+
+# ---------------------------------------------------------------------------
+# ArchetypeMappedRouter — explicit archetype → responder mapping
+# ---------------------------------------------------------------------------
+
+
+class ArchetypeMappedRouter:
+    """Look up a responder by archetype, with a default fallback.
+
+    Callers supply an ``archetype_for(kid) -> str`` callable so the
+    router can route per-agent. If the lookup returns an unknown
+    archetype, ``default_responder`` handles the call.
+    """
+
+    def __init__(
+        self,
+        mapping: dict[str, Responder],
+        *,
+        archetype_for: Callable[[bytes], str | None],
+        default_responder: Responder,
+    ) -> None:
+        self.mapping = dict(mapping)
+        self.archetype_for = archetype_for
+        self.default_responder = default_responder
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        archetype = self.archetype_for(agent_kid)
+        responder = self.mapping.get(archetype or "", self.default_responder)
+        return await responder(agent_kid, query)
+
+
+# ---------------------------------------------------------------------------
+# RandomPoolRouter — stochastic mixture (for benchmarking model diversity)
+# ---------------------------------------------------------------------------
+
+
+class RandomPoolRouter:
+    """Pick a uniform-random responder from the pool for each call.
+
+    Distinct from :class:`MultiModelPanelRouter` (which is deterministic
+    per kid). This is for benchmarking and Monte-Carlo experiments where
+    you want each call to potentially use a different model.
+    """
+
+    def __init__(self, pool: Iterable[Responder], *, seed: int | None = None) -> None:
+        self.pool = list(pool)
+        if not self.pool:
+            raise ValueError("RandomPoolRouter pool cannot be empty")
+        self._rng = random.Random(seed)
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        responder = self._rng.choice(self.pool)
+        return await responder(agent_kid, query)
+
+
+__all__ = [
+    "ArchetypeMappedRouter",
+    "CostAwareRouter",
+    "MultiModelPanelRouter",
+    "RandomPoolRouter",
+    "ResponderRouter",
+]

hypermind/responders/structured.py

@@ -0,0 +1,287 @@
+"""Structured reasoning capture for LLM-backed responders.
+
+Single-shot LLM panels return ``{confidence, reasoning}`` — a flat scalar
+and a short prose rationale. Sub-claims, evidence references, alternative
+scenarios, and key unknowns are lost at parse time.
+
+This module defines the richer schema that the LLM is *also* asked to
+produce, with graceful fallback when the model ignores the extended
+structure (or pricing/cost data isn't available).
+
+The widened :class:`StructuredResponse` is attached to every
+:class:`PanelMember` and surfaced in the :class:`ConsultResult`, so the
+viewer can show *why* an analyst answered the way they did, what they
+thought might change their mind, and which references they cited.
+
+Backward-compat: every field has a default. A bare confidence-only
+response from the LLM still produces a valid (but minimally-populated)
+:class:`StructuredResponse`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Token usage (cost tracking hook — Phase 5 wires it through cost.py)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class TokenUsage:
+    """LLM token accounting for one panel-member call.
+
+    ``cost_usd`` is None when the model isn't in the price table —
+    operators see the warning emit on the recorder rather than a wrong
+    cost figure.
+    """
+
+    model: str
+    prompt_tokens: int
+    completion_tokens: int
+    cost_usd: float | None = None
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "model": self.model,
+            "prompt_tokens": self.prompt_tokens,
+            "completion_tokens": self.completion_tokens,
+            "total_tokens": self.total_tokens,
+            "cost_usd": self.cost_usd,
+        }
+
+
+# ---------------------------------------------------------------------------
+# StructuredResponse — what an LLM tells us beyond a scalar confidence
+# ---------------------------------------------------------------------------
+
+#: Hard caps so the viewer / aggregator can rely on bounded sizes.
+MAX_REASONING_CHARS = 1000
+MAX_LIST_ITEMS = 8
+MAX_LIST_ITEM_CHARS = 240
+
+
+@dataclass(frozen=True)
+class StructuredResponse:
+    """Rich reasoning record from one LLM call.
+
+    Fields:
+        confidence: scalar in [0, 1] — already used to build Uncertainty
+        reasoning: one-paragraph rationale (≤1000 chars)
+        sub_claims: bulleted decomposition of the main claim
+        alternatives: scenarios that would change the answer
+        evidence_refs: cited external references (URLs, doc IDs, …)
+        key_unknowns: things the analyst flags as unresolved
+        token_usage: cost accounting (filled by responder, may be None)
+        raw_json: raw LLM payload — kept for replay and debugging
+    """
+
+    confidence: float
+    reasoning: str = ""
+    sub_claims: list[str] = field(default_factory=list)
+    alternatives: list[str] = field(default_factory=list)
+    evidence_refs: list[str] = field(default_factory=list)
+    key_unknowns: list[str] = field(default_factory=list)
+    token_usage: TokenUsage | None = None
+    raw_json: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "confidence": self.confidence,
+            "reasoning": self.reasoning,
+            "sub_claims": list(self.sub_claims),
+            "alternatives": list(self.alternatives),
+            "evidence_refs": list(self.evidence_refs),
+            "key_unknowns": list(self.key_unknowns),
+            "token_usage": self.token_usage.to_dict() if self.token_usage else None,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+_JSON_BLOCK_RE = re.compile(r"\{[\s\S]*\}", re.MULTILINE)
+
+
+def _truncate(s: str, n: int) -> str:
+    s = (s or "").strip()
+    return s if len(s) <= n else s[:n].rstrip() + "…"
+
+
+def _coerce_str_list(value: Any, max_items: int = MAX_LIST_ITEMS) -> list[str]:
+    """Best-effort coercion of LLM output into a clean list[str].
+
+    Accepts list, comma-separated string, or single string. Drops empty
+    items, dedupes preserving order, truncates to ``max_items`` and
+    each item to :data:`MAX_LIST_ITEM_CHARS` chars.
+    """
+    if value is None:
+        return []
+    if isinstance(value, str):
+        # Treat a stringified list (e.g. "a, b, c") as comma-separated
+        items = [p.strip() for p in value.split(",")]
+    elif isinstance(value, (list, tuple)):
+        items = []
+        for raw in value:
+            if isinstance(raw, str):
+                items.append(raw.strip())
+            elif isinstance(raw, dict):
+                # LLMs sometimes nest {"text": "..."} or similar
+                text = raw.get("text") or raw.get("claim") or raw.get("title") or ""
+                items.append(str(text).strip())
+            else:
+                items.append(str(raw).strip())
+    else:
+        return []
+
+    cleaned: list[str] = []
+    seen: set[str] = set()
+    for it in items:
+        if not it:
+            continue
+        truncated = _truncate(it, MAX_LIST_ITEM_CHARS)
+        key = truncated.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        cleaned.append(truncated)
+        if len(cleaned) >= max_items:
+            break
+    return cleaned
+
+
+def parse_structured_response(
+    raw: str,
+    *,
+    agent_kid: bytes | None = None,
+    token_usage: TokenUsage | None = None,
+) -> StructuredResponse:
+    """Parse the LLM's JSON response into a :class:`StructuredResponse`.
+
+    Tolerant of:
+      * bare confidence-only payloads (legacy contract)
+      * extra prose around the JSON block (extracts the first ``{...}``)
+      * field aliases (``rationale``/``explanation`` for reasoning, etc.)
+      * list-or-string variations on sub_claims/alternatives/evidence
+
+    Raises :class:`ValueError` if no valid ``confidence`` can be extracted —
+    callers (the OpenAI/Anthropic responder) re-raise as
+    :class:`LLMResponderError` to keep the consult-panel drop-policy intact.
+
+    The ``agent_kid`` argument is currently informational (kept for future
+    audit-trail correlation); it does NOT affect parsing.
+    """
+    _ = agent_kid  # reserved for future per-agent parse caching
+
+    if raw is None:
+        raise ValueError("empty LLM response")
+
+    text = str(raw).strip()
+    if not text:
+        raise ValueError("empty LLM response")
+
+    # Try direct JSON parse first; fall back to extracting the first object.
+    parsed: Any
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        m = _JSON_BLOCK_RE.search(text)
+        if m is None:
+            raise ValueError("LLM response is not JSON and contains no JSON object") from None
+        try:
+            parsed = json.loads(m.group(0))
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"LLM response JSON block did not parse: {exc}") from exc
+
+    if not isinstance(parsed, dict):
+        raise ValueError(f"LLM response top-level is {type(parsed).__name__}, expected object")
+
+    # Confidence is mandatory.
+    if "confidence" not in parsed:
+        raise ValueError("LLM response missing required 'confidence' field")
+    try:
+        confidence = float(parsed["confidence"])
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"LLM 'confidence' is not a float: {exc}") from exc
+
+    # Reasoning: accept multiple aliases the model may have used.
+    reasoning_raw = (
+        parsed.get("reasoning")
+        or parsed.get("rationale")
+        or parsed.get("explanation")
+        or parsed.get("thought")
+        or ""
+    )
+    reasoning = _truncate(str(reasoning_raw), MAX_REASONING_CHARS)
+
+    sub_claims = _coerce_str_list(
+        parsed.get("sub_claims") or parsed.get("claims") or parsed.get("factors")
+    )
+    alternatives = _coerce_str_list(
+        parsed.get("alternatives")
+        or parsed.get("alternative_scenarios")
+        or parsed.get("counterfactuals")
+    )
+    evidence_refs = _coerce_str_list(
+        parsed.get("evidence_refs")
+        or parsed.get("evidence")
+        or parsed.get("citations")
+        or parsed.get("references")
+    )
+    key_unknowns = _coerce_str_list(
+        parsed.get("key_unknowns") or parsed.get("unknowns") or parsed.get("open_questions")
+    )
+
+    return StructuredResponse(
+        confidence=confidence,
+        reasoning=reasoning,
+        sub_claims=sub_claims,
+        alternatives=alternatives,
+        evidence_refs=evidence_refs,
+        key_unknowns=key_unknowns,
+        token_usage=token_usage,
+        raw_json=text if len(text) <= 4096 else text[:4096] + "…",
+    )
+
+
+# ---------------------------------------------------------------------------
+# System-prompt helper — what we ask the LLM to produce
+# ---------------------------------------------------------------------------
+
+#: Default extension to any system prompt to elicit the rich schema.
+#: Callers compose this with their archetype-specific prompt; the OpenAI
+#: and Anthropic responders auto-append it when ``capture_structured=True``.
+STRUCTURED_PROMPT_SUFFIX = """\
+
+Respond with a single json object using this schema:
+
+{
+  "confidence": <float in [0, 1] — probability the answer is YES>,
+  "reasoning": "<one-paragraph rationale, ≤300 words>",
+  "sub_claims": ["<bullet>", "<bullet>", ...],
+  "alternatives": ["<scenario that would change my answer>", ...],
+  "evidence_refs": ["<source/url/doc id>", ...],
+  "key_unknowns": ["<thing I am uncertain about>", ...]
+}
+
+Lists may be empty. Do NOT add any prose outside the JSON object.
+"""
+
+
+__all__ = [
+    "MAX_LIST_ITEMS",
+    "MAX_LIST_ITEM_CHARS",
+    "MAX_REASONING_CHARS",
+    "STRUCTURED_PROMPT_SUFFIX",
+    "StructuredResponse",
+    "TokenUsage",
+    "parse_structured_response",
+]