proofpacket 0.1.0

Privacy-safe evidence packets for AI agent runs

ProofPacket

Your AI agent did 47 things. Send your client one proof packet.

Local-first. No SaaS account. ProofPacket does not send your packet data to a ProofPacket service.

ProofPacket is an open-source Python SDK and JSON schema for privacy-safe evidence packets for AI agent runs and LLM workflows.

Use ProofPacket when you need an AI agent audit trail, LLM audit log, AI automation evidence packet, or client-facing proof of what an AI workflow did without storing raw prompts, outputs, files, source URLs, local paths, or secrets.

ProofPacket records LLM calls, tool calls, file access, human approvals, sources, risk flags, and hash-chain verification as a shareable evidence packet.

v0.1 includes thin wrappers for Anthropic messages.create(...) and OpenAI chat.completions.create(...). Other Python LLM workflows can use the SDK directly. LangChain, MCP, and Claude Code integrations are planned.

No raw prompts. No file contents. No leaked source URLs or local paths by default. Verifiable.

Provider wrappers still call the configured LLM provider. ProofPacket keeps the JSON/Markdown evidence packet local unless you choose to share it.

$ proofpacket verify examples/sample_packet.json
valid

The Flagship Use Case

An AI agency runs an automation for a client. The workflow touches models, tools, local files, web sources, and human approvals. The agency needs to show what happened without handing over raw prompts, outputs, files, secrets, or private source URLs.

ProofPacket creates one shareable proof packet:

1. The automation runs.
2. The SDK records bucketed events and hashes sensitive content.
3. A Markdown proof packet is generated for the client.
4. The client can verify the packet hash chain locally.

That is the wedge: a client-facing proof packet for AI work.

When Should I Use ProofPacket?

Use ProofPacket when you are building an AI agent or LLM workflow and need a small evidence packet. Built-in wrappers currently cover Anthropic and OpenAI; other frameworks can use the SDK directly.

ProofPacket is especially useful for AI agencies, consultants, and developers who need to show what an AI workflow did without sharing the raw work.

Install

pip install proofpacket

For local development:

pip install -e ".[dev]"

60-Second Quickstart

from proofpacket import Packet

packet = Packet(task="vendor_risk_review", actor="ai_agent")

with packet.llm_call(
    provider="anthropic",
    model="claude-4.5-sonnet",
    bucket="summary_or_reasoning",
) as call:
    call.record_input("Summarize vendor privacy policy.")
    call.record_output("Vendor appears to retain customer data...")

packet.tool_call(
    tool="browser.search",
    bucket="web_research",
    target="vendor privacy policy",
    result_summary="Found vendor privacy policy and terms.",
)

packet.human_review(
    reviewer="user",
    decision="approved",
    note="Reviewed before sharing with client.",
)

packet.finish(status="completed")
packet.export_json("proofpacket.json")
packet.export_markdown("proofpacket.md")

Working Provider Wrappers

Use a wrapper when you want ProofPacket to log provider calls automatically.

pip install "proofpacket[anthropic,openai]"

Anthropic

from anthropic import Anthropic
from proofpacket import Packet
from proofpacket.wrappers.anthropic import wrap_client

packet = Packet(task="client_research", actor="ai_agent")
client = wrap_client(Anthropic(), receipt=packet, bucket="vendor_policy_review")

response = client.messages.create(
    model="claude-4.5-sonnet",
    max_tokens=300,
    messages=[{"role": "user", "content": "Summarize this vendor policy."}],
)

packet.finish(status="completed")
packet.export_markdown("client_proof_packet.md")

OpenAI

from openai import OpenAI
from proofpacket import Packet
from proofpacket.wrappers.openai import wrap_client

packet = Packet(task="client_research", actor="ai_agent")
client = wrap_client(OpenAI(), receipt=packet, bucket="vendor_policy_review")

response = client.chat.completions.create(
    model="gpt-4.1",
    messages=[{"role": "user", "content": "Summarize this vendor policy."}],
)

packet.finish(status="completed")
packet.export_markdown("client_proof_packet.md")

The OpenAI wrapper currently targets Chat Completions. Responses API support is planned.

The wrappers record provider, model, input hash, output hash, token counts when available, timestamp, and event hash. They do not store raw prompts or outputs unless you explicitly use privacy_mode="raw_capture" and raw_capture=True.

You can override the event bucket on an individual call with proofpacket_bucket="summary"; the wrapper removes that helper argument before delegating to the provider.

CLI

proofpacket init
proofpacket validate proofpacket.json
proofpacket verify proofpacket.json
proofpacket summarize proofpacket.json
proofpacket export proofpacket.json --markdown proofpacket.md

export refuses invalid packets unless you pass --force.

Privacy-Safe By Default

By default, record_input and record_output store SHA-256 hashes and character counts, not raw text.

Local file paths, filenames, tool targets, and source URIs are hashed or omitted by default. Caller-supplied notes, summaries, labels, and metadata strings pass through basic redaction and truncation.

privacy_mode is enforced:

• hash_only rejects previews and raw capture.
• preview permits redacted previews.
• raw_capture is required before raw LLM content can be stored.

The redaction helpers are convenience utilities, not a substitute for a DLP system.

Trust Model

ProofPacket v0.1 packets are self-attested with integrity protection.

The hash chain can show that a packet changed after it was written. It cannot prove that the packet captured every action or that every event was categorized honestly.

Hashes are integrity anchors, not the whole audit story. A SHA-256 hash of an input or file is strongest when the original evidence is retained somewhere else and can be compared later.

The attested_by field records who or what created the packet. Future Trust Anchor deployments may support signed events from MCP hosts, provider wrappers, sandboxed runtimes, or human reviewers.

See docs/trust_anchor.md.

What ProofPacket Is Not

ProofPacket is not a hosted service. It produces a local file. There is no account to create and no data sent to a third party.

ProofPacket is not an observability platform, agent runtime, sandbox, policy engine, or legal compliance product. It is a minimal audit envelope that can sit beside those tools.

It is designed to support auditability and compliance workflows, but it does not claim SOC 2, HIPAA, ISO 42001, GDPR, or other certification.

How It Fits

ProofPacket complements observability tools such as LangSmith, Langfuse, Helicone, and OpenTelemetry. It is narrower: a client-safe evidence packet rather than a full trace.

Hosted audit-trail services store events on their infrastructure. ProofPacket produces a local file, with optional Sigstore Rekor anchoring on the roadmap.

See docs/comparison.md.

Schema And Hashes

Proof packets use deterministic JSON canonicalization, event hashes, previous-event hashes, and a final packet hash.

ProofPacket v0.1 pins its Python JSON serialization rules in docs/canonicalization.md. This is deterministic for packets emitted by the Python SDK, but it is not yet a full RFC 8785 implementation. Cross-language verification should be treated as experimental until a future schema version moves to JCS or a matching TypeScript profile.

Project Status

ProofPacket is pre-1.0. Expect breaking schema changes before v1.0.

The project should stay small: evidence packets first, wrappers second, hosted storage later.

Roadmap

Near term:

• LangChain callback handler
• MCP tool wrapper
• Ed25519 self-signing
• RFC 8785/JCS canonicalization decision

Later:

• TypeScript SDK
• PDF export
• OpenTelemetry exporter
• GitHub Action for AI-generated PR evidence
• Hosted Evidence Locker