Metadata-Version: 2.3
Name: traceweave
Version: 0.1.2
Summary: Distributed tracing and observability for AI agents. Datadog for AI Agents.
Project-URL: Homepage, https://github.com/traceweave/traceweave
Project-URL: Documentation, https://github.com/traceweave/traceweave#readme
Project-URL: Repository, https://github.com/traceweave/traceweave
Project-URL: Issues, https://github.com/traceweave/traceweave/issues
Project-URL: Changelog, https://github.com/traceweave/traceweave/blob/main/CHANGELOG.md
Author: traceweave contributors
License: MIT
License-File: LICENSE
Keywords: agents,ai,distributed-tracing,llm,monitoring,observability,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: orjson>=3.9
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.40
Requires-Dist: websockets>=12.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18; extra == 'all'
Requires-Dist: crewai>=0.1.0; extra == 'all'
Requires-Dist: langchain-core>=0.1.0; extra == 'all'
Requires-Dist: langchain>=0.1.0; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Requires-Dist: pyautogen>=0.2.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18; extra == 'anthropic'
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == 'autogen'
Provides-Extra: crewai
Requires-Dist: crewai>=0.1.0; extra == 'crewai'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
Requires-Dist: langchain>=0.1.0; extra == 'langchain'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

<div align="center">

# 🔍 traceweave

### Distributed Tracing & Observability for AI Agents

**See exactly what your AI agents are doing. Debug multi-agent systems like a pro.**

[![PyPI version](https://img.shields.io/pypi/v/traceweave.svg)](https://pypi.org/project/traceweave/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/traceweave.svg)](https://pypi.org/project/traceweave/)

**English** | [简体中文](README_CN.md) | [日本語](README_JA.md) | [한국어](README_KO.md) | [Español](README_ES.md)

[Quick Start](#-quick-start) · [Features](#-features) · [Integrations](#-integrations) · [Dashboard](#-dashboard) · [Examples](#-examples)

</div>

---

> **Think of it as Datadog for AI Agents.** Trace every agent decision, tool call, and LLM interaction with beautiful visualizations and zero-config instrumentation.

```
📍 Trace: multi-agent-research  id=a3f2c1d8...
├── ✅ 🔗 multi-agent-research           ██████████████████████░░ 12.3s   tokens: 8.2k   cost: $0.15
│   ├── ✅ 🤖 planner                    ████████░░░░░░░░░░░░░░  3.2s    tokens: 2.1k   cost: $0.04
│   │   └── ✅ 🧠 plan-generation        ██████░░░░░░░░░░░░░░░░  2.1s    tokens: 1.8k   cost: $0.03
│   ├── ✅ 🤖 researcher                 ████████████░░░░░░░░░░  5.1s    tokens: 3.4k   cost: $0.06
│   │   ├── ✅ 🔧 web-search             ██░░░░░░░░░░░░░░░░░░░░  0.6s    tokens: -      cost: -
│   │   ├── ✅ 🔧 arxiv-search           █░░░░░░░░░░░░░░░░░░░░░  0.3s    tokens: -      cost: -
│   │   └── ✅ 🧠 analyze-results        ████████░░░░░░░░░░░░░░  3.1s    tokens: 2.8k   cost: $0.05
│   ├── ✅ 🤖 writer                     ██████████░░░░░░░░░░░░  4.8s    tokens: 1.9k   cost: $0.04
│   │   └── ✅ 🧠 write-report           ██████████░░░░░░░░░░░░  4.2s    tokens: 1.9k   cost: $0.04
│   └── ✅ 🤖 reviewer                   ██████░░░░░░░░░░░░░░░░  2.4s    tokens: 0.8k   cost: $0.01
│       └── ✅ 🧠 review-report          ██████░░░░░░░░░░░░░░░░  2.1s    tokens: 0.8k   cost: $0.01
╰── Summary ─────────────────────────────────────────────────────
    ⏱  Duration: 12.3s │ 🔢 Spans: 11 │ 📊 Tokens: 8.2k │ 💰 Cost: $0.15
```

## Why traceweave?

Building with AI agents? You've probably experienced:

- 🤯 **"Why did my agent do that?"** — No visibility into agent reasoning chains
- 💸 **"Where are my tokens going?"** — Can't track costs across nested agent calls
- 🐛 **"Which step failed?"** — Debugging multi-agent pipelines is a nightmare
- 📊 **"How long does each step take?"** — No performance profiling for agents

**traceweave solves all of this with 2 lines of code.**

## 🚀 Quick Start

```bash
pip install traceweave
```

```python
from agent_trace import tracer, trace_agent, trace_tool
from agent_trace.dashboard.tui import print_trace

@trace_tool("calculator")
def add(a: int, b: int) -> int:
    return a + b

@trace_agent("math-agent")
def math_agent(question: str) -> int:
    return add(2, 3)

# Trace everything
with tracer.start_trace("math-task"):
    answer = math_agent("What is 2 + 3?")

# Visualize
print_trace(tracer.get_all_traces()[-1])
```

## ✨ Features

### 🎯 Zero-Config Auto-Instrumentation

Automatically trace OpenAI, Anthropic, and LangChain with a single line:

```python
from agent_trace.integrations import instrument_all
instrument_all()  # That's it! All LLM calls are now traced.
```

### 🤖 Elegant Decorators

```python
@trace_agent("researcher")    # Trace agent functions
@trace_tool("web-search")     # Trace tool calls
@trace_llm(model="gpt-4")     # Trace LLM calls with token tracking
```

### 📊 Token & Cost Tracking

Automatic token counting and cost estimation for all major models:

```python
with tracer.start_span("my-llm-call", SpanKind.LLM) as span:
    response = call_llm(prompt)
    span.set_token_usage(
        prompt_tokens=1500,
        completion_tokens=500,
        model="claude-3-sonnet",
        prompt_cost_per_1k=0.003,
        completion_cost_per_1k=0.015,
    )
```

### 🖥️ Beautiful Terminal Dashboard

```bash
traceweave tui  # Live-updating terminal dashboard
```

### 🌐 Web Dashboard

```bash
traceweave dashboard  # Opens at http://localhost:8420
```

Dark-themed, real-time web dashboard with:
- Interactive trace tree visualization
- Token usage analytics
- Cost breakdown per agent/tool
- Timeline waterfall view

### 📤 Export Anywhere

```python
from agent_trace.exporters import export_json, export_chrome

# Save as JSON
export_json(trace, "my-trace.json")

# Export to Chrome DevTools format (open in chrome://tracing)
export_chrome(trace, "my-trace.chrome.json")
```

## 🔌 Integrations

### OpenAI

```python
from agent_trace.integrations.openai_integration import instrument_openai
instrument_openai()

# All OpenAI calls are now traced automatically!
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### Anthropic

```python
from agent_trace.integrations.anthropic_integration import instrument_anthropic
instrument_anthropic()

# All Anthropic calls are now traced!
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    messages=[{"role": "user", "content": "Hello!"}]
)
```

### LangChain

```python
from agent_trace.integrations.langchain_integration import AgentTraceCallbackHandler

handler = AgentTraceCallbackHandler()
chain = prompt | llm | output_parser
chain.invoke({"input": "..."}, config={"callbacks": [handler]})
```

## 📁 Examples

| Example | Description |
|---------|-------------|
| [Simple Demo](examples/simple_demo.py) | Minimal example — trace in 10 lines |
| [Multi-Agent Research](examples/multi_agent_demo.py) | 4-agent team with tools, LLM calls, and cost tracking |

Run the built-in demo:

```bash
traceweave demo
```

## 🏗️ Architecture

```
traceweave/
├── agent_trace/
│   ├── core/           # Core tracing engine
│   │   ├── models.py   # Pydantic data models (Span, Trace, TokenUsage)
│   │   ├── tracer.py   # Main tracer with context management
│   │   ├── span.py     # Span context manager
│   │   ├── context.py  # Thread-safe context propagation
│   │   └── decorators.py # @trace_agent, @trace_tool, @trace_llm
│   ├── integrations/   # Framework auto-instrumentation
│   │   ├── openai_integration.py
│   │   ├── anthropic_integration.py
│   │   └── langchain_integration.py
│   ├── dashboard/      # Visualization
│   │   ├── tui.py      # Rich terminal dashboard
│   │   └── server.py   # Web dashboard (single HTML, no build step)
│   ├── exporters/      # Export formats
│   │   ├── json_exporter.py
│   │   └── chrome_exporter.py
│   └── cli.py          # CLI commands
└── examples/           # Demo scripts
```

## 🔑 Key Concepts

| Concept | Description |
|---------|-------------|
| **Trace** | A complete operation (e.g., "research task"). Contains a tree of spans. |
| **Span** | A single unit of work (agent call, tool use, LLM request). |
| **SpanKind** | Type of span: `AGENT`, `TOOL`, `LLM`, `CHAIN`, `RETRIEVER` |
| **TokenUsage** | Token counts + cost estimation per LLM call |

## 📦 Installation

```bash
# Core only
pip install traceweave

# With specific integrations
pip install traceweave[openai]
pip install traceweave[anthropic]
pip install traceweave[langchain]

# Everything
pip install traceweave[all]
```

**Requirements:** Python 3.9+

## 🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

<div align="center">

**Built with ❤️ for the AI agent community**

If you find traceweave useful, please ⭐ star the repo!

</div>
