Metadata-Version: 2.4
Name: ag2tracer
Version: 0.1.1
Summary: Failure attribution on multi-agent traces
Project-URL: Homepage, https://github.com/ag2tracer/ag2tracer
Project-URL: Repository, https://github.com/ag2tracer/ag2tracer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: litellm>=1.0.0

# ag2tracer

Failure attribution on multi-agent traces. Given a conversation trace from a multi-agent system, `ag2tracer` identifies **which agent** made the decisive error and **at which step**.

## Installation

```bash
pip install ag2tracer
```

## Setup

Set at least one API key:

```bash
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"   # optional
export GOOGLE_API_KEY="your-google-key"          # optional
```

## Web Interface

```bash
# Launch the web UI
ag2tracer launch

# Or run in background
ag2tracer launch --daemon

# Other commands
ag2tracer status    # check if server is running
ag2tracer logs      # view server logs
ag2tracer logs -f   # follow logs
ag2tracer stop      # stop the background server
```

Then open http://127.0.0.1:8500 to:

1. Upload a trace JSON file (must contain a `history` field)
2. Browse the conversation with a sliding-window viewer
3. Select an attribution method and click **Start**
4. View the failure-responsible agent and decisive error step

## Python API

```python
import json
from ag2tracer import all_at_once, step_by_step, binary_search

with open("trace.json") as f:
    trace = json.load(f)

# Choose a method
result = all_at_once(trace, model="gpt-4o")
# result = step_by_step(trace, model="gpt-4o")
# result = binary_search(trace, model="gpt-4o")

print(f"Agent: {result.agent_name}")
print(f"Step:  {result.step_number}")
print(f"Reason: {result.reason}")
```

## Trace Format

A trace is a JSON object with a required `history` array:

```json
{
  "history": [
    {"role": "assistant", "name": "Excel_Expert", "content": "..."},
    {"role": "user", "name": "Computer_terminal", "content": "..."},
    ...
  ],
  "question": "optional problem description",
  "ground_truth": "optional expected answer"
}
```

## Attribution Methods

| Method | Description | LLM Calls |
|--------|-------------|-----------|
| **All-at-Once** | Feeds entire conversation to the LLM | 1 |
| **Step-by-Step** | Evaluates each step sequentially, stops at first error | Up to N |
| **Binary Search** | Recursively narrows down the error location | O(log N) |

## License

MIT
