prova-sdk 0.1.0__tar.gz

prova_sdk-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# dependencies
+node_modules/
+
+# next.js
+.next/
+out/
+
+# build
+tsconfig.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+
+# env
+.env
+.env.local
+.env*.local
+
+# supabase local dev metadata
+supabase/.temp/
+
+# vercel
+.vercel
+
+# package lock
+package-lock.json
+
+# python
+__pycache__/
+*.py[cod]
+*.pyo
+.pytest_cache/
+
+# playwright
+/playwright-report/
+/test-results/
+/playwright/.cache/

prova_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,142 @@
+# 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/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_sdk-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_sdk-0.1.0/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) + "}"