proofledger 0.1.0__tar.gz

proofledger-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Local dev event log
+.proofledger/
+
+# Python build / cache artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/

proofledger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProofLedger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proofledger-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: proofledger
+Version: 0.1.0
+Summary: Framework-agnostic, tamper-evident audit layer for AI agents. Hash chains verify byte-for-byte against the ProofLedger TypeScript SDK and dashboard.
+Project-URL: Homepage, https://proofledger.dev
+Project-URL: Repository, https://github.com/jorama/proofledger
+Project-URL: Issues, https://github.com/jorama/proofledger/issues
+Author: ProofLedger
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,audit,hash-chain,llm,observability,proofledger,tamper-evident,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: cryptography>=41; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: signing
+Requires-Dist: cryptography>=41; extra == 'signing'
+Description-Content-Type: text/markdown
+
+# ProofLedger Python SDK
+
+A framework-agnostic, tamper-evident audit layer for AI agents. ProofLedger sits
+underneath or beside any agent framework (LangGraph, CrewAI, OpenAI Agents SDK,
+AutoGen, or a custom stack) and records every run, event, and tool call into a
+SHA-256 hash chain.
+
+The chains this SDK produces are **byte-for-byte compatible** with the
+ProofLedger TypeScript SDK: runs captured from Python verify correctly in the
+ProofLedger dashboard, which verifies using the TS implementation.
+
+No third-party runtime dependencies — standard library only (Python >= 3.9).
+
+## Install
+
+```bash
+pip install proofledger
+```
+
+Or from this repo:
+
+```bash
+pip install packages/sdk-py
+```
+
+## Usage
+
+```python
+from proofledger import enable, track, with_run, verify_run
+
+# Cloud mode — sends to your ProofLedger backend.
+enable(
+    api_key="tl_live_...",
+    base_url="https://proofledger.dev",
+    project_id="proj_...",
+)
+
+# One-shot tracking of a complete, verifiable run.
+track(
+    agent_id="support-agent",
+    input="Hello",
+    output="Hi there",
+    model="gpt-4.1",
+    provider="openai",
+)
+```
+
+If you call `enable()` without an `api_key` (or pass `local=True`), the SDK runs
+in **local dev mode**: events are kept in memory and best-effort appended to
+`./.proofledger/events.jsonl`, with no server required.
+
+### Wrapping a unit of work with `with_run`
+
+`with_run` opens a run, runs your function, records the result (or the error),
+and closes the run — all on a verifiable chain. The callback receives a
+`RunHandle` you can use to record tool calls and custom events.
+
+```python
+from proofledger import enable, with_run, verify_run
+
+enable(local=True)  # local dev mode, no api key
+
+def do_work(run):
+    # Record a tool call — emits tool.called + tool.returned around the record.
+    run.record_tool_call(
+        tool_name="search_kb",
+        input={"query": "refund policy"},
+        output={"hits": 3},
+    )
+    return {"answer": "Refunds within 30 days."}
+
+result = with_run({"agent_id": "support-agent", "model": "gpt-4.1"}, do_work)
+
+# Verify the run's hash chain.
+report = verify_run(...)  # pass the run id; see examples/basic.py
+print(report["valid"])    # True
+```
+
+See [`examples/basic.py`](examples/basic.py) for a complete, runnable example:
+
+```bash
+python examples/basic.py
+```
+
+## Hashing primitives
+
+The same primitives the dashboard uses are re-exported:
+
+```python
+from proofledger import (
+    create_payload_hash,
+    create_event_hash,
+    verify_event_chain,
+    GENESIS_HASH,
+)
+```
+
+- **Canonical JSON**: object keys are sorted recursively and serialized with no
+  whitespace and literal Unicode, matching JS `JSON.stringify` with sorted keys.
+- `GENESIS_HASH` is 64 zeros — the `previousHash` of the first event.
+- `create_event_hash` commits to the event id, type, timestamp, payload hash,
+  and the previous event's hash, chaining every event to the one before it.
+
+Because the canonicalization and digests match the TypeScript SDK exactly, a
+chain captured in Python verifies identically in the ProofLedger dashboard.

proofledger-0.1.0/README.md

@@ -0,0 +1,105 @@
+# ProofLedger Python SDK
+
+A framework-agnostic, tamper-evident audit layer for AI agents. ProofLedger sits
+underneath or beside any agent framework (LangGraph, CrewAI, OpenAI Agents SDK,
+AutoGen, or a custom stack) and records every run, event, and tool call into a
+SHA-256 hash chain.
+
+The chains this SDK produces are **byte-for-byte compatible** with the
+ProofLedger TypeScript SDK: runs captured from Python verify correctly in the
+ProofLedger dashboard, which verifies using the TS implementation.
+
+No third-party runtime dependencies — standard library only (Python >= 3.9).
+
+## Install
+
+```bash
+pip install proofledger
+```
+
+Or from this repo:
+
+```bash
+pip install packages/sdk-py
+```
+
+## Usage
+
+```python
+from proofledger import enable, track, with_run, verify_run
+
+# Cloud mode — sends to your ProofLedger backend.
+enable(
+    api_key="tl_live_...",
+    base_url="https://proofledger.dev",
+    project_id="proj_...",
+)
+
+# One-shot tracking of a complete, verifiable run.
+track(
+    agent_id="support-agent",
+    input="Hello",
+    output="Hi there",
+    model="gpt-4.1",
+    provider="openai",
+)
+```
+
+If you call `enable()` without an `api_key` (or pass `local=True`), the SDK runs
+in **local dev mode**: events are kept in memory and best-effort appended to
+`./.proofledger/events.jsonl`, with no server required.
+
+### Wrapping a unit of work with `with_run`
+
+`with_run` opens a run, runs your function, records the result (or the error),
+and closes the run — all on a verifiable chain. The callback receives a
+`RunHandle` you can use to record tool calls and custom events.
+
+```python
+from proofledger import enable, with_run, verify_run
+
+enable(local=True)  # local dev mode, no api key
+
+def do_work(run):
+    # Record a tool call — emits tool.called + tool.returned around the record.
+    run.record_tool_call(
+        tool_name="search_kb",
+        input={"query": "refund policy"},
+        output={"hits": 3},
+    )
+    return {"answer": "Refunds within 30 days."}
+
+result = with_run({"agent_id": "support-agent", "model": "gpt-4.1"}, do_work)
+
+# Verify the run's hash chain.
+report = verify_run(...)  # pass the run id; see examples/basic.py
+print(report["valid"])    # True
+```
+
+See [`examples/basic.py`](examples/basic.py) for a complete, runnable example:
+
+```bash
+python examples/basic.py
+```
+
+## Hashing primitives
+
+The same primitives the dashboard uses are re-exported:
+
+```python
+from proofledger import (
+    create_payload_hash,
+    create_event_hash,
+    verify_event_chain,
+    GENESIS_HASH,
+)
+```
+
+- **Canonical JSON**: object keys are sorted recursively and serialized with no
+  whitespace and literal Unicode, matching JS `JSON.stringify` with sorted keys.
+- `GENESIS_HASH` is 64 zeros — the `previousHash` of the first event.
+- `create_event_hash` commits to the event id, type, timestamp, payload hash,
+  and the previous event's hash, chaining every event to the one before it.
+
+Because the canonicalization and digests match the TypeScript SDK exactly, a
+chain captured in Python verifies identically in the ProofLedger dashboard.

proofledger-0.1.0/examples/basic.py

@@ -0,0 +1,75 @@
+"""Runnable ProofLedger example in LOCAL mode (no API key required).
+
+Run it with::
+
+    python examples/basic.py
+
+It performs a one-shot ``track`` and a ``with_run`` that records a tool call,
+then prints the verification result for the ``with_run`` chain.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+# Allow running directly from a checkout without installing the package.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from proofledger import enable, track, verify_run, with_run  # noqa: E402
+
+
+def main() -> None:
+    # Local dev mode — no api key, events kept in memory + ./.proofledger.
+    enable(local=True)
+
+    # 1. One-shot tracking of a complete run.
+    tracked = track(
+        agent_id="support-agent",
+        input="What is your refund policy?",
+        output="Refunds are available within 30 days of purchase.",
+        model="gpt-4.1",
+        provider="openai",
+        usage={"promptTokens": 12, "completionTokens": 18},
+    )
+    track_report = verify_run(tracked["runId"])
+    print(f"track run:    {tracked['runId']}")
+    print(
+        f"  valid={track_report['valid']} "
+        f"events={track_report['eventCount']} "
+        f"issues={len(track_report['issues'])}"
+    )
+
+    # 2. A wrapped unit of work that records a tool call.
+    captured = {}
+
+    def do_work(run):
+        captured["run_id"] = run.run_id
+        run.record_tool_call(
+            tool_name="search_kb",
+            input={"query": "refund policy"},
+            output={"hits": 3, "top": "Refunds within 30 days."},
+        )
+        return {"answer": "Refunds are available within 30 days."}
+
+    with_run(
+        {"agent_id": "support-agent", "model": "gpt-4.1", "provider": "openai"},
+        do_work,
+    )
+
+    run_report = verify_run(captured["run_id"])
+    print(f"with_run:     {captured['run_id']}")
+    print(
+        f"  valid={run_report['valid']} "
+        f"events={run_report['eventCount']} "
+        f"issues={len(run_report['issues'])}"
+    )
+
+    all_valid = track_report["valid"] and run_report["valid"]
+    print()
+    print(f"All chains valid: {all_valid}")
+    sys.exit(0 if all_valid else 1)
+
+
+if __name__ == "__main__":
+    main()

proofledger-0.1.0/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-0.1.0/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),
+    }