hypermind 0.11.0__py3-none-any.whl

hypermind/responders/anthropic.py

@@ -0,0 +1,159 @@
+"""Anthropic Messages-backed responder.
+
+Same contract as :class:`OpenAIResponder`: returns
+``(Uncertainty, StructuredResponse)`` so the consult panel can capture
+sub-claims, evidence references, and reasoning.
+
+Install: ``pip install hypermind[anthropic]``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hypermind.responders.base import (
+    LLMResponderError,
+    ResponderResult,
+    confidence_to_uncertainty,
+)
+from hypermind.responders.structured import (
+    STRUCTURED_PROMPT_SUFFIX,
+    StructuredResponse,
+    TokenUsage,
+    parse_structured_response,
+)
+
+_DEFAULT_SYSTEM = """You are a domain analyst on a federated intelligence panel.
+
+For each query, respond with a single JSON object:
+{
+  "confidence": <float in [0, 1]>,
+  "reasoning": "<one-paragraph rationale, ≤100 words>"
+}
+
+`confidence` is the probability that the answer to the question is YES.
+0.0 = certain NO, 1.0 = certain YES, 0.5 = no opinion. Use the full
+range — do not anchor to 0.5 unless you genuinely have no information.
+
+Respond ONLY with the JSON object, no surrounding prose."""
+
+
+class AnthropicResponder:
+    """A consult responder backed by an Anthropic Claude model.
+
+    Example::
+
+        from anthropic import AsyncAnthropic
+        from hypermind.responders import AnthropicResponder
+
+        client = AsyncAnthropic()
+        responder = AnthropicResponder(
+            client=client,
+            model="claude-sonnet-4-6",
+            system_prompt="You are a biosecurity analyst...",
+        )
+
+        result = await alice.consult(
+            "Is this pathogen escape contained?",
+            panel_size=10,
+            responder=responder,
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str = "claude-sonnet-4-6",
+        system_prompt: str = _DEFAULT_SYSTEM,
+        effective_n: float = 10.0,
+        max_tokens: int = 600,
+        temperature: float = 0.4,
+        capture_structured: bool = True,
+        cost_tracker: Any = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.system_prompt = system_prompt
+        self.effective_n = effective_n
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+        self.capture_structured = capture_structured
+        self.cost_tracker = cost_tracker
+        self.last_response: tuple[float, str] | None = None
+        self.last_structured: StructuredResponse | None = None
+
+    def _build_system_prompt(self) -> str:
+        if not self.capture_structured:
+            return self.system_prompt
+        if "sub_claims" in self.system_prompt:
+            return self.system_prompt
+        return self.system_prompt + STRUCTURED_PROMPT_SUFFIX
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        system = self._build_system_prompt()
+        try:
+            resp = await self.client.messages.create(
+                model=self.model,
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+                system=system,
+                messages=[{"role": "user", "content": query}],
+            )
+        except Exception as exc:
+            raise LLMResponderError(f"Anthropic call failed: {exc}") from exc
+
+        # Anthropic returns message.content as a list of content blocks
+        try:
+            text_block = next(b for b in resp.content if getattr(b, "type", None) == "text")
+            text = text_block.text
+        except (StopIteration, AttributeError) as exc:
+            raise LLMResponderError(f"Anthropic response had no text block: {exc}") from exc
+
+        # ---- Token usage ---------------------------------------------------
+        token_usage: TokenUsage | None = None
+        usage = getattr(resp, "usage", None)
+        if usage is not None:
+            prompt_t = int(getattr(usage, "input_tokens", 0) or 0)
+            completion_t = int(getattr(usage, "output_tokens", 0) or 0)
+            if self.cost_tracker is not None:
+                try:
+                    token_usage = self.cost_tracker.record(
+                        model=self.model,
+                        prompt_tokens=prompt_t,
+                        completion_tokens=completion_t,
+                        agent_kid=agent_kid,
+                    )
+                except Exception:
+                    token_usage = TokenUsage(
+                        model=self.model,
+                        prompt_tokens=prompt_t,
+                        completion_tokens=completion_t,
+                        cost_usd=None,
+                    )
+            else:
+                token_usage = TokenUsage(
+                    model=self.model,
+                    prompt_tokens=prompt_t,
+                    completion_tokens=completion_t,
+                    cost_usd=None,
+                )
+
+        # ---- Structured parse ----------------------------------------------
+        try:
+            structured = parse_structured_response(
+                text,
+                agent_kid=agent_kid,
+                token_usage=token_usage,
+            )
+        except ValueError as exc:
+            raise LLMResponderError(
+                f"Anthropic response did not contain a valid 'confidence' field: {exc}"
+            ) from exc
+
+        confidence = structured.confidence
+        self.last_response = (confidence, structured.reasoning)
+        self.last_structured = structured
+
+        unc = confidence_to_uncertainty(confidence, effective_n=self.effective_n)
+        return unc, structured

hypermind/responders/base.py

@@ -0,0 +1,162 @@
+"""Responder Protocol + helpers shared by every responder implementation."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Awaitable, Callable
+from typing import Protocol
+
+from hypermind.responders.structured import StructuredResponse
+from hypermind.uncertainty import Uncertainty
+
+
+class LLMResponderError(RuntimeError):
+    """Raised when an LLM call fails or returns an unparseable response.
+
+    The consult panel drops failed responders rather than aborting the
+    aggregation, so this is logged but not user-fatal in normal flow.
+    """
+
+
+#: Result type a responder may return.
+#:
+#: Legacy responders return bare :class:`Uncertainty`. v0.6+ responders
+#: may additionally return a :class:`StructuredResponse` paired with the
+#: posterior so the consult panel can capture sub-claims, evidence
+#: references, and reasoning text. The ``consult()`` dispatch in
+#: :mod:`hypermind.agent` accepts either form transparently.
+ResponderResult = Uncertainty | tuple[Uncertainty, StructuredResponse]
+
+# Public type alias for ``consult(responder=...)``.
+Responder = Callable[[bytes, str], Awaitable[ResponderResult]]
+
+
+def unpack_responder_result(
+    result: ResponderResult,
+) -> tuple[Uncertainty, StructuredResponse | None]:
+    """Normalise a responder return value to ``(Uncertainty, StructuredResponse | None)``.
+
+    Backward-compatible: a bare :class:`Uncertainty` produces ``(unc, None)``
+    so existing :class:`StaticResponder` / :class:`SyntheticResponder`
+    callers continue to work unchanged.
+    """
+    if isinstance(result, Uncertainty):
+        return result, None
+    if isinstance(result, tuple) and len(result) == 2 and isinstance(result[0], Uncertainty):
+        unc, structured = result
+        if structured is None or isinstance(structured, StructuredResponse):
+            return unc, structured
+    raise TypeError(
+        "Responder must return Uncertainty or (Uncertainty, StructuredResponse), "
+        f"got {type(result).__name__}"
+    )
+
+
+# --------------------------------------------------------------------------
+# Confidence → Uncertainty mapping
+# --------------------------------------------------------------------------
+
+
+def confidence_to_uncertainty(
+    confidence: float,
+    *,
+    effective_n: float = 10.0,
+    calibration_adj: float = 1.0,
+) -> Uncertainty:
+    """Map a single ``confidence`` ∈ [0, 1] into a Beta posterior.
+
+    The mapping uses an *effective sample size*: a confidence of 0.8
+    with ``effective_n=10`` produces ``Beta(α=8, β=2)``. Tuning
+    ``effective_n`` controls how confidently the responder is asserting
+    its belief — 4 for vibes, 10 for educated guesses, 30 for genuinely
+    informed predictions, ≥100 for ground-truth-anchored claims.
+
+    ``calibration_adj`` is a multiplicative shrinkage applied to
+    ``effective_n``. Callers that track per-agent Brier history (the
+    closed-loop calibration kernel) pass values in roughly [0.5, 2.0]:
+    well-calibrated agents are *boosted* (>1.0), overconfident agents
+    are *shrunk* (<1.0). Default 1.0 is a no-op so legacy callers see
+    identical behaviour.
+
+    Clamps confidence to [0.01, 0.99] so α and β are strictly positive
+    (Beta is undefined at the endpoints).
+    """
+    c = max(0.01, min(0.99, float(confidence)))
+    raw_n = max(1.0, float(effective_n))
+    adj = max(0.1, float(calibration_adj))  # never collapse to 0
+    n = max(1.0, raw_n * adj)
+    alpha = c * n
+    beta = (1.0 - c) * n
+    # Floor at 1.0 — Beta(1, 1) is the uniform prior; values < 1 produce
+    # bimodal U-shaped posteriors which are not what callers usually want.
+    return Uncertainty.beta(
+        alpha=max(1.0, alpha),
+        beta=max(1.0, beta),
+        n_eff=n,
+    )
+
+
+# --------------------------------------------------------------------------
+# Responder Protocol
+# --------------------------------------------------------------------------
+
+
+class _ResponderProto(Protocol):
+    async def __call__(self, agent_kid: bytes, query: str) -> Uncertainty: ...
+
+
+# --------------------------------------------------------------------------
+# StaticResponder — every agent returns the same Uncertainty
+# --------------------------------------------------------------------------
+
+
+class StaticResponder:
+    """Return a fixed Uncertainty for every (agent, query) pair.
+
+    Useful for deterministic tests and benchmarks where you want to
+    isolate the consult aggregation logic from any answer variation.
+    """
+
+    def __init__(self, uncertainty: Uncertainty) -> None:
+        self._u = uncertainty
+
+    async def __call__(self, agent_kid: bytes, query: str) -> Uncertainty:
+        return self._u
+
+
+# --------------------------------------------------------------------------
+# SyntheticResponder — Beta-sampled per-agent personality
+# --------------------------------------------------------------------------
+
+
+class SyntheticResponder:
+    """Per-agent Beta(α, β) profile, deterministic by agent kid.
+
+    Each agent gets a stable (α, β) drawn from the configured ranges,
+    seeded by its kid so the same agent always answers the same way.
+    Used by the geopolitical simulation as a stand-in for real LLMs.
+
+    >>> resp = SyntheticResponder(alpha_range=(8, 12), beta_range=(2, 4))
+    >>> await resp(b"\\x01" * 32, "Will it rain?")
+    Uncertainty(...)
+    """
+
+    def __init__(
+        self,
+        *,
+        alpha_range: tuple[float, float] = (5.0, 10.0),
+        beta_range: tuple[float, float] = (3.0, 6.0),
+    ) -> None:
+        self.alpha_range = alpha_range
+        self.beta_range = beta_range
+
+    async def __call__(self, agent_kid: bytes, query: str) -> Uncertainty:
+        # Stable per-agent seed so the same agent always returns the same
+        # posterior for the same query. (Hashing the query as well would
+        # be reasonable; we don't, so reputation drift between calls is
+        # purely from oracle resolution rather than answer variance.)
+        seed = int.from_bytes(agent_kid[:8], "big") if agent_kid else 0
+        rng = random.Random(seed)
+        alpha = rng.uniform(*self.alpha_range)
+        beta = rng.uniform(*self.beta_range)
+        return Uncertainty.beta(alpha=alpha, beta=beta)

hypermind/responders/openai.py

@@ -0,0 +1,199 @@
+"""OpenAI-backed responder.
+
+Each call to the responder spawns one Chat Completions request with a
+strict JSON schema. The model returns
+``{"confidence": 0.x, "reasoning": "...", "sub_claims": [...], ...}``
+which is parsed into ``Uncertainty.beta(...)`` paired with a
+:class:`StructuredResponse`.
+
+Install: ``pip install hypermind[openai]`` (adds ``openai>=1.0`` as a soft dep).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hypermind.responders.base import (
+    LLMResponderError,
+    ResponderResult,
+    confidence_to_uncertainty,
+)
+from hypermind.responders.structured import (
+    STRUCTURED_PROMPT_SUFFIX,
+    StructuredResponse,
+    TokenUsage,
+    parse_structured_response,
+)
+
+_DEFAULT_SYSTEM = """You are a domain analyst on a federated intelligence panel.
+
+For each query, respond with a single JSON object:
+{
+  "confidence": <float in [0, 1]>,
+  "reasoning": "<one-paragraph rationale, ≤100 words>"
+}
+
+`confidence` is the probability that the answer to the question is YES.
+0.0 = certain NO, 1.0 = certain YES, 0.5 = no opinion. Use the full
+range — do not anchor to 0.5 unless you genuinely have no information.
+
+Respond ONLY with the JSON object, no surrounding prose."""
+
+
+class OpenAIResponder:
+    """A consult responder backed by an OpenAI chat model.
+
+    Constructed with an OpenAI client, a model name, and an optional
+    system prompt that tells the model what role it is playing. Each
+    panel-member call spawns one chat completion.
+
+    When ``capture_structured=True`` (the default in v0.6+), the system
+    prompt is augmented with :data:`STRUCTURED_PROMPT_SUFFIX` and the
+    parsed sub-claims / evidence / alternatives are returned alongside
+    the Uncertainty. Backward-compat: the dispatch in :mod:`agent.consult`
+    accepts either ``Uncertainty`` or ``(Uncertainty, StructuredResponse)``
+    transparently.
+
+    Example::
+
+        from openai import AsyncOpenAI
+        from hypermind.responders import OpenAIResponder
+
+        client = AsyncOpenAI()
+        responder = OpenAIResponder(
+            client=client,
+            model="gpt-4o-mini",
+            system_prompt="You are a geopolitical analyst...",
+        )
+
+        result = await alice.consult(
+            "Will the cease-fire hold for 30 days?",
+            panel_size=10,
+            responder=responder,
+            capture_structured=True,
+        )
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str = "gpt-4o-mini",
+        system_prompt: str = _DEFAULT_SYSTEM,
+        effective_n: float = 10.0,
+        timeout_s: float = 30.0,
+        temperature: float = 0.4,
+        capture_structured: bool = True,
+        cost_tracker: Any = None,
+    ) -> None:
+        self.client = client
+        self.model = model
+        self.system_prompt = system_prompt
+        self.effective_n = effective_n
+        self.timeout_s = timeout_s
+        self.temperature = temperature
+        self.capture_structured = capture_structured
+        # Optional TokenCostTracker — when set, every call records its
+        # TokenUsage there in addition to attaching it to the
+        # StructuredResponse. See :mod:`hypermind.observability.cost`.
+        self.cost_tracker = cost_tracker
+        # Optional sink for the most recent LLM response (raw confidence
+        # + reasoning). Preserved for backward compat with v0.5 callers
+        # that read ``responder.last_response`` after each call.
+        self.last_response: tuple[float, str] | None = None
+        self.last_structured: StructuredResponse | None = None
+        self._cached_system: str = self._build_system_prompt()
+
+    def _build_system_prompt(self) -> str:
+        if not self.capture_structured:
+            return self.system_prompt
+        # Avoid double-suffixing if the caller already included it.
+        if "sub_claims" in self.system_prompt:
+            return self.system_prompt
+        return self.system_prompt + STRUCTURED_PROMPT_SUFFIX
+
+    async def __call__(self, agent_kid: bytes, query: str) -> ResponderResult:
+        system = self._cached_system
+
+        # OpenAI's `response_format=json_object` requires the literal
+        # token "json" somewhere in the messages — append a hint if
+        # missing so callers don't have to remember.
+        user_content = query
+        if "json" not in (user_content + system).lower():
+            user_content = (
+                f"{query}\n\n"
+                'Respond with a json object: {"confidence": <0..1>, "reasoning": "..."}'
+            )
+
+        try:
+            resp = await self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": user_content},
+                ],
+                response_format={"type": "json_object"},
+                temperature=self.temperature,
+                timeout=self.timeout_s,
+            )
+        except Exception as exc:
+            raise LLMResponderError(f"OpenAI call failed: {exc}") from exc
+
+        content = (resp.choices[0].message.content or "{}") if resp.choices else "{}"
+
+        # ---- Token usage --------------------------------------------------
+        token_usage: TokenUsage | None = None
+        usage = getattr(resp, "usage", None)
+        if usage is not None:
+            prompt_t = int(getattr(usage, "prompt_tokens", 0) or 0)
+            completion_t = int(getattr(usage, "completion_tokens", 0) or 0)
+            cost: float | None = None
+            if self.cost_tracker is not None:
+                # cost_tracker.record() returns the canonical TokenUsage
+                # with cost computed from PRICE_TABLE; fall back to a
+                # locally-built record if the tracker isn't attached.
+                try:
+                    token_usage = self.cost_tracker.record(
+                        model=self.model,
+                        prompt_tokens=prompt_t,
+                        completion_tokens=completion_t,
+                        agent_kid=agent_kid,
+                    )
+                except Exception:
+                    token_usage = TokenUsage(
+                        model=self.model,
+                        prompt_tokens=prompt_t,
+                        completion_tokens=completion_t,
+                        cost_usd=None,
+                    )
+            else:
+                token_usage = TokenUsage(
+                    model=self.model,
+                    prompt_tokens=prompt_t,
+                    completion_tokens=completion_t,
+                    cost_usd=cost,
+                )
+
+        # ---- Structured parse ---------------------------------------------
+        try:
+            structured = parse_structured_response(
+                content,
+                agent_kid=agent_kid,
+                token_usage=token_usage,
+            )
+        except ValueError as exc:
+            raise LLMResponderError(
+                f"OpenAI response did not contain a valid 'confidence' field: {exc}"
+            ) from exc
+
+        confidence = structured.confidence
+        # Preserve the v0.5 single-tuple sink for callers that read it.
+        self.last_response = (confidence, structured.reasoning)
+        self.last_structured = structured
+
+        unc = confidence_to_uncertainty(confidence, effective_n=self.effective_n)
+
+        # When capture_structured is False we still return a tuple — the
+        # dispatch unpacker handles both. Callers that want the bare
+        # Uncertainty back can read it from the tuple directly.
+        return unc, structured