hypermind 0.11.0__py3-none-any.whl

hypermind/agent_card.py

@@ -0,0 +1,127 @@
+"""AgentCard — signed self-description for agent discovery (spec §3.2).
+
+An AgentCard is published by an agent as a regular sealed claim (claim_type
+"agent_card") so peers can discover its capabilities, supported topics, roles,
+and contact endpoint. It rides in the standard SEAL SignedStatement envelope
+and is stored in the shared transparency log like any other claim.
+
+Spec reference: draft-hypermind-scitt-contested-claims-profile-00 §3.2 and
+the A2A bridge normative requirement at §4.12.1.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["AgentCard"]
+
+
+@dataclass
+class AgentCard:
+    """Signed self-description published by an agent for peer discovery.
+
+    Fields mirror spec §3.2.  All fields are optional except ``agent_kid``,
+    which is the 32-byte Ed25519 public-key half used as the stable agent
+    address.
+
+    Serialisation contract
+    ----------------------
+    ``to_payload()`` / ``from_payload()`` are the only public serialisation
+    primitives; they produce/consume a plain ``dict`` that the standard
+    ``publish_claim`` payload pipeline can embed directly.  The ``agent_kid``
+    is encoded as a lowercase hex string so the JSON/CBOR payload layer
+    does not need to handle raw bytes.
+
+    Usage::
+
+        card = AgentCard(
+            agent_kid=agent.keypair.kid,
+            display_name="Alice the Scout",
+            topics=["ai-safety-evals", "threat-intel"],
+            roles=["Scout"],
+            sdk_version="0.10.0",
+        )
+        kid = await agent.publish_card(card)
+    """
+
+    agent_kid: bytes
+    """32-byte Ed25519 public-key half; the stable agent address."""
+
+    display_name: str = ""
+    """Human-readable name shown in dashboards and dispute panels."""
+
+    topics: list[str] = field(default_factory=list)
+    """Topic strings this agent is willing to engage on."""
+
+    roles: list[str] = field(default_factory=list)
+    """Role bundle names (Scout, Sceptic, Generalist, Synthesist, Mediator, Oracle)."""
+
+    capabilities: list[str] = field(default_factory=list)
+    """Advertised CapToken caveat kinds (e.g. "topic", "rate", "expiry")."""
+
+    endpoint: str = ""
+    """Optional contact endpoint URI (A2A / MCP server URL; see §4.12)."""
+
+    sdk_version: str = ""
+    """SDK version string, e.g. "0.10.0"."""
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    """Arbitrary extra fields; preserved round-trip but not interpreted."""
+
+    # ------------------------------------------------------------------
+    # Serialisation helpers
+    # ------------------------------------------------------------------
+
+    def to_payload(self) -> dict[str, Any]:
+        """Serialise to a JSON-serialisable dict for embedding in a claim payload.
+
+        ``agent_kid`` is hex-encoded so the payload is safe for JSON and
+        deterministic CBOR transport layers.
+        """
+        if len(self.agent_kid) != 32:
+            raise ValueError(
+                f"agent_kid must be exactly 32 bytes; got {len(self.agent_kid)}"
+            )
+        return {
+            "agent_kid": self.agent_kid.hex(),
+            "display_name": self.display_name,
+            "topics": list(self.topics),
+            "roles": list(self.roles),
+            "capabilities": list(self.capabilities),
+            "endpoint": self.endpoint,
+            "sdk_version": self.sdk_version,
+            "metadata": dict(self.metadata),
+        }
+
+    @classmethod
+    def from_payload(cls, payload: dict[str, Any]) -> AgentCard:
+        """Deserialise from a claim payload dict produced by ``to_payload()``.
+
+        Raises ``ValueError`` if the required ``agent_kid`` field is missing or
+        the hex string does not decode to exactly 32 bytes.
+        """
+        if "agent_kid" not in payload:
+            raise ValueError("AgentCard payload missing required field 'agent_kid'")
+        agent_kid = bytes.fromhex(payload["agent_kid"])
+        if len(agent_kid) != 32:
+            raise ValueError(
+                f"agent_kid must decode to 32 bytes; got {len(agent_kid)}"
+            )
+        return cls(
+            agent_kid=agent_kid,
+            display_name=payload.get("display_name", ""),
+            topics=list(payload.get("topics", [])),
+            roles=list(payload.get("roles", [])),
+            capabilities=list(payload.get("capabilities", [])),
+            endpoint=payload.get("endpoint", ""),
+            sdk_version=payload.get("sdk_version", ""),
+            metadata=dict(payload.get("metadata", {})),
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"AgentCard(kid={self.agent_kid.hex()[:12]}... "
+            f"name={self.display_name!r} "
+            f"topics={self.topics!r})"
+        )

hypermind/api/__init__.py

@@ -0,0 +1,32 @@
+"""HTTP management API for a HyperMindAgent.
+
+Wraps a single agent in an ASGI 3 app so non-Python callers can:
+
+  * publish claims (POST /v1/claims)
+  * query a claim by kid (GET /v1/claims/{kid})
+  * stream the audit log (GET /v1/audit)
+  * read reputation (GET /v1/reputation/{agent_kid}?topic=...)
+  * list disputes (GET /v1/disputes)
+  * run a panel consult (POST /v1/consult)
+  * read agent introspection (GET /v1/introspect)
+  * read storage / health stats (GET /v1/stats, /healthz)
+  * scrape Prometheus metrics (GET /metrics)
+
+Zero hard dependencies — pure ASGI 3, JSON only, runs under any ASGI
+server (uvicorn, hypercorn, daphne).
+
+Mount under uvicorn::
+
+    from hypermind import HyperMindAgent
+    from hypermind.api import management_app
+
+    agent = HyperMindAgent.sandbox(room="prod")
+    app = management_app(agent)
+    # uvicorn.run(app, host="0.0.0.0", port=8080)
+"""
+
+from __future__ import annotations
+
+from hypermind.api.app import management_app
+
+__all__ = ["management_app"]