Metadata-Version: 2.4
Name: retrace-sdk
Version: 0.13.0
Summary: Record, replay, fork & share AI agent executions
Project-URL: Homepage, https://retrace.yashbogam.me
Project-URL: Repository, https://github.com/yash1511-bogam/retrace-sdk
Project-URL: Documentation, https://retrace.yashbogam.me/docs/sdk-python
Author: Yash Bogam
License: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,gemini,llm,observability,openai,replay,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
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.10
Requires-Dist: requests>=2.32.0
Requires-Dist: websocket-client>=1.9.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.52.0; extra == 'gemini'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# retrace-sdk

The execution replay engine for AI agents. Record every LLM call, tool invocation, and error your AI agent makes. Replay step-by-step. Fork from any point. Share interactive traces via URL.

## Install

```bash
pip install retrace-sdk
```

Requires Python 3.10+.

## Quick Start

```python
import retrace

retrace.configure(api_key="rt_live_...")  # Get your key at retrace.yashbogam.me/settings

@retrace.record(name="my-agent")
def run_agent(prompt: str):
    response = client.chat.completions.create(
        model="gpt-5.5",
        messages=[{"role": "user", "content": prompt}]
    )
    return response.choices[0].message.content

run_agent("What is quantum computing?")
```

## Auto-Instrumentation

Retrace automatically captures LLM calls from all major providers:

```python
# OpenAI — captured automatically
# Anthropic — captured automatically
# Google Gemini — captured automatically
```

No extra setup needed. Install the provider SDK alongside `retrace-sdk` and calls are captured.

## Features

- **Record** — One decorator captures every LLM call, tool call, and error
- **Replay** — Step through executions with play/pause/speed controls
- **Fork** — Branch from any step, modify input, watch a new path diverge
- **Share** — Publish traces as shareable "tapes" with interactive playback
- **Retrace AI** — Built-in evaluations, memory extraction, and semantic search

## Resumable Execution (Cascade Replay)

Mark a function as resumable to enable full cascade replay from the dashboard:

```python
@retrace.record(name="my-agent", resumable=True)
def run_agent(prompt: str):
    plan = call_planner(prompt)
    result = call_executor(plan)
    return summarize(result)
```

When you fork at any span in the dashboard, the SDK re-executes the entire function with modified input — all subsequent LLM calls diverge.

## Error Handling

```python
from retrace import RetraceError, RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError, RetraceEnforcementError
```

## Enforcement (Circuit Breakers)

Hard ceilings that stop a runaway agent before the next call. Local limits are enforced offline (zero network); `server_enforcement=True` also consults centrally-managed server policies.

```python
import retrace
from retrace import RetraceEnforcementError

retrace.configure(
    api_key="rt_live_...",
    max_steps_per_run=50,
    max_usd_per_run=2.0,
    server_enforcement=True,  # optional: also consult server policies
)

try:
    run_agent("...")
except RetraceEnforcementError as e:
    print(e.verdict, e.reason)  # e.g. "block", "Local USD ceiling reached: ..."
```

Precedence: explicit arg > env var (`RETRACE_MAX_STEPS_PER_RUN`, `RETRACE_MAX_TOKENS_PER_RUN`, `RETRACE_MAX_USD_PER_RUN`, `RETRACE_SERVER_ENFORCEMENT`) > unset. If the server check is unreachable, local limits still apply.

## Multi-Agent Context

Tag spans with an agent id/role so the dashboard can draw the agent topology and run inter-agent detectors (ping-pong, reasoning–action mismatch, task derailment):

```python
import retrace

with retrace.agent("planner", role="planner"):
    plan = call_planner(prompt)
with retrace.agent("executor", role="executor"):
    result = call_executor(plan)
```

## Golden Cassettes (CI Regression Gates)

Record a run as a golden cassette and gate on it offline in CI with `retrace ci replay`:

```python
from retrace import write_golden_cassette

write_golden_cassette("golden.json", recorder=rec)
```

## Sampling

```python
retrace.configure(api_key="rt_live_...", sample_rate=0.1)  # Record 10% of traces
```

## Changelog

### 0.13.0

- **Multi-agent context** — `retrace.agent(id, role=...)` context manager tags spans for topology + inter-agent detectors
- **Golden cassettes** — `write_golden_cassette(path, recorder=...)` records a run as a CI regression fixture
- **Pre-call enforcement gate** — local step/token/USD-per-run ceilings enforced offline; `RetraceEnforcementError` raised instead of silently skipping the call


- **Sessions** — `session_id` parameter in `TraceRecorder` to group multi-turn conversations
- **Multi-Agent** — `agent_id` field on `Span` for cross-agent tracing
- **Guardrail support** — SDK respects HALT commands from server-side guardrail policies

### 0.2.2

- Version sync with TypeScript SDK

### 0.6.0

- **Token ID capture** — Span dataclass now supports `token_ids` and `logprobs` fields for speculative decoding during replay
- **Serialization** — `to_dict()` includes token_ids/logprobs when present

### 0.2.1

- **Offline buffer** — stores up to 1000 messages when WebSocket disconnects, flushes on reconnect
- **Dedicated listener thread** — receives server 'resume' commands without needing active sends
- **Cascade replay** — `resumable=True` registers function for SDK-level re-execution
- **Fixed** — duplicate except block in transport, proper close() cleanup

### 0.2.0

- Typed errors (RetraceAuthError, RetraceCreditsExhaustedError, RetraceRateLimitError)
- Trace sampling via `sample_rate` config
- Auto-instrumentation for OpenAI, Anthropic, Gemini
- WebSocket transport with auto-reconnect

## Links

- [Documentation](https://retrace.yashbogam.me/docs)
- [GitHub](https://github.com/yash1511-bogam/retrace)
- [PyPI](https://pypi.org/project/retrace-sdk/)
