cendor-sdk 1.0.0__py3-none-any.whl

cendor/sdk/__init__.py

@@ -0,0 +1,143 @@
+"""cendor.sdk — a governed, provider-agnostic agent SDK.
+
+*The second door into Cendor:* the simple, all-in-one governed agent SDK. Cost budgets,
+tamper-evident audit, PII redaction, context governance, and record/replay testing are the
+**foundation**, not plugins — composed through ``cendor-core``'s bus / interceptor / ``Sink`` /
+``Compressor`` seams, correlated by ``trace()``, with zero SDK-specific glue. An ungoverned
+``run()`` works on ``cendor-core`` alone.
+
+```python
+from cendor.sdk import Agent, tool, run, budget, guard, Policy, AuditLog
+
+@tool
+def get_weather(city: str) -> str:
+    "Current weather for a city."
+    return f"Sunny in {city}"
+
+agent = Agent(name="assistant", model="gpt-4o", tools=[get_weather])
+log = AuditLog(system="support", path="audit.jsonl")
+with budget(usd=0.25, on_exceed="block"), guard(Policy.default(), audit=log):
+    result = run(agent, "What's the weather in Paris?", audit=log)
+print(result.output, result.cost)
+```
+"""
+
+from __future__ import annotations
+
+# --- audit + redaction (cendor-acttrace, re-exported) -------------------------------------------
+from cendor.acttrace import AuditLog, Policy, verify
+
+# --- correlation (cendor-core) ------------------------------------------------------------------
+from cendor.core import current_trace_id, trace
+
+# --- budgets + attribution (cendor-tokenguard, re-exported) -------------------------------------
+from cendor.tokenguard import BudgetExceeded, budget, configure, report, track
+
+from ._governance import guard
+
+# --- the SDK -----------------------------------------------------------------------------------
+from .a2a import A2AClient, A2AServer
+from .agent import Agent
+from .checkpoint import Checkpointer
+from .embeddings import aembed, embed
+from .eval import EvalCase, EvalReport, EvalResult, evaluate
+from .foundry import FoundryAdapter
+from .hitl import require_approval
+from .mcp import get_mcp_prompt, load_mcp_prompts, load_mcp_resources, load_mcp_tools
+from .memory import Session, SQLiteSessionStore, SummarizingSession, llm_summarizer
+from .orchestration import (
+    Handoff,
+    handoff,
+    parallel,
+    parallel_async,
+    sequential,
+    supervisor,
+)
+from .otel import span_tree
+from .pricing import register_model_price
+from .providers import ParsedResponse, ToolInvocation
+from .rag import Hit, VectorIndex
+from .resilience import RetryPolicy
+from .result import (
+    Result,
+    RunComplete,
+    Step,
+    StreamEvent,
+    TextDelta,
+    ToolCallEvent,
+    ToolResultEvent,
+)
+from .result import Run as Run
+from .runner import Runner, run
+from .tools import Tool, tool
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # agent + loop
+    "Agent",
+    "tool",
+    "Tool",
+    "run",
+    "Runner",
+    "Session",
+    # embeddings + RAG
+    "embed",
+    "aembed",
+    "VectorIndex",
+    "Hit",
+    # orchestration (Phase 2)
+    "handoff",
+    "Handoff",
+    "sequential",
+    "parallel",
+    "parallel_async",
+    "supervisor",
+    # interop (Phase 3)
+    "load_mcp_tools",
+    "load_mcp_prompts",
+    "get_mcp_prompt",
+    "load_mcp_resources",
+    "A2AServer",
+    "A2AClient",
+    "FoundryAdapter",
+    "span_tree",
+    "require_approval",
+    # hardening + eval (Phase 4)
+    "RetryPolicy",
+    "Checkpointer",
+    "SQLiteSessionStore",
+    "SummarizingSession",
+    "llm_summarizer",
+    "evaluate",
+    "EvalCase",
+    "EvalReport",
+    "EvalResult",
+    # result model
+    "Result",
+    "Run",
+    "Step",
+    "ParsedResponse",
+    "ToolInvocation",
+    # streaming events (run.stream / run.astream)
+    "StreamEvent",
+    "TextDelta",
+    "ToolCallEvent",
+    "ToolResultEvent",
+    "RunComplete",
+    # governance (the real tokenguard/acttrace objects, re-exported)
+    "budget",
+    "track",
+    "report",
+    "configure",
+    "register_model_price",
+    "BudgetExceeded",
+    "guard",
+    "Policy",
+    "AuditLog",
+    "verify",
+    # correlation
+    "trace",
+    "current_trace_id",
+    "__version__",
+]

cendor/sdk/_governance.py

@@ -0,0 +1,42 @@
+"""Thin governance wiring the SDK owns: ``guard`` as a context manager.
+
+``acttrace.guard()`` returns a bare pre-call interceptor (you install it on core's interceptor
+seam yourself). The SDK exposes ``guard`` as a **context manager** so it reads like ``budget()`` /
+``track()`` and composes in one ``with`` line — the whole reason it's in the re-export surface
+(plan §4). It installs the acttrace interceptor for the duration and removes it on exit; the actual
+redact/block/flag logic and the audit recording are 100% acttrace's, riding core's seam.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+from cendor.core.instrument import add_interceptor, remove_interceptor
+
+
+@contextmanager
+def guard(policy: Any = None, *, audit: Any = None, on_block: Any = None) -> Any:
+    """Install an ``acttrace`` policy guard on core's interceptor seam for the block's duration.
+
+    Redacts PII **before** the provider sees it, blocks disallowed content, and flags the rest —
+    per the ``Policy``. When ``audit`` is given, each action is recorded on the hash-chained log.
+
+    ```python
+    from cendor.sdk import guard, Policy, AuditLog
+    log = AuditLog(system="support", path="audit.jsonl")
+    with guard(Policy.gdpr(), audit=log):
+        run(agent, "email me at alice@example.com", audit=log)
+    ```
+    """
+    from cendor.acttrace import guard as _acttrace_guard
+
+    if on_block is not None:
+        interceptor = _acttrace_guard(policy, audit=audit, on_block=on_block)
+    else:
+        interceptor = _acttrace_guard(policy, audit=audit)
+    add_interceptor(interceptor)
+    try:
+        yield interceptor
+    finally:
+        remove_interceptor(interceptor)

cendor/sdk/a2a.py

@@ -0,0 +1,151 @@
+"""A2A: expose a governed ``cendor.sdk`` agent over the Agent-to-Agent protocol (plan §7 Phase 3).
+
+A minimal, dependency-free implementation of A2A's JSON-RPC ``message/send`` plus the agent card.
+``A2AServer.handle(request)`` runs the agent and returns an A2A message result (with governance
+metadata: trace id, cost); ``A2AClient`` calls a server **in-process** (no socket) for tests and
+embedding. ``serve()`` is an optional local HTTP server (stdlib only — local-first, never required).
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from .agent import Agent
+from .runner import run
+
+
+def _text_of_message(message: dict) -> str:
+    parts = message.get("parts") or []
+    texts = [str(p.get("text", "")) for p in parts if p.get("kind", "text") == "text"]
+    return "\n".join(t for t in texts if t)
+
+
+def _message_result(text: str, metadata: dict) -> dict:
+    return {
+        "messageId": uuid.uuid4().hex,
+        "role": "agent",
+        "parts": [{"kind": "text", "text": text}],
+        "kind": "message",
+        "metadata": metadata,
+    }
+
+
+class A2AServer:
+    """Serve one agent over A2A. In-process via :meth:`handle`; over HTTP via :func:`serve`."""
+
+    def __init__(self, agent: Agent, *, audit: Any = None) -> None:
+        self.agent = agent
+        self.audit = audit
+
+    def agent_card(self) -> dict:
+        """The A2A agent card advertising this agent's identity and skills."""
+        return {
+            "name": self.agent.name,
+            "description": self.agent.instructions or f"The {self.agent.name} agent.",
+            "version": "1.0.0",
+            "protocolVersion": "0.2",
+            "capabilities": {"streaming": False},
+            "defaultInputModes": ["text/plain"],
+            "defaultOutputModes": ["text/plain"],
+            "skills": [
+                {
+                    "id": t.name,
+                    "name": t.name,
+                    "description": t.description,
+                }
+                for t in self.agent.toolset
+            ],
+        }
+
+    def handle(self, request: dict) -> dict:
+        """Dispatch a JSON-RPC A2A request. Supports ``message/send``."""
+        rpc_id = request.get("id")
+        method = request.get("method")
+        if method != "message/send":
+            return {
+                "jsonrpc": "2.0",
+                "id": rpc_id,
+                "error": {"code": -32601, "message": f"method not found: {method}"},
+            }
+        message = (request.get("params") or {}).get("message") or {}
+        text = _text_of_message(message)
+        result = run(self.agent, text, audit=self.audit)
+        metadata = {
+            "trace_id": result.trace_id,
+            "cost_usd": str(result.cost.amount),
+            "agents": result.agents,
+        }
+        return {
+            "jsonrpc": "2.0",
+            "id": rpc_id,
+            "result": _message_result(str(result.output), metadata),
+        }
+
+
+class A2AClient:
+    """Call an :class:`A2AServer` in-process (no network) — the offline/embedded path."""
+
+    def __init__(self, server: A2AServer) -> None:
+        self.server = server
+
+    def card(self) -> dict:
+        return self.server.agent_card()
+
+    def send(self, text: str) -> str:
+        """Send a user message and return the agent's text reply."""
+        response = self.server.handle(self._request(text))
+        if "error" in response:
+            raise RuntimeError(f"A2A error: {response['error']}")
+        parts = response["result"]["parts"]
+        return "\n".join(p.get("text", "") for p in parts if p.get("kind") == "text")
+
+    def send_full(self, text: str) -> dict:
+        """Send a message and return the full A2A message result (incl. governance metadata)."""
+        return self.server.handle(self._request(text))["result"]
+
+    @staticmethod
+    def _request(text: str) -> dict:
+        return {
+            "jsonrpc": "2.0",
+            "id": uuid.uuid4().hex,
+            "method": "message/send",
+            "params": {"message": {"role": "user", "parts": [{"kind": "text", "text": text}]}},
+        }
+
+
+def serve(agent: Agent, *, host: str = "127.0.0.1", port: int = 0, audit: Any = None) -> Any:
+    """Start a local A2A HTTP server (stdlib ``http.server``). Optional, opt-in; returns the server.
+
+    The agent card is served at ``GET /.well-known/agent-card.json``; JSON-RPC at ``POST /``.
+    Call ``.serve_forever()`` (blocking) or run it in a thread; ``.shutdown()`` to stop.
+    """
+    from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+
+    a2a = A2AServer(agent, audit=audit)
+
+    class Handler(BaseHTTPRequestHandler):
+        def _send(self, code: int, payload: dict) -> None:
+            body = json.dumps(payload).encode()
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:  # noqa: N802 - stdlib handler name
+            if self.path.rstrip("/").endswith("agent-card.json") or self.path == "/":
+                self._send(200, a2a.agent_card())
+            else:
+                self._send(404, {"error": "not found"})
+
+        def do_POST(self) -> None:  # noqa: N802 - stdlib handler name
+            length = int(self.headers.get("Content-Length", 0))
+            request = json.loads(self.rfile.read(length) or b"{}")
+            self._send(200, a2a.handle(request))
+
+        def log_message(self, *args: Any) -> None:  # silence the default stderr logging
+            return
+
+    return ThreadingHTTPServer((host, port), Handler)

cendor/sdk/agent.py

@@ -0,0 +1,94 @@
+"""``Agent`` — a small, opinionated, provider-agnostic agent definition.
+
+An ``Agent`` is declarative data: a name, a model id, instructions, tools, and a few knobs. The
+loop lives in ``runner.py``; governance lives in the surrounding ``budget()``/``guard()`` contexts.
+The provider is inferred from the model id (override with ``provider=``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .providers import Provider, resolve_provider
+from .tools import Tool, as_tool
+
+
+@dataclass
+class Agent:
+    """A provider-agnostic agent.
+
+    Args:
+        name: A short identifier used in results, audit decisions, and handoffs.
+        model: Any core-supported model id (``"gpt-4o"``, ``"claude-opus-4-8"``, ``"gemini-…"``).
+        instructions: The system prompt.
+        tools: ``@tool``-decorated callables, plain functions, or ``Tool`` objects.
+        provider: Override the provider inferred from ``model``.
+        output_type: Structured output — a dataclass, a Pydantic model, or a JSON-schema dict.
+        max_turns: Upper bound on ReAct iterations (loop-termination guarantee).
+        context_budget: If set, assemble the history to this token budget via ``contextkit``.
+        temperature / max_tokens: Optional generation controls.
+        extra: Extra provider request kwargs merged into every model call — the passthrough for
+            things the SDK doesn't model first-class (``tool_choice``, ``reasoning_effort``,
+            ``top_p``, ``stop``, ``seed``, ``response_format``, ``extra_body``, …). Merged at the
+            top level of the request, matching the OpenAI/Anthropic/Ollama/HF/Azure shape.
+        retriever: Optional ``query -> list[str]`` callable (e.g. ``VectorIndex.as_retriever()``).
+            When set, context is retrieved for the run's query and injected as a system message
+            before the call — "always-on" RAG. (For agentic retrieval, expose it as a tool instead.)
+        handoffs: Names of peer agents this agent may transfer to (Phase 2).
+        api_key / base_url / client: Optional client config, or an explicit instrumented client.
+    """
+
+    name: str
+    model: str
+    instructions: str = ""
+    tools: list[Any] = field(default_factory=list)
+    provider: str | None = None
+    output_type: Any = None
+    max_turns: int = 8
+    context_budget: int | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+    retriever: Any = None  # Callable[[str], list[str]] — injected as context when set (RAG)
+    handoffs: list[Any] = field(default_factory=list)
+    max_usd: float | None = None  # per-agent spend cap (enforced by the orchestrator, Phase 2)
+    api_key: str | None = None
+    base_url: str | None = None
+    client: Any = None
+
+    _tools: list[Tool] = field(default_factory=list, init=False, repr=False)
+    _tool_map: dict[str, Tool] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self._tools = [as_tool(t) for t in self.tools]
+        self._tool_map = {t.name: t for t in self._tools}
+
+    @property
+    def provider_impl(self) -> Provider:
+        """The resolved provider implementation for this agent's model."""
+        return resolve_provider(self.model, self.provider)
+
+    @property
+    def toolset(self) -> list[Tool]:
+        """The agent's tools as ``Tool`` objects."""
+        return self._tools
+
+    def get_tool(self, name: str) -> Tool | None:
+        """Look up a tool by name."""
+        return self._tool_map.get(name)
+
+    def config(self) -> dict[str, Any]:
+        """Client construction config (api_key / base_url)."""
+        cfg: dict[str, Any] = {}
+        if self.api_key:
+            cfg["api_key"] = self.api_key
+        if self.base_url:
+            cfg["base_url"] = self.base_url
+        return cfg
+
+    def add_tool(self, tool: Any) -> None:
+        """Register an extra tool at runtime (used by MCP/handoff wiring in later phases)."""
+        t = as_tool(tool)
+        self._tools.append(t)
+        self._tool_map[t.name] = t

cendor/sdk/checkpoint.py

@@ -0,0 +1,55 @@
+"""Checkpointed / resumable runs — local-first (plan §7 Phase 4).
+
+A ``Checkpointer`` persists a run's conversation to a local JSON file after each turn, so a long
+agent can resume after a crash or restart without re-doing completed work (already-run tools are in
+the saved messages and are not re-executed). Local by default; no server.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+class Checkpointer:
+    """Persist and restore run state to a local JSON file."""
+
+    def __init__(self, path: str) -> None:
+        self.path = Path(path)
+
+    def load(self) -> dict[str, Any] | None:
+        """The saved state (``{run_id, messages, done, output}``), or ``None`` if absent/bad."""
+        if not self.path.exists():
+            return None
+        try:
+            return json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return None
+
+    def save(self, state: dict[str, Any]) -> None:
+        """Atomically write the run state (temp file + replace)."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp.write_text(json.dumps(state, indent=2, default=str), encoding="utf-8")
+        tmp.replace(self.path)
+
+    def resumable_messages(self) -> list[dict] | None:
+        """Saved messages to resume from, or ``None`` if there's no unfinished checkpoint."""
+        state = self.load()
+        if state and not state.get("done"):
+            return list(state.get("messages") or [])
+        return None
+
+    def clear(self) -> None:
+        """Delete the checkpoint file (e.g. after a successful, finished run)."""
+        try:
+            self.path.unlink()
+        except OSError:
+            pass
+
+
+def _as_checkpointer(value: Any) -> Checkpointer | None:
+    if value is None or isinstance(value, Checkpointer):
+        return value
+    return Checkpointer(str(value))

cendor/sdk/embeddings.py

@@ -0,0 +1,132 @@
+"""Embeddings — governed, captured embedding calls (the RAG plumbing from the plan's §0).
+
+``embed(model, inputs)`` calls the provider's embeddings endpoint, returns the vectors, and emits a
+governed ``LLMCall`` on ``cendor-core``'s bus — so the call's tokens + cost land in the *same* audit
+/ attribution / cost tree as chat calls (RAG embeddings were invisible beneath frameworks; owning
+the call makes them first-class). Correlate them by wrapping in ``trace(...)`` like any run.
+
+Note: this *captures* (records) the embedding call. Pre-call USD *blocking* of embeddings would need
+core-level embeddings interception; use a ``tokens=`` budget or register a price to bound spend.
+
+OpenAI-family providers (``openai`` / ``azure`` / ``foundry_local``) share ``embeddings.create``;
+for others, call the provider's embedding client directly.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from cendor.core import bus, current_trace_id, prices
+from cendor.core.types import LLMCall, Usage
+
+from .providers import OpenAIChatProvider, get_provider, resolve_provider
+
+
+def _texts(inputs: str | list[str]) -> list[str]:
+    return [inputs] if isinstance(inputs, str) else list(inputs)
+
+
+def _config(api_key: str | None, base_url: str | None) -> dict[str, Any]:
+    cfg: dict[str, Any] = {}
+    if api_key:
+        cfg["api_key"] = api_key
+    if base_url:
+        cfg["base_url"] = base_url
+    return cfg
+
+
+def _resolve(model: str, provider: str | None) -> OpenAIChatProvider:
+    try:
+        prov = resolve_provider(model, provider)
+    except ValueError:
+        prov = get_provider("openai")  # embedding ids rarely prefix-infer; default to OpenAI shape
+    if not isinstance(prov, OpenAIChatProvider):
+        raise NotImplementedError(
+            f"embed() supports OpenAI-family providers (openai/azure/foundry_local); got "
+            f"{prov.name!r}. Call that provider's embeddings client directly."
+        )
+    return prov
+
+
+def _vectors(resp: Any) -> list[list[float]]:
+    data = getattr(resp, "data", None)
+    if data is None and isinstance(resp, dict):
+        data = resp.get("data", [])
+    out: list[list[float]] = []
+    for d in data or []:
+        emb = getattr(d, "embedding", None)
+        if emb is None and isinstance(d, dict):
+            emb = d.get("embedding")
+        out.append(list(emb) if emb is not None else [])
+    return out
+
+
+def _emit(model: str, provider: str, resp: Any, start: float) -> None:
+    u = getattr(resp, "usage", None)
+    inp = 0
+    if u is not None:
+        inp = getattr(u, "prompt_tokens", None) or getattr(u, "total_tokens", 0) or 0
+    elif isinstance(resp, dict):
+        inp = (resp.get("usage") or {}).get("prompt_tokens", 0) or 0
+    call = LLMCall(
+        id=uuid.uuid4().hex,
+        provider=provider,
+        model=model,
+        messages=[],
+        trace_id=current_trace_id(),
+        ts=datetime.now(UTC),
+    )
+    call.latency_ms = (time.perf_counter() - start) * 1000.0
+    call.usage = Usage(input_tokens=int(inp), output_tokens=0)
+    try:
+        call.cost = prices.estimate(model, int(inp), 0)
+        call.metadata["cost_estimated"] = True
+    except KeyError:
+        call.cost = None
+    call.metadata["embedding"] = True
+    bus.emit(call)
+
+
+def embed(
+    model: str,
+    inputs: str | list[str],
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    dimensions: int | None = None,
+) -> list[list[float]]:
+    """Embed text(s); return one vector per input and emit a governed ``LLMCall`` on the bus."""
+    prov = _resolve(model, provider)
+    client = prov.client(async_=False, config=_config(api_key, base_url))
+    kwargs: dict[str, Any] = {"model": model, "input": _texts(inputs)}
+    if dimensions is not None:
+        kwargs["dimensions"] = dimensions
+    start = time.perf_counter()
+    resp = client.embeddings.create(**kwargs)
+    _emit(model, prov.name, resp, start)
+    return _vectors(resp)
+
+
+async def aembed(
+    model: str,
+    inputs: str | list[str],
+    *,
+    provider: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    dimensions: int | None = None,
+) -> list[list[float]]:
+    """Async counterpart of :func:`embed`."""
+    prov = _resolve(model, provider)
+    client = prov.client(async_=True, config=_config(api_key, base_url))
+    kwargs: dict[str, Any] = {"model": model, "input": _texts(inputs)}
+    if dimensions is not None:
+        kwargs["dimensions"] = dimensions
+    start = time.perf_counter()
+    resp = await client.embeddings.create(**kwargs)
+    _emit(model, prov.name, resp, start)
+    return _vectors(resp)