proofledger 0.1.0__py3-none-any.whl

proofledger/__init__.py

@@ -0,0 +1,193 @@
+"""ProofLedger Python SDK.
+
+A framework-agnostic, tamper-evident audit layer for AI agents. Produces hash
+chains that are byte-for-byte compatible with the ProofLedger TypeScript SDK, so
+runs captured from Python verify correctly in the ProofLedger dashboard.
+
+Quick start::
+
+    from proofledger import enable, track, with_run, verify_run
+
+    enable(api_key="tl_live_...", base_url="https://proofledger.dev",
+           project_id="proj_...")
+    track(agent_id="support-agent", input="Hello", output="Hi there",
+          model="gpt-4.1", provider="openai")
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from .client import RunHandle, ProofLedgerClient, iso_now
+from .hashing import (
+    GENESIS_HASH,
+    ChainVerificationResult,
+    canonicalize,
+    create_event_hash,
+    create_payload_hash,
+    sha256,
+    verify_event_chain,
+)
+from .ids import new_id
+from .transport import HttpTransport, LocalTransport, Transport
+
+__all__ = [
+    # Lifecycle / module-level API
+    "enable",
+    "create_client",
+    "client",
+    "track",
+    "start_run",
+    "end_run",
+    "record_event",
+    "record_tool_call",
+    "with_run",
+    "verify_run",
+    "request_approval",
+    "await_approval",
+    "require_approval",
+    "register_agent_identity",
+    "send_agent_message",
+    # Adapters
+    "instrument",
+    "wrap_openai",
+    "create_langchain_handler",
+    # Signing (Phase 6)
+    "create_agent_identity",
+    "sign_message",
+    "verify_message",
+    "signing_available",
+    # Building blocks
+    "ProofLedgerClient",
+    "RunHandle",
+    "Transport",
+    "LocalTransport",
+    "HttpTransport",
+    # Hashing
+    "create_payload_hash",
+    "create_event_hash",
+    "verify_event_chain",
+    "canonicalize",
+    "sha256",
+    "GENESIS_HASH",
+    "ChainVerificationResult",
+    "new_id",
+    "iso_now",
+]
+
+T = TypeVar("T")
+
+#: The lazily-bootstrapped module-level singleton.
+_global_client: Optional[ProofLedgerClient] = None
+
+
+def _get_client() -> ProofLedgerClient:
+    """Resolve the active client.
+
+    If :func:`enable` was never called, lazily bootstrap a silent local-mode
+    client so that ``from proofledger import track`` simply works in dev.
+    """
+    global _global_client
+    if _global_client is None:
+        _global_client = ProofLedgerClient(silent=True)
+    return _global_client
+
+
+def enable(
+    api_key: Optional[str] = None,
+    project_id: str = "default-project",
+    base_url: str = "http://localhost:3000",
+    environment: str = "development",
+    local: bool = False,
+    local_dir: Optional[str] = None,
+    silent: bool = False,
+    disabled: bool = False,
+) -> ProofLedgerClient:
+    """Initialize the global client and return it for advanced use."""
+    global _global_client
+    _global_client = ProofLedgerClient(
+        api_key=api_key,
+        project_id=project_id,
+        base_url=base_url,
+        environment=environment,
+        local=local,
+        local_dir=local_dir,
+        silent=silent,
+        disabled=disabled,
+    )
+    return _global_client
+
+
+def create_client(**options: Any) -> ProofLedgerClient:
+    """Create an isolated client instead of using the global singleton."""
+    return ProofLedgerClient(**options)
+
+
+def client() -> ProofLedgerClient:
+    """The active client (auto-bootstrapped in local mode if needed)."""
+    return _get_client()
+
+
+def track(**kwargs: Any) -> Dict[str, str]:
+    """One-shot tracking. See :meth:`ProofLedgerClient.track`."""
+    return _get_client().track(**kwargs)
+
+
+def start_run(**kwargs: Any) -> RunHandle:
+    return _get_client().start_run(**kwargs)
+
+
+def end_run(run_id: str, result: Optional[Dict[str, Any]] = None) -> None:
+    return _get_client().end_run(run_id, result)
+
+
+def record_event(**kwargs: Any) -> Dict[str, Any]:
+    return _get_client().record_event(**kwargs)
+
+
+def record_tool_call(**kwargs: Any) -> Dict[str, Any]:
+    return _get_client().record_tool_call(**kwargs)
+
+
+def with_run(context: Dict[str, Any], fn: Callable[[RunHandle], T]) -> T:
+    return _get_client().with_run(context, fn)
+
+
+def verify_run(run_id: str) -> ChainVerificationResult:
+    return _get_client().verify_run(run_id)
+
+
+def request_approval(**kwargs: Any) -> Dict[str, Any]:
+    """Create a human-approval request. See :meth:`ProofLedgerClient.request_approval`."""
+    return _get_client().request_approval(**kwargs)
+
+
+def await_approval(approval_id: str, **kwargs: Any) -> str:
+    return _get_client().await_approval(approval_id, **kwargs)
+
+
+def require_approval(**kwargs: Any) -> str:
+    """Request approval and block until decided (raises if denied)."""
+    return _get_client().require_approval(**kwargs)
+
+
+def register_agent_identity(agent_id: str, public_key: str, algorithm: str = "ed25519") -> None:
+    """Register an agent's Ed25519 public key. See ProofLedgerClient.register_agent_identity."""
+    return _get_client().register_agent_identity(agent_id, public_key, algorithm)
+
+
+def send_agent_message(**kwargs: Any) -> Dict[str, Any]:
+    """Sign and send a verified agent-to-agent message."""
+    return _get_client().send_agent_message(**kwargs)
+
+
+# Adapters (imported lazily-safe; they resolve the global client at call time).
+from .adapters import instrument, wrap_openai, create_langchain_handler  # noqa: E402
+
+# Signing (Phase 6) — needs the optional `cryptography` extra.
+from .signing import (  # noqa: E402
+    create_agent_identity,
+    sign_message,
+    verify_message,
+    signing_available,
+)

proofledger/adapters.py

@@ -0,0 +1,157 @@
+"""Framework adapters — one-line instrumentation for popular agent stacks.
+
+Duck-typed: nothing is imported from OpenAI/LangChain/etc., so the SDK keeps zero
+runtime dependencies. Adapters use the global ProofLedger client by default.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Optional
+
+__all__ = ["instrument", "wrap_openai", "create_langchain_handler"]
+
+
+def _default_client() -> Any:
+    # Lazy import to avoid a circular import with the package __init__.
+    from . import client as _client
+
+    return _client()
+
+
+def instrument(context: dict, fn: Callable[[Any], Any], client: Optional[Any] = None) -> Any:
+    """Wrap any callable as a fully-tracked run.
+
+    ``context`` is a dict of :meth:`ProofLedgerClient.start_run` kwargs.
+    """
+    c = client or _default_client()
+    return c.with_run(context, fn)
+
+
+def wrap_openai(openai: Any, agent_id: str = "openai", client: Optional[Any] = None) -> Any:
+    """Instrument an OpenAI client so each ``chat.completions.create(...)`` is
+    captured as a ProofLedger run (input, output, model, token usage).
+
+        openai = wrap_openai(OpenAI(), agent_id="support-agent")
+    """
+    c = client or _default_client()
+    completions = openai.chat.completions
+    original = completions.create
+
+    def wrapped(**params: Any) -> Any:
+        run = c.start_run(
+            agent_id=agent_id,
+            provider="openai",
+            model=params.get("model"),
+            input=params.get("messages") or params.get("input"),
+        )
+        started = time.time() * 1000.0
+        try:
+            res = original(**params)
+            message = _extract_message(res)
+            run.record_event("model.responded", {"output": message})
+            usage = _extract_usage(res)
+            c.end_run(
+                run.run_id,
+                {
+                    "status": "success",
+                    "output": message,
+                    "latencyMs": time.time() * 1000.0 - started,
+                    "usage": usage,
+                },
+            )
+            return res
+        except Exception as err:  # noqa: BLE001 - re-raised below
+            c.end_run(
+                run.run_id,
+                {
+                    "status": "failed",
+                    "error": str(err),
+                    "latencyMs": time.time() * 1000.0 - started,
+                },
+            )
+            raise
+
+    completions.create = wrapped  # type: ignore[assignment]
+    return openai
+
+
+def _extract_message(res: Any) -> Optional[str]:
+    try:
+        choice = res.choices[0]
+        message = getattr(choice, "message", None)
+        if message is not None:
+            return getattr(message, "content", None)
+        return getattr(choice, "text", None)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def create_langchain_handler(agent_id: str = "langchain", client: Optional[Any] = None) -> Any:
+    """A LangChain callback handler that records each LLM + tool call as a run.
+
+    Duck-typed against LangChain's ``BaseCallbackHandler`` surface (no import
+    needed). Pass it via ``callbacks=[create_langchain_handler(agent_id="...")]``.
+    """
+    c = client or _default_client()
+    runs: dict = {}
+
+    class ProofLedgerCallbackHandler:
+        ignore_llm = False
+        ignore_chain = False
+        ignore_agent = False
+        ignore_retriever = False
+        ignore_chat_model = False
+        ignore_custom_event = False
+        raise_error = False
+        run_inline = False
+
+        def on_llm_start(self, serialized: Any, prompts: Any, **kwargs: Any) -> None:
+            run = c.start_run(
+                agent_id=agent_id,
+                provider="langchain",
+                model=(serialized or {}).get("name") if isinstance(serialized, dict) else None,
+                input=prompts,
+            )
+            runs[str(kwargs.get("run_id"))] = run
+
+        def on_llm_end(self, response: Any, **kwargs: Any) -> None:
+            run = runs.pop(str(kwargs.get("run_id")), None)
+            if run is None:
+                return
+            text = None
+            try:
+                text = response.generations[0][0].text
+            except Exception:  # noqa: BLE001
+                pass
+            run.record_event("model.responded", {"output": text})
+            c.end_run(run.run_id, {"status": "success", "output": text})
+
+        def on_llm_error(self, error: Any, **kwargs: Any) -> None:
+            run = runs.pop(str(kwargs.get("run_id")), None)
+            if run is not None:
+                c.end_run(run.run_id, {"status": "failed", "error": str(error)})
+
+        def on_tool_start(self, serialized: Any, input_str: Any, **kwargs: Any) -> None:
+            parent = runs.get(str(kwargs.get("parent_run_id")))
+            if parent is not None:
+                name = (serialized or {}).get("name", "tool") if isinstance(serialized, dict) else "tool"
+                parent.record_event("tool.called", {"toolName": name, "input": input_str})
+
+        def on_tool_end(self, output: Any, **kwargs: Any) -> None:
+            parent = runs.get(str(kwargs.get("parent_run_id")))
+            if parent is not None:
+                parent.record_event("tool.returned", {"output": str(output)})
+
+    return ProofLedgerCallbackHandler()
+
+
+def _extract_usage(res: Any) -> Optional[dict]:
+    usage = getattr(res, "usage", None)
+    if usage is None:
+        return None
+    return {
+        "promptTokens": getattr(usage, "prompt_tokens", None),
+        "completionTokens": getattr(usage, "completion_tokens", None),
+        "totalTokens": getattr(usage, "total_tokens", None),
+    }