hypermind 0.11.0__py3-none-any.whl

hypermind/api/app.py

@@ -0,0 +1,686 @@
+"""HTTP management API ASGI app — ``management_app(agent)``.
+
+Surface is intentionally small: every route corresponds 1:1 to a public
+``HyperMindAgent`` verb. No CRUD on internal state; no admin overrides.
+The agent's existing ramp + capability gates fully apply.
+
+Auth is out of scope for v0.5 — operators put this behind their own
+proxy (Caddy, Envoy, Tailscale ACL) until v0.6's TLS+mTLS story lands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Awaitable, Callable
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any
+
+from hypermind.observability.asgi import asgi_app as _obs_app
+from hypermind.uncertainty import Uncertainty
+
+if TYPE_CHECKING:
+    from hypermind.agent import HyperMindAgent
+
+
+_Send = Callable[[dict[str, Any]], Awaitable[None]]
+_Receive = Callable[[], Awaitable[dict[str, Any]]]
+_Scope = dict[str, Any]
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+
+async def _read_body(receive: _Receive) -> bytes:
+    body = b""
+    while True:
+        msg = await receive()
+        body += msg.get("body", b"")
+        if not msg.get("more_body", False):
+            break
+    return body
+
+
+async def _send_json(send: _Send, *, status: int, payload: Any) -> None:
+    body = json.dumps(payload, default=_json_default).encode("utf-8")
+    await send(
+        {
+            "type": "http.response.start",
+            "status": status,
+            "headers": [
+                (b"content-type", b"application/json"),
+                (b"content-length", str(len(body)).encode()),
+            ],
+        }
+    )
+    await send({"type": "http.response.body", "body": body, "more_body": False})
+
+
+def _json_default(obj: Any) -> Any:
+    if isinstance(obj, (bytes, bytearray)):
+        return obj.hex()
+    if hasattr(obj, "to_dict"):
+        return obj.to_dict()
+    if hasattr(obj, "__dict__"):
+        return obj.__dict__
+    return str(obj)
+
+
+def _err(send: _Send, status: int, message: str, *, rule_id: str | None = None) -> Awaitable[None]:
+    payload: dict[str, Any] = {"error": message}
+    if rule_id:
+        payload["rule_id"] = rule_id
+    return _send_json(send, status=status, payload=payload)
+
+
+def _parse_kid(s: str) -> bytes:
+    s = s.strip().lower().removesuffix("…").rstrip(".")
+    return bytes.fromhex(s)
+
+
+# --------------------------------------------------------------------------
+# Route handlers
+# --------------------------------------------------------------------------
+
+
+async def _handle_publish(agent: HyperMindAgent, body: bytes, send: _Send) -> None:
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+
+    claim_payload = payload.get("payload")
+    claim_type = payload.get("claim_type", "custom")
+    topic = payload.get("topic")
+    unc_dict = payload.get("uncertainty", {})
+
+    if claim_payload is None:
+        await _err(send, 400, "missing field: payload")
+        return
+
+    # Build Uncertainty from a small JSON shape
+    try:
+        unc = _uncertainty_from_dict(unc_dict)
+    except (KeyError, ValueError) as exc:
+        await _err(send, 400, f"invalid uncertainty: {exc}")
+        return
+
+    try:
+        kid = await agent.publish_claim(
+            payload=claim_payload,
+            claim_type=claim_type,
+            uncertainty=unc,
+            topic=topic,
+        )
+    except Exception as exc:
+        rule_id = getattr(exc, "rule_id", None)
+        await _err(send, 422, str(exc), rule_id=rule_id)
+        return
+
+    await _send_json(send, status=201, payload={"kid": kid.hex()})
+
+
+def _uncertainty_from_dict(d: dict[str, Any]) -> Uncertainty:
+    """Tiny JSON shape for Uncertainty.
+
+    Accepts:
+        {"kind": "beta", "alpha": 8, "beta": 2}
+        {"kind": "gauss", "mu": 0.5, "sigma2": 0.01}
+        {"kind": "unknown"}
+        {"kind": "point", "value": 0.7}
+        {"confidence": 0.8}                  # short form, maps to Beta(8, 2)
+    """
+    if not d:
+        return Uncertainty.unknown()
+    kind = d.get("kind")
+    if kind == "beta":
+        return Uncertainty.beta(alpha=float(d["alpha"]), beta=float(d["beta"]))
+    if kind == "gauss":
+        return Uncertainty.gauss(mu=float(d["mu"]), sigma2=float(d["sigma2"]))
+    if kind == "unknown":
+        return Uncertainty.unknown()
+    if kind == "point":
+        return Uncertainty.point(float(d["value"]))
+    if "confidence" in d:
+        # Default short form
+        from hypermind.responders.base import confidence_to_uncertainty
+
+        return confidence_to_uncertainty(float(d["confidence"]))
+    raise ValueError(f"unknown uncertainty kind: {kind!r}")
+
+
+async def _handle_get_claim(agent: HyperMindAgent, kid_hex: str, send: _Send) -> None:
+    if agent._world is None:
+        await _err(send, 404, "no world attached")
+        return
+    try:
+        kid = _parse_kid(kid_hex)
+    except ValueError:
+        await _err(send, 400, f"invalid kid hex: {kid_hex!r}")
+        return
+    stmt = agent._world.sealed.get(kid)
+    if stmt is None:
+        await _err(send, 404, "claim not found")
+        return
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "kid": stmt.kid.hex(),
+            "issuer_kid": stmt.issuer_kid.hex(),
+            "record_type": stmt.record_type,
+            "alg": stmt.alg,
+            "hlc": str(stmt.hlc),
+            "namespace_id": stmt.namespace_id.hex(),
+            "wire_size": len(stmt.to_bytes()),
+        },
+    )
+
+
+async def _handle_audit(agent: HyperMindAgent, since_hlc: str | None, send: _Send) -> None:
+    records: list[dict[str, Any]] = []
+    try:
+        async for line in agent.audit_export(since_hlc=since_hlc):
+            decoded = line.decode() if isinstance(line, bytes) else line
+            # audit_export emits "JSONL\tHEX-SIG"
+            try:
+                json_part, sig_part = decoded.split("\t", 1)
+                rec = json.loads(json_part)
+                rec["_signature"] = sig_part.strip()
+                records.append(rec)
+            except (ValueError, json.JSONDecodeError):
+                records.append({"raw": decoded})
+    except Exception as exc:
+        await _err(send, 500, f"audit export failed: {exc}")
+        return
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "count": len(records),
+            "records": records,
+        },
+    )
+
+
+async def _handle_reputation(
+    agent: HyperMindAgent,
+    kid_hex: str,
+    topic: str | None,
+    send: _Send,
+) -> None:
+    try:
+        target_kid = _parse_kid(kid_hex)
+    except ValueError:
+        await _err(send, 400, f"invalid kid hex: {kid_hex!r}")
+        return
+    try:
+        snap = await agent.reputation_of(target_kid, topic=topic or "default")
+    except Exception as exc:
+        await _err(send, 500, str(exc))
+        return
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "agent_kid": snap.agent_id.hex(),
+            "topic": snap.topic,
+            "score": snap.score,
+            "n_observations": snap.n_observations,
+            "last_updated_ms": snap.last_updated_ms,
+            "momentum_z": snap.momentum_z,
+        },
+    )
+
+
+async def _handle_disputes(agent: HyperMindAgent, send: _Send) -> None:
+    if agent._world is None:
+        await _send_json(send, status=200, payload={"disputes": []})
+        return
+    items = []
+    for kid, dispute in agent._world.disputes.items():
+        items.append(
+            {
+                "claim_kid": kid.hex(),
+                "initiator": dispute.initiator.hex(),
+                "state": str(dispute.state),
+                "bond_topic_scope": dispute.bond_topic_scope,
+                "bond_amount": dispute.bond_amount,
+                "transitions": [
+                    {"state": str(s), "ms": ms, "reason": reason}
+                    for s, ms, reason in dispute.transitions
+                ],
+            }
+        )
+    await _send_json(send, status=200, payload={"count": len(items), "disputes": items})
+
+
+async def _handle_consult(agent: HyperMindAgent, body: bytes, send: _Send) -> None:
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+
+    query = payload.get("query")
+    if not query:
+        await _err(send, 400, "missing field: query")
+        return
+    panel_size = int(payload.get("panel_size", 5))
+    route_strategy = payload.get("route_strategy", "disagreement")
+    topic = payload.get("topic")
+    timeout_s = float(payload.get("timeout_s", 30.0))
+
+    try:
+        result = await agent.consult(
+            query,
+            panel_size=panel_size,
+            route_strategy=route_strategy,
+            topic=topic,
+            timeout=timedelta(seconds=timeout_s),
+        )
+    except Exception as exc:
+        rule_id = getattr(exc, "rule_id", None)
+        await _err(send, 422, str(exc), rule_id=rule_id)
+        return
+
+    await _send_json(
+        send,
+        status=200,
+        payload={
+            "query": query,
+            "posterior_mean": result.posterior.mean(),
+            "disagreement": result.disagreement,
+            "panel_size": len(result.panel),
+            "panel": [
+                {
+                    "agent_kid": m.agent_id.hex(),
+                    "weight": m.weight,
+                    "posterior_mean": m.posterior.mean(),
+                }
+                for m in result.panel
+            ],
+            "receipt_kid": result.receipt_kid.hex() if result.receipt_kid else None,
+        },
+    )
+
+
+async def _handle_introspect(agent: HyperMindAgent, send: _Send) -> None:
+    try:
+        info = await agent.introspect()
+    except Exception as exc:
+        await _err(send, 500, str(exc))
+        return
+    await _send_json(send, status=200, payload=info)
+
+
+async def _handle_stats(agent: HyperMindAgent, send: _Send) -> None:
+    payload: dict[str, Any] = {
+        "agent_kid": agent.keypair.kid.hex(),
+        "did_key": agent.keypair.did_key,
+        "namespace": agent.namespace,
+        "rooms": list(agent.rooms),
+        "role": agent.role,
+        "ramp_paused": getattr(agent, "_ramp_paused", False),
+    }
+    if agent._world is not None:
+        payload["world"] = {
+            "namespace_id": agent._world.namespace_id.hex(),
+            "sealed_count": len(agent._world.sealed),
+            "dispute_count": len(agent._world.disputes),
+            "tree_size": agent._world.ts.size() if agent._world.ts else 0,
+        }
+        if agent._world.storage is not None:
+            try:
+                payload["storage"] = agent._world.storage.stats()
+            except Exception:
+                payload["storage"] = {"error": "stats unavailable"}
+    await _send_json(send, status=200, payload=payload)
+
+
+async def _handle_calibration(
+    agent: HyperMindAgent,
+    body: bytes,
+    send: _Send,
+) -> None:
+    """POST /v1/calibration — return per-(agent_kid, topic) Brier history."""
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+    kid_hex = payload.get("agent_kid")
+    topic = payload.get("topic", "default")
+    if not kid_hex:
+        await _err(send, 400, "missing field: agent_kid")
+        return
+    try:
+        kid = _parse_kid(kid_hex)
+    except ValueError:
+        await _err(send, 400, f"invalid kid hex: {kid_hex!r}")
+        return
+    if agent._world is None:
+        await _err(send, 404, "no world attached")
+        return
+    out = agent._world.reputation.brier_tracker.to_dict(kid, topic)
+    if out["n_observations"] == 0:
+        await _err(send, 404, f"no calibration history for {kid_hex[:16]}…/{topic}")
+        return
+    await _send_json(send, status=200, payload=out)
+
+
+async def _handle_cost(
+    agent: HyperMindAgent,
+    query_params: dict[str, str],
+    send: _Send,
+) -> None:
+    """GET /v1/cost — return TokenCostTracker aggregate."""
+    if agent._world is None or agent._world.cost_tracker is None:
+        await _send_json(
+            send,
+            status=200,
+            payload={
+                "n_calls": 0,
+                "total_tokens": 0,
+                "total_usd": 0.0,
+                "by_model": {},
+            },
+        )
+        return
+    tracker = agent._world.cost_tracker
+    if "agent_kid" in query_params or "model" in query_params:
+        kid_hex = query_params.get("agent_kid")
+        model = query_params.get("model")
+        kid_bytes = None
+        if kid_hex:
+            try:
+                kid_bytes = _parse_kid(kid_hex)
+            except ValueError:
+                await _err(send, 400, f"invalid kid hex: {kid_hex!r}")
+                return
+        await _send_json(
+            send,
+            status=200,
+            payload={
+                "filter": {"agent_kid": kid_hex, "model": model},
+                "total_usd": tracker.total_usd(agent_kid=kid_bytes, model=model),
+                "total_tokens": tracker.total_tokens(agent_kid=kid_bytes, model=model),
+            },
+        )
+        return
+    await _send_json(send, status=200, payload=tracker.to_dict())
+
+
+async def _handle_eval_compare(
+    agent: HyperMindAgent,
+    body: bytes,
+    send: _Send,
+) -> None:
+    """POST /v1/eval/compare — A/B compare static-config responders.
+
+    For safety the HTTP endpoint accepts only StaticResponder configs;
+    callers wanting LLM comparison should use the Python API.
+    """
+    from hypermind.eval import compare_responders
+    from hypermind.responders import StaticResponder
+    from hypermind.uncertainty import Uncertainty
+
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+
+    questions = payload.get("question_set") or payload.get("questions") or []
+    responders_cfg = payload.get("responders") or {}
+    if not questions or not responders_cfg:
+        await _err(send, 400, "need both 'question_set' and 'responders'")
+        return
+
+    built: dict[str, Any] = {}
+    for name, cfg in responders_cfg.items():
+        kind = cfg.get("kind", "static")
+        if kind != "static":
+            await _err(send, 400, f"only kind=static supported in HTTP API; got {kind!r}")
+            return
+        confidence = float(cfg.get("confidence", 0.5))
+        unc = Uncertainty.beta(
+            max(1.0, confidence * 10),
+            max(1.0, (1 - confidence) * 10),
+        )
+        built[name] = StaticResponder(unc)
+
+    report = await compare_responders(
+        questions,
+        built,
+        question_set_id=payload.get("question_set_id", ""),
+    )
+    await _send_json(send, status=200, payload=report.to_dict())
+
+
+async def _handle_events_stream(
+    agent: HyperMindAgent,
+    send: _Send,
+) -> None:
+    """GET /v1/events/stream — Server-Sent Events of recorder events.
+
+    Each event is one ``LogRecord`` serialised as JSON with these fields:
+        ts_wall_ms, namespace, agent_id, event_type, severity, fields
+
+    The endpoint never closes — clients (e.g. ``EventSource`` in a
+    browser) keep the connection open and reconnect automatically on
+    drop. We send a heartbeat comment every 15s to keep proxies happy.
+    """
+    if agent._world is None:
+        await _err(send, 404, "no world attached")
+        return
+
+    recorder = agent._world.recorder
+    # SSE headers
+    await send(
+        {
+            "type": "http.response.start",
+            "status": 200,
+            "headers": [
+                (b"content-type", b"text/event-stream"),
+                (b"cache-control", b"no-cache"),
+                (b"connection", b"keep-alive"),
+                (b"access-control-allow-origin", b"*"),
+            ],
+        }
+    )
+
+    # Send an initial comment so the client knows we're connected
+    await send(
+        {
+            "type": "http.response.body",
+            "body": b": connected\n\n",
+            "more_body": True,
+        }
+    )
+
+    try:
+        async for record in recorder.tail():
+            payload = {
+                "ts_wall_ms": record.ts_wall_ms,
+                "namespace": record.namespace,
+                "agent_id": record.agent_id,
+                "event_type": record.event_type,
+                "severity": record.severity,
+                "fields": record.fields,
+            }
+            chunk = f"data: {json.dumps(payload)}\n\n".encode()
+            await send(
+                {
+                    "type": "http.response.body",
+                    "body": chunk,
+                    "more_body": True,
+                }
+            )
+    except (asyncio.CancelledError, GeneratorExit):
+        # Client disconnected — clean exit
+        return
+    except Exception:
+        return
+
+
+async def _handle_replay(
+    agent: HyperMindAgent,
+    body: bytes,
+    send: _Send,
+) -> None:
+    """POST /v1/replay — replay an audit log (provided as JSONL bytes)."""
+    from hypermind.eval.replay import replay_lines
+
+    try:
+        payload = json.loads(body) if body else {}
+    except json.JSONDecodeError as exc:
+        await _err(send, 400, f"invalid JSON: {exc}")
+        return
+
+    audit_text = payload.get("audit_text", "")
+    if not audit_text:
+        await _err(send, 400, "missing 'audit_text' (JSONL string)")
+        return
+    verify_signatures = bool(payload.get("verify_signatures", True))
+    result = replay_lines(
+        audit_text.splitlines(),
+        verify_signatures=verify_signatures,
+    )
+    await _send_json(send, status=200, payload=result.to_dict())
+
+
+# --------------------------------------------------------------------------
+# Router
+# --------------------------------------------------------------------------
+
+
+def management_app(
+    agent: HyperMindAgent,
+) -> Callable[[_Scope, _Receive, _Send], Awaitable[None]]:
+    """Return an ASGI 3 app that exposes ``agent`` over HTTP.
+
+    Routes:
+        GET  /healthz                       — liveness probe
+        GET  /metrics                       — Prometheus scrape (text 0.0.4)
+        GET  /v1/stats                      — agent + world summary
+        GET  /v1/introspect                 — full introspection payload
+        POST /v1/claims                     — publish a claim
+        GET  /v1/claims/{kid}               — fetch a claim by kid
+        GET  /v1/audit?since_hlc=...        — stream signed audit log
+        GET  /v1/reputation/{kid}?topic=... — read reputation
+        GET  /v1/disputes                   — list active disputes
+        POST /v1/consult                    — run a panel consult
+    """
+    obs_app = _obs_app(recorder=agent._world.recorder if agent._world else None)
+
+    async def app(scope: _Scope, receive: _Receive, send: _Send) -> None:
+        if scope["type"] == "lifespan":
+            while True:
+                msg = await receive()
+                if msg["type"] == "lifespan.startup":
+                    await send({"type": "lifespan.startup.complete"})
+                elif msg["type"] == "lifespan.shutdown":
+                    await send({"type": "lifespan.shutdown.complete"})
+                    return
+
+        if scope["type"] != "http":
+            return
+
+        method: str = scope.get("method", "GET").upper()
+        path: str = scope.get("path", "/")
+        qs: bytes = scope.get("query_string", b"")
+        params = _parse_qs(qs)
+
+        # Delegate /healthz, /metrics to the observability app
+        if path in ("/healthz", "/metrics"):
+            await obs_app(scope, receive, send)
+            return
+
+        # ---- v1 routes ---------------------------------------------------
+        if method == "GET" and path == "/v1/stats":
+            await _handle_stats(agent, send)
+            return
+
+        if method == "GET" and path == "/v1/introspect":
+            await _handle_introspect(agent, send)
+            return
+
+        if method == "POST" and path == "/v1/claims":
+            body = await _read_body(receive)
+            await _handle_publish(agent, body, send)
+            return
+
+        if method == "GET" and path.startswith("/v1/claims/"):
+            kid_hex = path[len("/v1/claims/") :]
+            await _handle_get_claim(agent, kid_hex, send)
+            return
+
+        if method == "GET" and path == "/v1/audit":
+            since = params.get("since_hlc")
+            await _handle_audit(agent, since, send)
+            return
+
+        if method == "GET" and path.startswith("/v1/reputation/"):
+            kid_hex = path[len("/v1/reputation/") :]
+            topic = params.get("topic")
+            await _handle_reputation(agent, kid_hex, topic, send)
+            return
+
+        if method == "GET" and path == "/v1/disputes":
+            await _handle_disputes(agent, send)
+            return
+
+        if method == "POST" and path == "/v1/consult":
+            body = await _read_body(receive)
+            await _handle_consult(agent, body, send)
+            return
+
+        # ---- v0.6 eval routes ----
+        if method == "POST" and path == "/v1/calibration":
+            body = await _read_body(receive)
+            await _handle_calibration(agent, body, send)
+            return
+
+        if method == "GET" and path == "/v1/cost":
+            await _handle_cost(agent, params, send)
+            return
+
+        if method == "POST" and path == "/v1/eval/compare":
+            body = await _read_body(receive)
+            await _handle_eval_compare(agent, body, send)
+            return
+
+        if method == "POST" and path == "/v1/replay":
+            body = await _read_body(receive)
+            await _handle_replay(agent, body, send)
+            return
+
+        if method == "GET" and path == "/v1/events/stream":
+            await _handle_events_stream(agent, send)
+            return
+
+        # Fallback
+        await _err(send, 404, f"unknown route: {method} {path}")
+
+    return app
+
+
+def _parse_qs(qs: bytes) -> dict[str, str]:
+    """Tiny QS parser — first value wins, no list-of-values support."""
+    out: dict[str, str] = {}
+    for pair in qs.split(b"&"):
+        if not pair:
+            continue
+        if b"=" in pair:
+            k, v = pair.split(b"=", 1)
+        else:
+            k, v = pair, b""
+        try:
+            out[k.decode("utf-8")] = v.decode("utf-8")
+        except UnicodeDecodeError:
+            continue
+    return out