🧵 Trazo

Universal Execution Tracer & Semantic Diff Engine for LLM Agent Pipelines.

Know exactly why your agent did what it did — and how it changed.

Quickstart • Key Features • CLI Reference • Architecture • Contributing

🧐 What is Trazo?

Building LLM agents is easy. Debugging them is hard. When your pipeline behavior shifts, Trazo tells you why.

Trazo is a local-first, zero-dependency tracing library that captures every step of your agent's execution, tracks costs, and allows you to semantically diff two runs to see exactly what changed in your prompts, models, or outputs.

Before Trazo:

• print(response) spam in your terminal.
• Grepping through 100MB log files.
• Re-running expensive pipelines just to see a single intermediate output.
• Paying $$$ for cloud observability tools just to debug a local script.

After Trazo:

• 🔍 Visual DAGs: See your pipeline execution as a beautiful tree.
• 🔀 Semantic Diffs: Instant comparison of two runs with similarity scores.
• ⏮️ Time-Travel Replay: Re-run any specific step with original inputs.
• 💰 Cost Tracking: Automated token counting and USD cost estimation.
• 🔒 100% Local: No data ever leaves your machine. SQLite powered.

🚀 Quickstart

1. Install

pip install "trazo[ui]"

2. Instrument in 3 Lines

import trazo as tz

tz.init()  # Initialize storage
tz.instrument_ollama()  # Auto-instrument local models

@tz.trace  # Trace any function
def my_agent_step(query: str):
    # Your logic here...
    return "Result"

with tz.run("my_first_trace"):
    my_agent_step("How does transformers work?")

3. See the Magic

trazo view       # List recent runs
trazo ui         # Launch the visual DAG viewer at http://localhost:7432

✨ Key Features

🔍 Automatic Instrumentation

Just call tz.instrument_openai() or tz.instrument_ollama() at the top of your script. Trazo handles the rest—capturing inputs, outputs, tokens, and latency without touching your code.

🔀 Semantic Diff Engine

Compare two versions of your pipeline. Trazo matches spans by name and calculates a similarity score using lightweight n-gram hashing (no ML needed) or real embeddings (optional).

trazo diff [baseline_id] [current_id]

⏮️ Time-Travel Debugging

Spotted a failure in a complex chain? Use trazo replay [span_id] to re-execute just that specific step with the exact same inputs, or override them to test a fix.

📊 Rich Terminal UI

No browser? No problem. Trazo provides a high-fidelity terminal interface using rich for inspecting traces, diffs, and logs directly in your shell.

🛠️ CLI Reference

🏗️ Architecture

Trazo is designed to be non-blocking and local-first.

graph TD
    A[Your Agent Code] -->|Event| B(TraceCollector)
    B -->|Background Thread| C[SQLite WAL Mode]
    C --> D[CLI Interface]
    C --> E[Web UI Dashboard]
    F[OpenAI / Ollama] -.->|Auto-patch| A

• Storage: SQLite with WAL mode for high concurrency.
• Context: contextvars ensures correct parent-child linking even in complex async/await flows.
• Performance: The background flush worker ensures tracing overhead is negligible (< 1ms).

🏆 Why Trazo?

🤝 Contributing

We love contributors! Whether it's fixing a bug, adding a new integration (Anthropic, Gemini, etc.), or improving the UI.

1. Fork the repo.
2. pip install -e ".[dev,ui]"
3. Create your feature branch.
4. Open a Pull Request.

Check out our Contributing Guide for more details.

🗺️ Roadmap

• Core Tracing & SQLite Storage
• Semantic Diff CLI
• Interactive DAG Viewer
• OpenAI & Ollama Integrations
• Anthropic & Google Gemini Integration (Coming Soon)
• GitHub Actions Integration: Fail PRs if semantic similarity drops!
• MCP Server Support: Chat with your traces in Claude Desktop.