Metadata-Version: 2.4
Name: blackbox-sdk
Version: 0.3.0
Summary: Flight recorder SDK for AI agents — zero-dependency BLACKBOX client
Project-URL: Homepage, https://github.com/Leclezio69/blackbox
Project-URL: Documentation, https://blackbox-gold.vercel.app/docs
Project-URL: Repository, https://github.com/Leclezio69/blackbox
License: MIT
Keywords: agents,ai,audit,llm,observability
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# BLACKBOX SDK

Zero-dependency Python SDK for recording AI agent runs into [BLACKBOX](https://frontend-three-self-24.vercel.app) — the flight recorder for AI agents.

## Install

```bash
pip install blackbox-sdk
```

Or from source:

```bash
cd sdk && pip install -e .
```

## Two-line integration

```python
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

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

## OpenTelemetry

BLACKBOX also accepts standard OTLP traces at `/v1/otel/traces`. See the [OTel setup guide](https://frontend-three-self-24.vercel.app/otel).
