atb-sdk 0.9.0b1

Python SDK for ATB (Agent Trace Bundle) — local-first AI audit trail

ATB Python SDK

The official Python SDK for ATB (Agent Trace Bundle) - local-first, tamper-evident audit trails for AI workflows.

Source repository: github.com/pcguest/atb

Installation

pip install atb-sdk

Use this package when you need to write or verify bundles from Python code. The Go CLI remains the authoritative CLI path:

go install github.com/pcguest/atb/cmd/atb@latest

The package does not include a standalone ATB CLI. The installed atb command is a compatibility stub that prints Go CLI install guidance and will be removed in a future major release.

With LangChain integration:

pip install atb-sdk[langchain]

Quick Start

from atb import Bundle

# Create a new bundle in Python
bundle = Bundle()

# Append events
bundle.append("dev.session", {
    "date": "2025-01-15",
    "features_built": ["hash chaining", "CLI init"],
    "blockers": ["RFC 8785 library compatibility"],
})

bundle.append("decision", {
    "choice": "Go over Rust for CLI",
    "reason": "fast static binaries with straightforward cross-platform builds",
    "alternatives": ["Rust", "Python-only"],
})

# Save to disk
bundle.save("run.atb/bundle.atb")

# Later - reload and verify integrity
b = Bundle.load("run.atb/bundle.atb")
b.verify()  # Raises ATBVerificationError if tampered
print(f"Verified {len(b)} records (including manifest) - chain intact.")

Bundle() starts with an atb.bundle.manifest record at seq = 0. Appended events start at seq = 1.

LangChain Integration

from atb import Bundle
from atb.langchain_callback import ATBCallbackHandler
from langchain.chat_models import ChatOpenAI

bundle = Bundle()
handler = ATBCallbackHandler(bundle, auto_save=True)

llm = ChatOpenAI(callbacks=[handler])
# All LLM calls are now automatically recorded in the bundle.

The callback emits the canonical ai.chain.run, ai.llm.call, and ai.tool.exec event types and also sets the top-level timestamp, trace_id, span_id, and parent_span_id event fields used by the Go runtime.

The deprecated shim import path atb.integrations.langchain.ATBCallbackHandler still works for compatibility, but it emits a DeprecationWarning. Use atb.langchain_callback.ATBCallbackHandler for new code.

Licence

MIT