blackbox-sdk 0.3.1

Flight recorder SDK for AI agents — zero-dependency BLACKBOX client

BLACKBOX SDK

Zero-dependency Python SDK for recording AI agent runs into BLACKBOX — the flight recorder for AI agents.

Install

pip install blackbox-sdk

Or from source:

cd sdk && pip install -e .

Two-line integration

import blackbox_sdk as bb

bb.configure(api_url="https://your-blackbox.railway.app", api_key="<agent-key>")

with bb.run("invoice_review_4821", model="claude-sonnet-4-6", system_prompt="You are…") as run:
    run.reasoning("Analyzing the invoice for anomalies…")
    result = call_tool("ocr_extract", path="/tmp/invoice.pdf")
    run.tool_call("ocr_extract", {"path": "/tmp/invoice.pdf"}, result=result)
    run.output("Total: $4,200. No anomalies detected.", tokens_in=512, tokens_out=38, cost_usd=0.0024)
    run.seal()

Every event is hashed and chained. Replay, diff, and audit any run in the BLACKBOX UI.

Configuration

Method	Priority
bb.configure(api_url=..., api_key=...)	1 (highest)
BLACKBOX_API_URL / BLACKBOX_AGENT_KEY env vars	2
Defaults (http://localhost:8000, no key)	3

API reference

bb.run(run_id?, *, model, system_prompt, tools, sampling, policy_pack)

Returns a RunRecorder context manager. The genesis event is recorded on __enter__. Unhandled exceptions automatically record a fault event before re-raising.

RunRecorder methods

Method	Description
run.genesis()	Called automatically on enter
run.reasoning(text)	Chain-of-thought step
run.tool_call(tool, inputs, result?, latency_ms?)	Tool invocation
run.retrieval(query, results, source?)	RAG retrieval
run.decision(text)	Policy/routing decision
run.output(text, tokens_in?, tokens_out?, cost_usd?, latency_ms?)	Final output
run.fault(claim, fault_class?, severity?, description?)	Detected hallucination
run.seal(summary?)	Close the run chain
run.timed_tool_call(tool, inputs, fn, *args, **kwargs)	Auto-timed tool call

Fault classes

Class	Meaning
C1	Fabricated value
C2	Fabricated source / citation
C3	Out-of-scope claim
C4	Contradiction with prior context

Environment variables

BLACKBOX_API_URL=https://your-blackbox.railway.app
BLACKBOX_AGENT_KEY=bb_agent_...

Auto-instrumentation

Patch openai and anthropic globally — every LLM call is recorded automatically, zero agent code changes:

import blackbox_sdk as bb

bb.configure(api_url="https://your-blackbox.railway.app")
bb.instrument()  # patches openai + anthropic clients at startup

# Every client.messages.create() / client.chat.completions.create()
# is now automatically recorded as a BLACKBOX run.

# Selective patching:
bb.instrument(record_openai=False)   # Anthropic only
bb.instrument(record_anthropic=False) # OpenAI only

OpenTelemetry

BLACKBOX also accepts standard OTLP traces at /v1/otel/traces. See the OTel setup guide.