prova-sdk 0.1.0__py3-none-any.whl

prova_cp/__init__.py

@@ -0,0 +1,27 @@
+"""Agent-side SDK for the Prova AI control plane."""
+
+from .client import ProvaClient, ProvaApiError, ReceiptVerificationError
+from .verify import verify_receipt
+from .canonical import canonicalize
+from .migrate import migrate, MAPPERS, langsmith_mapper, langfuse_mapper, openai_mapper
+from .callbacks import ProvaCallbackHandler
+from .crewai import ProvaCrewAI
+from .wrap import wrap_openai, wrap_anthropic
+
+__all__ = [
+    "ProvaClient",
+    "ProvaApiError",
+    "ReceiptVerificationError",
+    "verify_receipt",
+    "canonicalize",
+    "migrate",
+    "MAPPERS",
+    "langsmith_mapper",
+    "langfuse_mapper",
+    "openai_mapper",
+    "ProvaCallbackHandler",
+    "ProvaCrewAI",
+    "wrap_openai",
+    "wrap_anthropic",
+]
+__version__ = "0.1.0"

prova_cp/callbacks.py

@@ -0,0 +1,302 @@
+"""LangChain / LangGraph callback handler for automatic Prova instrumentation.
+
+Drop ProvaCallbackHandler into any LangGraph graph or LangChain chain and every
+LLM call, chain invocation, and tool call is automatically ingested as a signed
+Prova receipt.
+
+Usage:
+
+    from prova_cp import ProvaClient
+    from prova_cp.callbacks import ProvaCallbackHandler
+
+    prova = ProvaClient(api_key=os.environ["PROVA_API_KEY"])
+    handler = ProvaCallbackHandler(
+        client=prova,
+        app_id="my-agent",
+        environment="production",
+        framework="langgraph",
+    )
+
+    # LangGraph:
+    graph.invoke(inputs, config={"callbacks": [handler]})
+
+    # LangChain:
+    chain.invoke(inputs, config={"callbacks": [handler]})
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, List, Optional, Sequence, Union
+from uuid import UUID
+
+log = logging.getLogger(__name__)
+
+try:
+    from langchain_core.callbacks import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+    _LANGCHAIN_AVAILABLE = True
+except ImportError:
+    _LANGCHAIN_AVAILABLE = False
+
+    class BaseCallbackHandler:  # type: ignore[no-redef]
+        """Stub so the module is importable even without langchain_core."""
+        pass
+
+    class LLMResult:  # type: ignore[no-redef]
+        """Stub."""
+        generations: list = []
+        llm_output: dict = {}
+
+
+class ProvaCallbackHandler(BaseCallbackHandler):
+    """LangChain/LangGraph callback handler that ingests every AI event into Prova.
+
+    Thread-safe: each run_id gets its own timing state stored in a dict.
+    Failures are swallowed and logged so a Prova outage never breaks the agent.
+    """
+
+    def __init__(
+        self,
+        client: Any,
+        *,
+        app_id: str = "agent",
+        environment: str = "production",
+        framework: str = "langgraph",
+        provider: Optional[str] = None,
+    ) -> None:
+        if not _LANGCHAIN_AVAILABLE:
+            raise ImportError(
+                "langchain-core is required to use ProvaCallbackHandler. "
+                "Install it with: pip install langchain-core"
+            )
+        super().__init__()
+        self._client = client
+        self._source = {
+            "app_id": app_id,
+            "environment": environment,
+            "framework": framework,
+        }
+        self._provider = provider
+        self._start_times: Dict[str, float] = {}
+        self._prompts: Dict[str, Any] = {}
+
+    # ------------------------------------------------------------------
+    # LLM callbacks
+    # ------------------------------------------------------------------
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        self._start_times[key] = time.time()
+        self._prompts[key] = prompts
+
+    def on_chat_model_start(
+        self,
+        serialized: Dict[str, Any],
+        messages: List[List[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        self._start_times[key] = time.time()
+        try:
+            self._prompts[key] = [
+                {"role": m.type, "content": m.content}
+                for batch in messages
+                for m in batch
+            ]
+        except Exception:
+            self._prompts[key] = str(messages)
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        elapsed_ms = int((time.time() - self._start_times.pop(key, time.time())) * 1000)
+        prompt = self._prompts.pop(key, None)
+
+        try:
+            generation = (
+                response.generations[0][0] if response.generations and response.generations[0] else None
+            )
+            completion = getattr(generation, "text", None) or (
+                getattr(generation, "message", None) and getattr(generation.message, "content", None)
+            )
+
+            llm_output = response.llm_output or {}
+            model_name = (
+                llm_output.get("model_name")
+                or llm_output.get("model")
+                or kwargs.get("invocation_params", {}).get("model_name")
+                or kwargs.get("invocation_params", {}).get("model")
+            )
+
+            payload: Dict[str, Any] = {"elapsed_ms": elapsed_ms}
+            if prompt is not None:
+                payload["prompt"] = prompt
+            if completion is not None:
+                payload["completion"] = completion
+            if llm_output:
+                payload["llm_output"] = llm_output
+
+            event: Dict[str, Any] = {
+                "kind": "model_call",
+                "source": {**self._source, "run_id": key},
+                "payload": payload,
+            }
+            if model_name or self._provider:
+                event["model"] = {
+                    k: v for k, v in {
+                        "provider": self._provider,
+                        "name": model_name,
+                    }.items() if v
+                }
+
+            self._client.ingest(event)
+        except Exception as exc:
+            log.warning("ProvaCallbackHandler.on_llm_end failed: %s", exc)
+
+    def on_llm_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        self._start_times.pop(key, None)
+        self._prompts.pop(key, None)
+
+    # ------------------------------------------------------------------
+    # Chain (agent node) callbacks
+    # ------------------------------------------------------------------
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._start_times[str(run_id)] = time.time()
+
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        elapsed_ms = int((time.time() - self._start_times.pop(key, time.time())) * 1000)
+
+        if parent_run_id is None:
+            return
+
+        name = kwargs.get("name") or (
+            serialized.get("name") if (serialized := kwargs.get("serialized")) else None
+        )
+
+        try:
+            self._client.ingest({
+                "kind": "agent_step",
+                "source": {**self._source, "run_id": key, "parent_run_id": str(parent_run_id)},
+                "payload": {
+                    "node": name or "unknown",
+                    "outputs": _safe_truncate(outputs),
+                    "elapsed_ms": elapsed_ms,
+                },
+            })
+        except Exception as exc:
+            log.warning("ProvaCallbackHandler.on_chain_end failed: %s", exc)
+
+    def on_chain_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._start_times.pop(str(run_id), None)
+
+    # ------------------------------------------------------------------
+    # Tool callbacks
+    # ------------------------------------------------------------------
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._start_times[str(run_id)] = time.time()
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        key = str(run_id)
+        elapsed_ms = int((time.time() - self._start_times.pop(key, time.time())) * 1000)
+
+        name = kwargs.get("name")
+        try:
+            self._client.ingest({
+                "kind": "tool_call",
+                "source": {**self._source, "run_id": key},
+                "payload": {
+                    "tool": name or "unknown",
+                    "output": _safe_truncate(output),
+                    "elapsed_ms": elapsed_ms,
+                },
+            })
+        except Exception as exc:
+            log.warning("ProvaCallbackHandler.on_tool_end failed: %s", exc)
+
+    def on_tool_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        self._start_times.pop(str(run_id), None)
+
+
+def _safe_truncate(obj: Any, max_len: int = 2000) -> Any:
+    """Truncate large string values to keep receipt payloads reasonable."""
+    if isinstance(obj, str):
+        return obj[:max_len] + ("..." if len(obj) > max_len else "")
+    if isinstance(obj, dict):
+        return {k: _safe_truncate(v, max_len) for k, v in obj.items()}
+    if isinstance(obj, list):
+        return [_safe_truncate(v, max_len) for v in obj[:50]]
+    return obj

prova_cp/canonical.py

@@ -0,0 +1,15 @@
+"""Stable JSON canonicalization. Matches lib/receipts/sign.ts:canonicalize."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def canonicalize(value: Any) -> str:
+    if value is None or not isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    if isinstance(value, list):
+        return "[" + ",".join(canonicalize(v) for v in value) + "]"
+    keys = sorted(value.keys())
+    return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + canonicalize(value[k]) for k in keys) + "}"

prova_cp/cli.py

@@ -0,0 +1,53 @@
+"""prova-migrate CLI. Reads NDJSON and bulk-ingests into the Audit Vault."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from typing import Optional
+
+from .client import ProvaClient
+from .migrate import migrate, read_ndjson, MAPPERS
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="prova-migrate",
+        description="Bulk-import LangSmith / Langfuse / OpenAI logs into the Prova Audit Vault.",
+    )
+    parser.add_argument("--source", required=True, choices=sorted(MAPPERS.keys()))
+    parser.add_argument("--file", required=True, help='Path to NDJSON file, or "-" for stdin.')
+    parser.add_argument("--batch", type=int, default=200)
+    parser.add_argument("--base-url", default=None)
+    args = parser.parse_args(argv)
+
+    api_key = os.environ.get("PROVA_API_KEY")
+    if not api_key:
+        print("PROVA_API_KEY is required", file=sys.stderr)
+        return 2
+
+    stream = sys.stdin if args.file == "-" else open(args.file, "r", encoding="utf-8")
+    started = time.monotonic()
+    with ProvaClient(api_key, base_url=args.base_url) as client:
+        result = migrate(
+            client,
+            args.source,
+            read_ndjson(stream),
+            batch_size=args.batch,
+            on_progress=lambda p: print(
+                f"batch {p['batch']}: ingested={p['ingested']} skipped={p['skipped']} total={p['total']}",
+                file=sys.stderr,
+            ),
+        )
+    if stream is not sys.stdin:
+        stream.close()
+    result["elapsed_s"] = round(time.monotonic() - started, 1)
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

prova_cp/client.py

@@ -0,0 +1,116 @@
+"""ProvaClient: synchronous httpx wrapper around ingest, gateway-check, register."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any, Iterable, Mapping, Optional, Union
+
+import httpx
+
+from .verify import verify_receipt, ReceiptVerificationError  # noqa: F401 (re-exported)
+
+DEFAULT_BASE_URL = "https://api.prova.cobound.dev"
+DEFAULT_TIMEOUT = 30.0
+RETRYABLE_STATUS = {408, 425, 429, 500, 502, 503, 504}
+
+
+class ProvaApiError(Exception):
+    def __init__(self, status: int, code: str, detail: Any) -> None:
+        super().__init__(f"Prova API {status} {code}: {detail}")
+        self.status = status
+        self.code = code
+        self.detail = detail
+
+
+class ProvaClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retry_attempts: int = 4,
+        retry_backoff: float = 0.25,
+        retry_max_backoff: float = 4.0,
+        verify_receipts: bool = False,
+        user_agent: str = "prova-sdk python",
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("ProvaClient: api_key is required")
+        self._api_key = api_key
+        self._base_url = (base_url or os.environ.get("PROVA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self._timeout = timeout
+        self._attempts = retry_attempts
+        self._backoff = retry_backoff
+        self._max_backoff = retry_max_backoff
+        self._verify_receipts = verify_receipts
+        self._http = httpx.Client(
+            base_url=self._base_url,
+            timeout=timeout,
+            headers={"User-Agent": user_agent, "Content-Type": "application/json"},
+            transport=transport,
+        )
+
+    def __enter__(self) -> "ProvaClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _request(self, path: str, body: Any, *, idempotency_key: Optional[str] = None) -> Any:
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        last_err: Optional[BaseException] = None
+        for attempt in range(1, self._attempts + 1):
+            try:
+                resp = self._http.post(path, json=body, headers=headers)
+            except httpx.RequestError as e:
+                last_err = e
+                resp = None
+            if resp is not None:
+                if resp.status_code < 400:
+                    return resp.json()
+                status = resp.status_code
+                try:
+                    parsed = resp.json()
+                except Exception:
+                    parsed = resp.text
+                code = parsed.get("error") if isinstance(parsed, dict) else "http_error"
+                if status not in RETRYABLE_STATUS or attempt == self._attempts:
+                    raise ProvaApiError(status, str(code), parsed)
+                last_err = ProvaApiError(status, str(code), parsed)
+            sleep = min(self._max_backoff, self._backoff * (2 ** (attempt - 1)))
+            time.sleep(sleep + random.random() * 0.05)
+        assert last_err is not None
+        raise last_err
+
+    def ingest(self, events: Union[Mapping[str, Any], Iterable[Mapping[str, Any]]]) -> Mapping[str, Any]:
+        body = events if isinstance(events, list) else (list(events) if not isinstance(events, Mapping) else events)
+        res = self._request("/api/v1/audit/ingest", body)
+        if self._verify_receipts:
+            for r in res.get("receipts", []):
+                verify_receipt(r, base_url=self._base_url, client=self._http)
+        return res
+
+    def gateway_check(self, event: Mapping[str, Any]) -> Mapping[str, Any]:
+        res = self._request("/api/v1/gateway/check", event)
+        if self._verify_receipts and res.get("receipt"):
+            verify_receipt(res["receipt"], base_url=self._base_url, client=self._http)
+        return res
+
+    def register(
+        self,
+        integrations: Union[Mapping[str, Any], Iterable[Mapping[str, Any]]],
+    ) -> Mapping[str, Any]:
+        body = integrations if isinstance(integrations, (list, Mapping)) else list(integrations)
+        return self._request("/api/v1/inventory", body)
+
+    def verify(self, receipt: Mapping[str, Any]) -> None:
+        verify_receipt(receipt, base_url=self._base_url, client=self._http)

prova_cp/crewai.py

@@ -0,0 +1,99 @@
+"""CrewAI auto-instrumentation for Prova.
+
+CrewAI does not expose LangChain-style callbacks. Its stable, version-tolerant
+hooks are the `step_callback` and `task_callback` parameters on a Crew (and
+`step_callback` on an Agent). This module wires those to Prova ingest.
+
+Usage:
+
+    from prova_cp import ProvaClient
+    from prova_cp.crewai import ProvaCrewAI
+
+    prova = ProvaClient(api_key="prv_...")
+    tap = ProvaCrewAI(prova, app_id="research-crew", environment="production")
+
+    crew = Crew(
+        agents=[...],
+        tasks=[...],
+        step_callback=tap.step_callback,
+        task_callback=tap.task_callback,
+    )
+
+Both callbacks are fail-silent: a Prova outage logs at warning level and never
+breaks the crew. Agent steps become `agent_step` receipts; completed tasks
+become `agent_run` receipts.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+_MAX_LEN = 2000
+
+
+def _safe(obj: Any, depth: int = 0) -> Any:
+    if isinstance(obj, str):
+        return obj[:_MAX_LEN] + ("..." if len(obj) > _MAX_LEN else "")
+    if depth > 4:
+        return "[truncated]"
+    if isinstance(obj, dict):
+        return {k: _safe(v, depth + 1) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_safe(v, depth + 1) for v in list(obj)[:50]]
+    # CrewAI output objects: pull common attributes without importing crewai.
+    for attr in ("raw", "output", "result", "summary", "description"):
+        if hasattr(obj, attr):
+            return _safe(getattr(obj, attr), depth + 1)
+    return str(obj)[:_MAX_LEN]
+
+
+class ProvaCrewAI:
+    def __init__(
+        self,
+        client: Any,
+        *,
+        app_id: str = "crew",
+        environment: str = "production",
+        framework: str = "crewai",
+    ) -> None:
+        self._client = client
+        self._source = {
+            "app_id": app_id,
+            "environment": environment,
+            "framework": framework,
+        }
+
+    def step_callback(self, step_output: Any) -> None:
+        """Pass as Crew(step_callback=...) or Agent(step_callback=...)."""
+        try:
+            agent = getattr(step_output, "agent", None)
+            tool = getattr(step_output, "tool", None)
+            self._client.ingest({
+                "kind": "agent_step",
+                "source": dict(self._source),
+                "payload": {
+                    "agent": str(agent) if agent else None,
+                    "tool": str(tool) if tool else None,
+                    "output": _safe(step_output),
+                },
+            })
+        except Exception as exc:
+            log.warning("ProvaCrewAI.step_callback failed: %s", exc)
+
+    def task_callback(self, task_output: Any) -> None:
+        """Pass as Crew(task_callback=...)."""
+        try:
+            self._client.ingest({
+                "kind": "agent_run",
+                "source": dict(self._source),
+                "payload": {
+                    "task": getattr(task_output, "description", None)
+                    or getattr(task_output, "name", None),
+                    "output": _safe(task_output),
+                },
+            })
+        except Exception as exc:
+            log.warning("ProvaCrewAI.task_callback failed: %s", exc)

prova_cp/migrate.py

@@ -0,0 +1,185 @@
+"""One-shot migration of LangSmith / Langfuse / OpenAI logs into the Audit Vault."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterable, Iterator, Mapping, Optional, TextIO
+
+from .client import ProvaClient
+
+Mapper = Callable[[Mapping[str, Any]], Optional[Dict[str, Any]]]
+
+
+def _provider_of(model: Optional[str]) -> str:
+    m = (model or "").lower()
+    if m.startswith(("gpt-", "o1", "o3")) or "openai" in m:
+        return "openai"
+    if m.startswith("claude"):
+        return "anthropic"
+    if m.startswith(("gemini", "text-bison")):
+        return "google"
+    if m.startswith(("mistral", "codestral")):
+        return "mistral"
+    if m.startswith(("llama", "meta-")):
+        return "meta"
+    return "other"
+
+
+def _model_block(model: Optional[str]) -> Optional[Dict[str, Any]]:
+    if not model:
+        return None
+    return {"provider": _provider_of(model), "name": model}
+
+
+def langsmith_mapper(raw: Mapping[str, Any]) -> Optional[Dict[str, Any]]:
+    rid = raw.get("id")
+    if not isinstance(rid, str):
+        return None
+    run_type = raw.get("run_type") or "llm"
+    extra = raw.get("extra") if isinstance(raw.get("extra"), Mapping) else {}
+    invocation = extra.get("invocation_params") if isinstance(extra.get("invocation_params"), Mapping) else {}
+    model = invocation.get("model") or raw.get("model")
+    session = raw.get("session_name") or raw.get("session_id")
+    kind = (
+        "tool_call" if run_type == "tool"
+        else "agent_run" if run_type in ("chain", "agent")
+        else "model_call"
+    )
+    return {
+        "idempotency_key": f"langsmith:{rid}",
+        "occurred_at": raw.get("start_time"),
+        "kind": kind,
+        "source": {"org_id": "", "framework": "langgraph", "app_id": session or raw.get("name")},
+        "model": _model_block(model if isinstance(model, str) else None),
+        "payload": {
+            "_migrated_from": "langsmith",
+            "name": raw.get("name"),
+            "run_type": run_type,
+            "inputs": raw.get("inputs"),
+            "outputs": raw.get("outputs"),
+            "end_time": raw.get("end_time"),
+            "latency_ms": raw.get("latency") if isinstance(raw.get("latency"), (int, float)) else None,
+        },
+    }
+
+
+def langfuse_mapper(raw: Mapping[str, Any]) -> Optional[Dict[str, Any]]:
+    rid = raw.get("id")
+    if not isinstance(rid, str):
+        return None
+    obs_type = str(raw.get("type") or "GENERATION").upper()
+    model = raw.get("model") if isinstance(raw.get("model"), str) else None
+    start = raw.get("startTime") or raw.get("start_time")
+    trace_id = raw.get("traceId") or raw.get("trace_id")
+    kind = "agent_step" if obs_type in ("SPAN", "EVENT") else "model_call"
+    return {
+        "idempotency_key": f"langfuse:{rid}",
+        "occurred_at": start if isinstance(start, str) else None,
+        "kind": kind,
+        "source": {"org_id": "", "framework": "custom", "app_id": trace_id},
+        "model": _model_block(model),
+        "payload": {
+            "_migrated_from": "langfuse",
+            "name": raw.get("name"),
+            "type": obs_type,
+            "input": raw.get("input"),
+            "output": raw.get("output"),
+            "metadata": raw.get("metadata"),
+            "usage": raw.get("usage"),
+        },
+    }
+
+
+def openai_mapper(raw: Mapping[str, Any]) -> Optional[Dict[str, Any]]:
+    rid = raw.get("id") or raw.get("request_id")
+    if not isinstance(rid, str):
+        return None
+    model = raw.get("model") if isinstance(raw.get("model"), str) else None
+    created = raw.get("created") if isinstance(raw.get("created"), (int, float)) else None
+    created_at = raw.get("created_at")
+    if isinstance(created_at, str):
+        occurred = created_at
+    elif isinstance(created_at, (int, float)):
+        occurred = datetime.fromtimestamp(created_at, tz=timezone.utc).isoformat()
+    elif created is not None:
+        occurred = datetime.fromtimestamp(created, tz=timezone.utc).isoformat()
+    else:
+        occurred = None
+    usage = raw.get("usage")
+    if not isinstance(usage, Mapping):
+        usage = {
+            "prompt_tokens": raw.get("input_tokens"),
+            "completion_tokens": raw.get("output_tokens"),
+        }
+    return {
+        "idempotency_key": f"openai:{rid}",
+        "occurred_at": occurred,
+        "kind": "model_call",
+        "source": {"org_id": "", "framework": "custom"},
+        "model": _model_block(model),
+        "payload": {
+            "_migrated_from": "openai",
+            "request_id": rid,
+            "choices": raw.get("choices"),
+            "messages": raw.get("messages"),
+            "usage": usage,
+        },
+    }
+
+
+MAPPERS: Dict[str, Mapper] = {
+    "langsmith": langsmith_mapper,
+    "langfuse": langfuse_mapper,
+    "openai": openai_mapper,
+}
+
+
+def read_ndjson(stream: TextIO) -> Iterator[Dict[str, Any]]:
+    for line in stream:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            yield json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+
+def migrate(
+    client: ProvaClient,
+    source: str,
+    rows: Iterable[Mapping[str, Any]],
+    *,
+    batch_size: int = 200,
+    on_progress: Optional[Callable[[Dict[str, int]], None]] = None,
+) -> Dict[str, int]:
+    mapper = MAPPERS.get(source)
+    if mapper is None:
+        raise ValueError(f"unknown source format: {source}")
+    size = max(1, min(1000, batch_size))
+    batch: list[Dict[str, Any]] = []
+    total = ingested = skipped = batch_n = 0
+
+    def flush() -> None:
+        nonlocal batch, ingested, batch_n
+        if not batch:
+            return
+        batch_n += 1
+        res = client.ingest(batch)
+        ingested += int(res.get("count", 0))
+        if on_progress:
+            on_progress({"batch": batch_n, "ingested": ingested, "skipped": skipped, "total": total})
+        batch = []
+
+    for raw in rows:
+        total += 1
+        mapped = mapper(raw)
+        if mapped is None:
+            skipped += 1
+            continue
+        batch.append(mapped)
+        if len(batch) >= size:
+            flush()
+    flush()
+    return {"total": total, "ingested": ingested, "skipped": skipped, "batches": batch_n}

prova_cp/verify.py

@@ -0,0 +1,97 @@
+"""Offline receipt verification using cryptography's Ed25519 primitives."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any, Mapping, MutableMapping, Optional
+
+import httpx
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from .canonical import canonicalize
+
+DEFAULT_BASE_URL = "https://api.prova.cobound.dev"
+
+_KEY_CACHE: MutableMapping[str, Ed25519PublicKey] = {}
+
+
+class ReceiptVerificationError(Exception):
+    def __init__(self, message: str, receipt_id: Optional[str] = None) -> None:
+        super().__init__(message)
+        self.receipt_id = receipt_id
+
+
+def _load_public_key(
+    key_id: str,
+    *,
+    public_key_pem: Optional[str],
+    base_url: str,
+    client: Optional[httpx.Client],
+) -> Ed25519PublicKey:
+    if public_key_pem:
+        return serialization.load_pem_public_key(public_key_pem.encode("utf-8"))  # type: ignore[return-value]
+    cached = _KEY_CACHE.get(key_id)
+    if cached is not None:
+        return cached
+    base = base_url.rstrip("/")
+    own_client = False
+    if client is None:
+        client = httpx.Client(timeout=10.0)
+        own_client = True
+    try:
+        resp = client.get(f"{base}/api/v1/keys/{key_id}")
+        if resp.status_code != 200:
+            raise ReceiptVerificationError(
+                f"failed to fetch public key {key_id}: HTTP {resp.status_code}",
+                key_id,
+            )
+        body = resp.json()
+        pem = body.get("public_key_pem")
+        if not pem:
+            raise ReceiptVerificationError(f"key registry returned no PEM for {key_id}", key_id)
+        key = serialization.load_pem_public_key(pem.encode("utf-8"))
+        _KEY_CACHE[key_id] = key  # type: ignore[assignment]
+        return key  # type: ignore[return-value]
+    finally:
+        if own_client:
+            client.close()
+
+
+def verify_receipt(
+    receipt: Mapping[str, Any],
+    *,
+    public_key_pem: Optional[str] = None,
+    base_url: str = DEFAULT_BASE_URL,
+    client: Optional[httpx.Client] = None,
+) -> None:
+    """Verify a receipt's hash and Ed25519 signature. Raises on mismatch."""
+    integrity = receipt.get("integrity") or {}
+    payload = receipt.get("payload")
+    findings = receipt.get("findings", [])
+    canonical = canonicalize({"findings": findings, "payload": payload})
+    expected = hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    if expected != integrity.get("hash"):
+        raise ReceiptVerificationError(
+            f"hash mismatch: expected {expected}, got {integrity.get('hash')}",
+            receipt.get("event_id"),
+        )
+    key = _load_public_key(
+        integrity["key_id"],
+        public_key_pem=public_key_pem,
+        base_url=base_url,
+        client=client,
+    )
+    sig = bytes.fromhex(integrity["signature"])
+    try:
+        key.verify(sig, canonical.encode("utf-8"))
+    except InvalidSignature as e:
+        raise ReceiptVerificationError(
+            f"signature does not verify against key {integrity['key_id']}",
+            receipt.get("event_id"),
+        ) from e
+
+
+def _reset_key_cache_for_tests() -> None:
+    _KEY_CACHE.clear()

prova_cp/wrap.py

@@ -0,0 +1,111 @@
+"""Drop-in wrappers for raw OpenAI / Anthropic clients.
+
+For teams not on LangGraph or CrewAI. Wrap the vendor client once; every
+completion is mirrored to Prova as a signed `model_call` receipt. The wrapper
+returns the vendor response unchanged and never raises on a Prova failure, so
+it is safe to wrap a production client.
+
+    from openai import OpenAI
+    from prova_cp import ProvaClient
+    from prova_cp.wrap import wrap_openai
+
+    prova = ProvaClient(api_key="prv_...")
+    client = wrap_openai(OpenAI(), prova, app_id="support-bot", environment="production")
+
+    # use `client` exactly like the OpenAI client -- calls are auto-ingested
+    client.chat.completions.create(model="gpt-4o", messages=[...])
+
+`wrap_anthropic` is identical for the Anthropic SDK (`messages.create`).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+log = logging.getLogger(__name__)
+
+_MAX_LEN = 4000
+
+
+def _safe(obj: Any, depth: int = 0) -> Any:
+    if isinstance(obj, str):
+        return obj[:_MAX_LEN] + ("..." if len(obj) > _MAX_LEN else "")
+    if depth > 5:
+        return "[truncated]"
+    if isinstance(obj, dict):
+        return {k: _safe(v, depth + 1) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_safe(v, depth + 1) for v in list(obj)[:50]]
+    if hasattr(obj, "model_dump"):
+        try:
+            return _safe(obj.model_dump(), depth + 1)
+        except Exception:
+            pass
+    return obj if isinstance(obj, (int, float, bool, type(None))) else str(obj)[:_MAX_LEN]
+
+
+class _CreateProxy:
+    """Wraps a single `create` callable, ingesting after a successful call."""
+
+    def __init__(self, fn: Any, client: Any, source: dict, provider: str) -> None:
+        self._fn = fn
+        self._client = client
+        self._source = source
+        self._provider = provider
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        response = self._fn(*args, **kwargs)
+        try:
+            model = kwargs.get("model")
+            self._client.ingest({
+                "kind": "model_call",
+                "source": dict(self._source),
+                "model": {"provider": self._provider, "name": model},
+                "payload": {
+                    "request": _safe({k: v for k, v in kwargs.items() if k != "api_key"}),
+                    "response": _safe(response),
+                },
+            })
+        except Exception as exc:
+            log.warning("prova_cp.wrap: ingest failed (%s): %s", self._provider, exc)
+        return response
+
+
+class _AttrProxy:
+    """Transparently proxies attribute access, swapping in a _CreateProxy for
+    the configured leaf method (e.g. completions.create)."""
+
+    def __init__(self, target: Any, client: Any, source: dict, provider: str, path: tuple[str, ...]) -> None:
+        self.__dict__["_t"] = target
+        self.__dict__["_c"] = client
+        self.__dict__["_s"] = source
+        self.__dict__["_p"] = provider
+        self.__dict__["_path"] = path
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self.__dict__["_t"], name)
+        new_path = self.__dict__["_path"] + (name,)
+        leaf = (("chat", "completions", "create"), ("messages", "create"), ("responses", "create"))
+        if new_path in leaf and callable(attr):
+            return _CreateProxy(attr, self.__dict__["_c"], self.__dict__["_s"], self.__dict__["_p"])
+        if callable(attr) or isinstance(attr, (str, int, float, bool, type(None))):
+            return attr
+        return _AttrProxy(attr, self.__dict__["_c"], self.__dict__["_s"], self.__dict__["_p"], new_path)
+
+
+def _wrap(vendor_client: Any, prova_client: Any, provider: str, app_id: str, environment: str) -> Any:
+    source = {"app_id": app_id, "environment": environment, "framework": provider}
+    return _AttrProxy(vendor_client, prova_client, source, provider, ())
+
+
+def wrap_openai(vendor_client: Any, prova_client: Any, *, app_id: str = "agent", environment: str = "production") -> Any:
+    """Wrap an `openai.OpenAI` client. `chat.completions.create` and
+    `responses.create` calls are mirrored to Prova."""
+    return _wrap(vendor_client, prova_client, "openai", app_id, environment)
+
+
+def wrap_anthropic(vendor_client: Any, prova_client: Any, *, app_id: str = "agent", environment: str = "production") -> Any:
+    """Wrap an `anthropic.Anthropic` client. `messages.create` calls are
+    mirrored to Prova."""
+    return _wrap(vendor_client, prova_client, "anthropic", app_id, environment)

prova_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: prova-sdk
+Version: 0.1.0
+Summary: Agent-side SDK for the Prova AI control plane (ingest, gateway-check, register).
+Project-URL: Homepage, https://prova.cobound.dev/docs/sdk
+Project-URL: Documentation, https://prova.cobound.dev/docs/sdk
+License: MIT
+Keywords: agents,ai,audit,compliance,langgraph,llm,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Provides-Extra: langgraph
+Requires-Dist: langchain-core>=0.2; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# prova-sdk (Python)
+
+Agent-side SDK for the Prova AI control plane. Thin wrappers around:
+
+- `POST /api/v1/audit/ingest`
+- `POST /api/v1/gateway/check`
+- `POST /api/v1/inventory`
+
+Plus an Ed25519 receipt verifier and a one-shot migration tool that bulk-imports
+existing LangSmith / Langfuse / OpenAI logs into the Audit Vault.
+
+Separate from the legacy `prova` package (the reasoning-chain verifier).
+See `/docs/sdk` for guidance on which one to install.
+
+## Install
+
+```sh
+pip install prova-sdk
+```
+
+Requires Python 3.10+.
+
+## Quick start
+
+```python
+from prova_cp import ProvaClient
+
+prova = ProvaClient(api_key="prv_...")
+
+prova.ingest({
+    "kind": "model_call",
+    "source": {"org_id": "YOUR_ORG", "framework": "langgraph", "app_id": "claims-orchestrator"},
+    "model": {"provider": "openai", "name": "gpt-4o"},
+    "payload": {"messages": messages, "response": response},
+})
+
+check = prova.gateway_check({"kind": "model_call", "payload": {"messages": messages}})
+if check["action"] == "block":
+    raise PolicyBlocked(check["findings"])
+```
+
+Pass `verify_receipts=True` to make the client verify every returned receipt's
+Ed25519 signature against the published public key before returning.
+
+## LangGraph / LangChain auto-instrumentation
+
+Install the optional extra and drop the callback handler into any graph. Every
+LLM call, node, and tool call is ingested as a signed receipt automatically. No
+per-node code changes.
+
+```sh
+pip install "prova-sdk[langgraph]"
+```
+
+```python
+from prova_cp import ProvaClient, ProvaCallbackHandler
+
+prova = ProvaClient(api_key="prv_...")
+handler = ProvaCallbackHandler(
+    prova,
+    app_id="claims-orchestrator",
+    environment="production",
+    framework="langgraph",
+)
+
+# LangGraph
+graph.invoke(inputs, config={"callbacks": [handler]})
+
+# LangChain
+chain.invoke(inputs, config={"callbacks": [handler]})
+```
+
+The handler is fail-silent: a Prova outage logs at warning level and never
+breaks the agent. LLM calls become `model_call` receipts, graph nodes become
+`agent_step`, tool calls become `tool_call`.
+
+## CrewAI
+
+CrewAI has no LangChain-style callbacks; use its `step_callback` /
+`task_callback` hooks instead.
+
+```python
+from prova_cp import ProvaClient, ProvaCrewAI
+
+tap = ProvaCrewAI(ProvaClient(api_key="prv_..."), app_id="research-crew")
+crew = Crew(agents=[...], tasks=[...],
+            step_callback=tap.step_callback,
+            task_callback=tap.task_callback)
+```
+
+Agent steps become `agent_step` receipts; completed tasks become `agent_run`.
+
+## Raw OpenAI / Anthropic clients (no framework)
+
+Wrap the vendor client once. Every completion is mirrored to a signed receipt.
+The vendor response is returned unchanged and a Prova failure never raises.
+
+```python
+from openai import OpenAI
+from prova_cp import ProvaClient, wrap_openai
+
+client = wrap_openai(OpenAI(), ProvaClient(api_key="prv_..."), app_id="support-bot")
+client.chat.completions.create(model="gpt-4o", messages=[...])  # auto-ingested
+```
+
+`wrap_anthropic` is identical for the Anthropic SDK (`messages.create`).
+
+## Migrate existing logs
+
+CLI:
+
+```sh
+PROVA_API_KEY=prv_... prova-migrate --source langsmith --file runs.ndjson
+```
+
+Programmatic:
+
+```python
+from prova_cp import ProvaClient, migrate
+from prova_cp.migrate import read_ndjson
+
+with ProvaClient(api_key="prv_...") as client, open("observations.ndjson") as f:
+    result = migrate(client, "langfuse", read_ndjson(f))
+    print(result)
+```
+
+Supported sources: `langsmith`, `langfuse`, `openai`. Idempotency keys are
+derived from the source row id, so re-running the migration is safe.
+
+## Verify a receipt offline
+
+```python
+from prova_cp import verify_receipt
+
+verify_receipt(receipt, public_key_pem=PUBLIC_KEY_PEM)
+```
+
+Or fetch the public key from the deployment automatically:
+
+```python
+verify_receipt(receipt, base_url="https://api.prova.cobound.dev")
+```

prova_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+prova_cp/__init__.py,sha256=ezq5fn7zIU_sS811DNfOtc3jcQd8hXecd4NFZFAQXo4,745
+prova_cp/callbacks.py,sha256=ymiYZ2EIf2YOWD8LavQn_5vQYnWGQOs0jueUAR7aQ7M,9379
+prova_cp/canonical.py,sha256=QLHeDnndJIYt4bvZKCint7Es-fQ3M49_yjJWMb1HE7o,571
+prova_cp/cli.py,sha256=8__mNDoyImKG5Tm3gLUt_j607JtgsPu0bdvO_f9uKVs,1720
+prova_cp/client.py,sha256=Dp0WtuhUgg99jcTVIguXkAYmZQf_N_myVBoAxO8pHQM,4492
+prova_cp/crewai.py,sha256=DFAAMr1sm5H8l-tkWkhUnyJ7dvIRXhqfhJWPKJhsp8A,3258
+prova_cp/migrate.py,sha256=mv4wmbiKHDrFW1Vz3S9DLfOiZ7gN0gIoHENjm6YImBU,6264
+prova_cp/verify.py,sha256=ImeejuFkuK9UIj8MQjh7e9Nin2RH65HELqivpqc0mLc,3232
+prova_cp/wrap.py,sha256=OSM2bdjnOSwQmcgx8WaOQjrMTq7GIGdH5d2yLy2B17o,4495
+prova_sdk-0.1.0.dist-info/METADATA,sha256=zp0TR5IerW8uN1ZjdfW1TjC2gbnkCkDxfiWoryeqvaY,4811
+prova_sdk-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+prova_sdk-0.1.0.dist-info/entry_points.txt,sha256=2k2W3-LIfH81nhpY0CC41BRWAPeTr4GkG-zkgsvNPig,52
+prova_sdk-0.1.0.dist-info/RECORD,,

prova_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

prova_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+prova-migrate = prova_cp.cli:main