agent-handshake 0.7.0__py3-none-any.whl

agent_handshake/__init__.py

@@ -0,0 +1,74 @@
+"""agent-handshake: The open specification for agent-to-agent interactions."""
+
+__version__ = "0.7.0"
+
+from agent_handshake.adapters.a2a_adapter import A2AAdapter
+from agent_handshake.adapters.base import AgentAdapter, AgentMetadata, AgentResponse
+from agent_handshake.adapters.function_adapter import FunctionAdapter
+from agent_handshake.adapters.http_adapter import HTTPAdapter
+from agent_handshake.adapters.langchain_adapter import LangChainAdapter
+from agent_handshake.config.loader import load_config
+from agent_handshake.config.settings import HandshakeConfig
+from agent_handshake.diff.engine import DiffEngine, DiffResult, DriftSeverity
+from agent_handshake.exceptions import (
+    AdapterError,
+    ConfigError,
+    HandshakeError,
+    PipelineExecutionError,
+    PolicyViolationError,
+    SemanticDriftError,
+    SnapshotMismatchError,
+    SnapshotNotFoundError,
+    SpecValidationError,
+)
+from agent_handshake.pipeline.executor import PipelineExecutor
+from agent_handshake.pipeline.trace import PipelineTrace
+from agent_handshake.snapshot.recorder import Recorder
+from agent_handshake.snapshot.replay import ReplayEngine
+from agent_handshake.snapshot.store import SnapshotStore
+from agent_handshake.spec.loader import load_spec
+from agent_handshake.spec.schema import PolicyRule, SemanticRule, Spec, StructuralSpec
+from agent_handshake.spec.validator import validate_output
+
+__all__ = [
+    "__version__",
+    # Spec
+    "Spec",
+    "StructuralSpec",
+    "SemanticRule",
+    "PolicyRule",
+    "load_spec",
+    "validate_output",
+    # Snapshots
+    "SnapshotStore",
+    "Recorder",
+    "ReplayEngine",
+    # Diff
+    "DiffEngine",
+    "DiffResult",
+    "DriftSeverity",
+    # Pipeline
+    "PipelineExecutor",
+    "PipelineTrace",
+    # Adapters
+    "A2AAdapter",
+    "AgentAdapter",
+    "AgentResponse",
+    "AgentMetadata",
+    "FunctionAdapter",
+    "HTTPAdapter",
+    "LangChainAdapter",
+    # Config
+    "HandshakeConfig",
+    "load_config",
+    # Exceptions
+    "HandshakeError",
+    "SpecValidationError",
+    "SnapshotNotFoundError",
+    "SnapshotMismatchError",
+    "SemanticDriftError",
+    "PolicyViolationError",
+    "PipelineExecutionError",
+    "AdapterError",
+    "ConfigError",
+]

agent_handshake/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal utilities for agent-handshake. Not part of the public API."""

agent_handshake/_internal/hashing.py

@@ -0,0 +1,23 @@
+"""Hashing utilities."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+
+def hash_dict(data: dict[str, Any]) -> str:
+    """Deterministic SHA256 hash of a dict."""
+    content = json.dumps(data, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(content.encode()).hexdigest()
+
+
+def short_hash(data: dict[str, Any], length: int = 12) -> str:
+    """Short deterministic hash of a dict."""
+    return hash_dict(data)[:length]
+
+
+def hash_string(text: str) -> str:
+    """SHA256 hash of a string."""
+    return hashlib.sha256(text.encode()).hexdigest()

agent_handshake/_internal/safe_eval.py

@@ -0,0 +1,119 @@
+"""Sandboxed expression evaluation for pipeline conditions.
+
+SECURITY: This uses a restricted AST evaluator, NOT raw eval().
+Only comparison operators, attribute access, and literals are allowed.
+No function calls, imports, or assignments.
+"""
+
+from __future__ import annotations
+
+import ast
+import operator
+from typing import Any
+
+# Allowed binary comparison operators
+_OPERATORS: dict[type, Any] = {
+    ast.Eq: operator.eq,
+    ast.NotEq: operator.ne,
+    ast.Lt: operator.lt,
+    ast.LtE: operator.le,
+    ast.Gt: operator.gt,
+    ast.GtE: operator.ge,
+}
+
+# Allowed boolean operators
+_BOOL_OPS: dict[type, Any] = {
+    ast.And: all,
+    ast.Or: any,
+}
+
+
+class _SafeEvaluator(ast.NodeVisitor):
+    """Restricted AST evaluator."""
+
+    def __init__(self, context: dict[str, Any]) -> None:
+        self.context = context
+
+    def evaluate(self, expr: str) -> Any:
+        """Evaluate an expression string against the context."""
+        tree = ast.parse(expr, mode="eval")
+        return self.visit(tree.body)
+
+    def visit_Compare(self, node: ast.Compare) -> bool:
+        """Handle comparison operations (==, !=, <, >, etc.)."""
+        left = self.visit(node.left)
+        for op_node, comparator in zip(node.ops, node.comparators):
+            op_type = type(op_node)
+            if op_type not in _OPERATORS:
+                raise ValueError(f"Unsupported operator: {op_type.__name__}")
+            right = self.visit(comparator)
+            if not _OPERATORS[op_type](left, right):
+                return False
+            left = right
+        return True
+
+    def visit_BoolOp(self, node: ast.BoolOp) -> bool:
+        """Handle boolean operations (and, or)."""
+        op_type = type(node.op)
+        if op_type not in _BOOL_OPS:
+            raise ValueError(f"Unsupported bool operator: {op_type.__name__}")
+        values = [self.visit(v) for v in node.values]
+        return bool(_BOOL_OPS[op_type](values))
+
+    def visit_Attribute(self, node: ast.Attribute) -> Any:
+        """Handle attribute access (e.g., output.category)."""
+        obj = self.visit(node.value)
+        if isinstance(obj, dict):
+            return obj.get(node.attr)
+        return getattr(obj, node.attr, None)
+
+    def visit_Subscript(self, node: ast.Subscript) -> Any:
+        """Handle subscript access (e.g., output['key'])."""
+        obj = self.visit(node.value)
+        key = self.visit(node.slice)
+        return obj[key]
+
+    def visit_Name(self, node: ast.Name) -> Any:
+        """Handle variable name resolution."""
+        if node.id not in self.context:
+            raise ValueError(f"Unknown variable: '{node.id}'")
+        return self.context[node.id]
+
+    def visit_Constant(self, node: ast.Constant) -> Any:
+        """Handle literal values (strings, numbers, booleans)."""
+        return node.value
+
+    def visit_List(self, node: ast.List) -> list[Any]:
+        """Handle list literals."""
+        return [self.visit(el) for el in node.elts]
+
+    def visit_Tuple(self, node: ast.Tuple) -> tuple[Any, ...]:
+        """Handle tuple literals."""
+        return tuple(self.visit(el) for el in node.elts)
+
+    def generic_visit(self, node: ast.AST) -> None:
+        """Reject any unsupported AST nodes."""
+        raise ValueError(
+            f"Unsupported expression element: {type(node).__name__}. "
+            f"Only comparisons, attribute access, and literals are allowed."
+        )
+
+
+def safe_evaluate(expression: str, context: dict[str, Any]) -> Any:
+    """Safely evaluate an expression against a context dict.
+
+    Only supports: comparisons, boolean ops, attribute access,
+    subscript access, and literals. No function calls or imports.
+
+    Args:
+        expression: The expression string (e.g., "output.category == 'billing'").
+        context: Variables available in the expression.
+
+    Returns:
+        The evaluation result.
+
+    Raises:
+        ValueError: If the expression contains unsupported operations.
+    """
+    evaluator = _SafeEvaluator(context)
+    return evaluator.evaluate(expression)

agent_handshake/_internal/types.py

@@ -0,0 +1,14 @@
+"""Shared type aliases."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+# Common type aliases used across the codebase
+JsonDict = dict[str, Any]
+
+
+class ValidatorFn(Protocol):
+    """Protocol for custom policy validator functions."""
+
+    def __call__(self, output: dict[str, Any], input_data: dict[str, Any]) -> tuple[bool, str]: ...

agent_handshake/adapters/__init__.py

@@ -0,0 +1 @@
+"""Agent adapters for wrapping different agent types."""

agent_handshake/adapters/a2a_adapter.py

@@ -0,0 +1,256 @@
+"""Adapter for agents that speak the A2A protocol (version 1.0, JSON-RPC)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import json
+import time
+import uuid
+from typing import Any
+from urllib.parse import urljoin
+
+import httpx
+
+from agent_handshake.adapters.base import AgentAdapter, AgentMetadata, AgentResponse
+from agent_handshake.exceptions import AdapterError
+
+AGENT_CARD_PATH = "/.well-known/agent-card.json"
+PROTOCOL_VERSION = "1.0"
+
+
+class A2AAdapter(AgentAdapter):
+    """Calls an A2A agent through its Agent Card and the JSON-RPC binding.
+
+    The input dict is sent as one structured ``data`` part, or, with
+    ``text_field``, that field's value is sent as a ``text`` part. The reply
+    (a Message, or the artifacts of a completed Task) becomes the output
+    dict: ``data`` parts holding objects are merged, ``text`` parts are joined
+    under ``"text"``, and file parts (``raw`` or ``url``) are listed under
+    ``"files"``. A ``url`` file keeps its URL; a ``raw`` file is described by
+    its ``size`` and ``sha256`` instead of its bytes, so snapshots stay small.
+    With ``json_text=True`` a text-only reply that is a JSON object is used as
+    the output directly.
+
+    Usage:
+        adapter = A2AAdapter(
+            url="https://triage.example.com",   # or the agent card URL
+            agent_id="triage-agent",
+        )
+    """
+
+    def __init__(
+        self,
+        url: str,
+        agent_id: str,
+        version: str | None = None,
+        text_field: str | None = None,
+        json_text: bool = False,
+        headers: dict[str, str] | None = None,
+        timeout: float = 60.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._card_url = url if url.endswith(".json") else url.rstrip("/") + AGENT_CARD_PATH
+        self._agent_id = agent_id
+        self._version = version
+        self._text_field = text_field
+        self._json_text = json_text
+        self._headers = headers or {}
+        self._timeout = timeout
+        self._transport = transport
+        self._card: dict[str, Any] | None = None
+        self._endpoint: tuple[str, str | None] | None = None
+
+    def get_metadata(self) -> AgentMetadata:
+        """Return metadata; the version comes from the Agent Card once fetched."""
+        version = self._version or (self._card or {}).get("version") or "unknown"
+        return AgentMetadata(agent_id=self._agent_id, version=str(version))
+
+    async def health_check(self) -> bool:
+        """Return True if the Agent Card can be fetched and offers JSON-RPC 1.0."""
+        try:
+            async with self._client() as client:
+                await self._resolve(client)
+        except AdapterError:
+            return False
+        return True
+
+    async def call(self, input_data: dict[str, Any]) -> AgentResponse:
+        """Send the input as an A2A message and return the agent's reply.
+
+        Raises:
+            AdapterError: If the card or endpoint is unusable, the agent returns
+                a JSON-RPC error, or the task does not complete.
+        """
+        start = time.monotonic()
+        async with self._client() as client:
+            rpc_url, tenant = await self._resolve(client)
+            params: dict[str, Any] = {"message": self._message(input_data)}
+            if tenant:
+                params["tenant"] = tenant
+            body = {
+                "jsonrpc": "2.0",
+                "id": str(uuid.uuid4()),
+                "method": "SendMessage",
+                "params": params,
+            }
+            reply = await self._post(client, rpc_url, body)
+        latency = (time.monotonic() - start) * 1000
+
+        if "error" in reply:
+            err = reply["error"] or {}
+            raise AdapterError(
+                self._agent_id, f"A2A error {err.get('code')}: {err.get('message', '')}"
+            )
+        result = reply.get("result") or {}
+        meta: dict[str, Any] = {}
+        if "task" in result:
+            task = result["task"]
+            parts = self._task_parts(task)
+            meta = {"task_id": task.get("id"), "context_id": task.get("contextId")}
+        elif "message" in result:
+            parts = result["message"].get("parts") or []
+            meta = {"context_id": result["message"].get("contextId")}
+        else:
+            raise AdapterError(self._agent_id, "A2A reply has neither 'task' nor 'message'")
+
+        output, text = self._to_output(parts)
+        return AgentResponse(output=output, raw_text=text, latency_ms=latency, metadata=meta)
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(
+            timeout=self._timeout,
+            headers={**self._headers, "A2A-Version": PROTOCOL_VERSION},
+            transport=self._transport,
+        )
+
+    async def _resolve(self, client: httpx.AsyncClient) -> tuple[str, str | None]:
+        if self._endpoint is not None:
+            return self._endpoint
+        try:
+            resp = await client.get(self._card_url)
+            resp.raise_for_status()
+            card = resp.json()
+        except (httpx.HTTPError, ValueError) as e:
+            raise AdapterError(
+                self._agent_id, f"Cannot load agent card {self._card_url}: {e}"
+            ) from e
+        if not isinstance(card, dict):
+            raise AdapterError(self._agent_id, f"Agent card {self._card_url} is not an object")
+
+        interfaces = card.get("supportedInterfaces") or []
+        for iface in interfaces:
+            if iface.get("protocolBinding") == "JSONRPC" and str(
+                iface.get("protocolVersion", "")
+            ).startswith("1."):
+                self._card = card
+                self._endpoint = (urljoin(self._card_url, iface["url"]), iface.get("tenant"))
+                return self._endpoint
+
+        offered = [
+            f"{i.get('protocolBinding')} {i.get('protocolVersion')}" for i in interfaces
+        ] or [f"A2A {card.get('protocolVersion', 'unknown')}"]
+        raise AdapterError(
+            self._agent_id,
+            f"Agent card {self._card_url} offers {', '.join(offered)}; "
+            f"A2AAdapter needs a JSONRPC interface for A2A {PROTOCOL_VERSION}",
+        )
+
+    async def _post(
+        self, client: httpx.AsyncClient, url: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        try:
+            resp = await client.post(url, json=body)
+            resp.raise_for_status()
+            reply = resp.json()
+        except (httpx.HTTPError, ValueError) as e:
+            raise AdapterError(self._agent_id, f"A2A request to {url} failed: {e}") from e
+        if not isinstance(reply, dict):
+            raise AdapterError(self._agent_id, "A2A reply is not a JSON-RPC object")
+        return reply
+
+    def _message(self, input_data: dict[str, Any]) -> dict[str, Any]:
+        if self._text_field is None:
+            part: dict[str, Any] = {"data": input_data, "mediaType": "application/json"}
+        else:
+            value = input_data.get(self._text_field)
+            if not isinstance(value, str):
+                raise AdapterError(
+                    self._agent_id, f"text_field '{self._text_field}' is missing or not a string"
+                )
+            part = {"text": value}
+        return {"messageId": str(uuid.uuid4()), "role": "ROLE_USER", "parts": [part]}
+
+    def _task_parts(self, task: dict[str, Any]) -> list[dict[str, Any]]:
+        status = task.get("status") or {}
+        state = status.get("state")
+        status_parts = (status.get("message") or {}).get("parts") or []
+        if state != "TASK_STATE_COMPLETED":
+            detail = " ".join(p["text"] for p in status_parts if "text" in p)
+            raise AdapterError(self._agent_id, f"task ended in {state}: {detail}".rstrip(": "))
+        parts = [p for a in task.get("artifacts") or [] for p in a.get("parts") or []]
+        return parts or status_parts
+
+    def _to_output(self, parts: list[dict[str, Any]]) -> tuple[dict[str, Any], str | None]:
+        if not parts:
+            raise AdapterError(self._agent_id, "A2A reply contains no parts")
+        output: dict[str, Any] = {}
+        texts: list[str] = []
+        loose: list[Any] = []
+        files: list[dict[str, Any]] = []
+        for part in parts:
+            if "text" in part:
+                texts.append(part["text"])
+            elif "data" in part:
+                data = part["data"]
+                if not isinstance(data, dict):
+                    loose.append(data)
+                    continue
+                clash = output.keys() & data.keys()
+                if clash:
+                    raise AdapterError(
+                        self._agent_id, f"data parts disagree on key(s) {sorted(clash)}"
+                    )
+                output.update(data)
+            elif "raw" in part or "url" in part:
+                files.append(self._file(part))
+            else:
+                raise AdapterError(self._agent_id, f"unknown part with keys {sorted(part)}")
+
+        text = "\n".join(texts) if texts else None
+        if text is not None and not output and not loose and not files and self._json_text:
+            try:
+                parsed = json.loads(text)
+            except ValueError:
+                parsed = None
+            if isinstance(parsed, dict):
+                return parsed, text
+        if loose:
+            self._put(output, "data", loose[0] if len(loose) == 1 else loose)
+        if text is not None:
+            self._put(output, "text", text)
+        if files:
+            self._put(output, "files", files)
+        return output, text
+
+    def _file(self, part: dict[str, Any]) -> dict[str, Any]:
+        entry: dict[str, Any] = {}
+        for key in ("filename", "mediaType"):
+            if key in part:
+                entry[key] = part[key]
+        if "url" in part:
+            entry["url"] = part["url"]
+            return entry
+        try:
+            content = base64.b64decode(part["raw"], validate=True)
+        except (binascii.Error, TypeError, ValueError) as e:
+            raise AdapterError(self._agent_id, f"file part has invalid base64 'raw': {e}") from e
+        entry["size"] = len(content)
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+        return entry
+
+    def _put(self, output: dict[str, Any], key: str, value: Any) -> None:
+        if key in output:
+            raise AdapterError(self._agent_id, f"reply already has a '{key}' field")
+        output[key] = value

agent_handshake/adapters/base.py

@@ -0,0 +1,68 @@
+"""Base adapter interface for wrapping any agent."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class AgentMetadata:
+    """Identification and configuration of an agent."""
+
+    agent_id: str
+    version: str
+    model: str | None = None
+    prompt_hash: str | None = None
+    tools: list[str] = field(default_factory=list)
+
+
+@dataclass
+class AgentResponse:
+    """Structured response from an agent call."""
+
+    output: dict[str, Any]
+    raw_text: str | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+    token_usage: dict[str, int] | None = None
+    latency_ms: float | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class AgentAdapter(ABC):
+    """Abstract base class for agent adapters.
+
+    Implement this to wrap your agent (LangChain, CrewAI, plain function,
+    HTTP service, etc.) so agent-handshake can call it during recording and testing.
+    """
+
+    @abstractmethod
+    def get_metadata(self) -> AgentMetadata:
+        """Return agent identification and configuration.
+
+        This is called to identify the agent in snapshots and reports.
+        The prompt_hash field is particularly important — it allows
+        agent-handshake to detect when a prompt has changed and invalidate
+        stale snapshots.
+        """
+        ...
+
+    @abstractmethod
+    async def call(self, input_data: dict[str, Any]) -> AgentResponse:
+        """Execute the agent with the given input.
+
+        Args:
+            input_data: Arbitrary dict passed to the agent.
+
+        Returns:
+            AgentResponse with at minimum the output dict populated.
+
+        Raises:
+            AdapterError: If the agent call fails.
+        """
+        ...
+
+    async def health_check(self) -> bool:
+        """Optional health check. Returns True if agent is reachable."""
+        return True

agent_handshake/adapters/function_adapter.py

@@ -0,0 +1,83 @@
+"""Adapter for plain Python async functions."""
+
+from __future__ import annotations
+
+import inspect
+import time
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from agent_handshake.adapters.base import AgentAdapter, AgentMetadata, AgentResponse
+from agent_handshake.exceptions import AdapterError
+
+
+class FunctionAdapter(AgentAdapter):
+    """Wraps an async Python function as an agent adapter.
+
+    Usage:
+        async def my_agent(input_data: dict) -> dict:
+            # your agent logic
+            return {"category": "billing"}
+
+        adapter = FunctionAdapter(
+            fn=my_agent,
+            agent_id="triage-agent",
+            version="1.0.0",
+        )
+    """
+
+    def __init__(
+        self,
+        fn: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]],
+        agent_id: str,
+        version: str,
+        model: str | None = None,
+        prompt_hash: str | None = None,
+    ) -> None:
+        if not callable(fn):
+            raise AdapterError(agent_id, f"Expected callable, got {type(fn).__name__}")
+        if not inspect.iscoroutinefunction(fn):
+            raise AdapterError(agent_id, "Function must be async (use 'async def')")
+
+        self._fn = fn
+        self._agent_id = agent_id
+        self._version = version
+        self._model = model
+        self._prompt_hash = prompt_hash
+
+    def get_metadata(self) -> AgentMetadata:
+        """Return metadata for this function adapter."""
+        return AgentMetadata(
+            agent_id=self._agent_id,
+            version=self._version,
+            model=self._model,
+            prompt_hash=self._prompt_hash,
+        )
+
+    async def call(self, input_data: dict[str, Any]) -> AgentResponse:
+        """Call the wrapped async function.
+
+        Args:
+            input_data: Input dict to pass to the function.
+
+        Returns:
+            AgentResponse with the function's return value.
+
+        Raises:
+            AdapterError: If the function call fails or returns wrong type.
+        """
+        start = time.monotonic()
+        try:
+            result = await self._fn(input_data)
+        except Exception as e:
+            raise AdapterError(self._agent_id, f"Agent call failed: {e}") from e
+
+        latency = (time.monotonic() - start) * 1000
+
+        if not isinstance(result, dict):
+            raise AdapterError(
+                self._agent_id,
+                f"Agent must return dict, got {type(result).__name__}",
+            )
+
+        return AgentResponse(output=result, latency_ms=latency)