traceloop-local 0.1.0

A lightweight local AI agent execution recorder and replayer.

Traceloop

A lightweight Python developer tool for local AI agent execution recording and timeline replaying.

Traceloop wraps any AI agent workflow to automatically capture every step, context handoff, tool call, and failure, allowing you to browse and replay failed runs locally.

Features

• Pure Python: Minimal dependencies (flask, click, rich).
• Framework Agnostic: Works with arbitrary Python code, LangChain, raw OpenAI calls, or custom agents.
• Local JSON Storage: Runs are saved as plain JSON to ~/.traceloop/runs/. No cloud accounts or API keys required.
• CLI & Web UI: Browse run timelines in your terminal or via a local web dashboard.
• Replay Capability: Step-level checkpoints allow you to inject saved inputs and re-run localized failures.

Installation

git clone https://github.com/yourusername/traceloop-python.git
cd traceloop-python
pip install -e .

Quick Start

1. Instrument your Agent

Use the @tracer.run() and tracer.step() decorators to wrap your logic.

from traceloop import tracer
import time

@tracer.run()
def my_agent(query):
    with tracer.step("web_search", query=query) as step:
        # Simulate work
        time.sleep(0.3)
        results = ["Result 1", "Result 2"]
        step["outputs"] = {"results": results}
        
    with tracer.step("summarize", context=results) as step:
        # Simulate a crash
        raise Exception("API Rate Limit Exceeded")

if __name__ == "__main__":
    try:
        my_agent("What is the capital of France?")
    except Exception:
        pass

2. View Runs (CLI)

Listrecent runs:

traceloop list

Show a specific run timeline (with execution durations and error tracebacks):

traceloop show <run_id>

3. Web Dashboard

Launch the local timeline viewer UI:

traceloop ui

Then navigate to http://localhost:5000 to interactively expand steps and view full input/output JSON payloads.

4. Replay from Checkpoint

In a real environment, you can re-inject inputs to debug a specific failing step:

traceloop replay <run_id> --from-step 2