Metadata-Version: 2.4
Name: agentautopsy
Version: 1.9.0
Summary: Post-mortem debugger for AI agents
Author: Abhishek Patel
License: MIT
Project-URL: Homepage, https://github.com/Abhisekhpatel/AgentAutopsy
Keywords: ai-agents,debugging,llm,observability
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai
Requires-Dist: anthropic
Requires-Dist: sqlite-utils
Requires-Dist: sqlite-vec
Requires-Dist: httpx
Requires-Dist: requests
Dynamic: license-file

# AgentAutopsy

**Post-mortem debugger for AI agents — when your agent fails, this tells you exactly why.**

[![AgentAutopsy CI](https://github.com/Abhisekhpatel/AgentAutopsy/actions/workflows/ci.yml/badge.svg)](https://github.com/Abhisekhpatel/AgentAutopsy/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/agentautopsy?color=blue)](https://pypi.org/project/agentautopsy/)
[![PyPI downloads](https://img.shields.io/pypi/dm/agentautopsy?color=green)](https://pypi.org/project/agentautopsy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

---

## Lifecycle

```
  ┌──────┐    ┌────────┐    ┌───────┐    ┌──────────┐    ┌─────┐    ┌─────────┐
  │ Fail │───▶│ Detect │───▶│ Trace │───▶│ Diagnose │───▶│ Fix │───▶│ Prevent │
  └──────┘    └────────┘    └───────┘    └──────────┘    └─────┘    └─────────┘
     │             │              │              │            │             │
  Agent        Pinpoint       Full SQLite     AI root      Auto-fix      Fix cache
  crashes      failure        event log       cause +      + replay      + drift
               step           locally         patch        verify        alerts
```

---

## Commands

| Command | What it does |
|---------|--------------|
| `agentautopsy ui` | Open visual debugger |
| `agentautopsy fix <id>` | Auto-fix a failure |
| `agentautopsy runs` | List all runs |
| `agentautopsy replay <id>` | Print full event report for a run |
| `agentautopsy mcp <cmd...>` | Proxy and trace an MCP server over stdio |
| `agentautopsy stats` | Show fix-cache and token stats |
| `agentautopsy serve` | Start HTTP API (`POST /analyze`) |

---

## Features

| Feature | What It Does | Use When |
|---------|--------------|----------|
| Zero-config watch | One import instruments LLM + HTTP calls | Adding tracing to existing agents |
| LLM interceptor | Records every OpenAI / Anthropic prompt and response | Debugging model behavior |
| HTTP interceptor | Captures failed outbound HTTP (`http_error` events) | Connection / API failures |
| SQLite trace store | Persists full decision traces in `agentautopsy.db` | Offline post-mortems |
| Failure detection | Finds the exact failing step in a run | Any agent crash |
| Root-cause analysis | AI diagnosis + concrete fix (Anthropic) | You need a fix, not just a stack trace |
| Fix cache | Remembers verified fixes for instant replay | Repeat failures |
| Auto-fix | Applies patch suggestions to your codebase | Turning diagnosis into code |
| Replay | Step through failed runs in CLI or UI | Understanding what went wrong |
| Web UI | Timeline, stats, debug chat | Visual debugging |
| MCP tracing | Proxy + schema drift / mismatch reports | MCP server or tool-call failures |
| Prompt diffing | Compares prompts vs. previous run | Silent behavior changes |
| Divergence detection | Flags runs that differ from past successes | Flaky or drifting agents |
| Multi-agent graph | Parent/child run chains (`agentautopsy agents`) | Crews and agent pipelines |
| GitHub Actions | Posts root cause + fix on PR test failures | CI/CD workflows |
| Slack alerts | Notifies channel on failure (`AGENTAUTOPSY_SLACK_WEBHOOK`) | Team visibility |

---

## Framework Support

| Framework | Support Level |
|-----------|---------------|
| OpenAI | Native — auto-intercepted |
| Anthropic | Native — auto-intercepted |
| HTTP / httpx | Native — auto-intercepted |
| LangChain | Callback handler — `get_callback_handler()` |
| LangGraph | Callback handler — `get_langgraph_handler()` |
| CrewAI | Callback handler — `get_crewai_handler()` |
| MCP | Proxy CLI + `watch_mcp()` post-mortem tracing |
| Any OpenAI/Anthropic client | Works with zero config via `watch()` |

---

## Quick Start

**1. Install**

```bash
pip install agentautopsy
```

**2. Instrument your agent**

```python
import agentautopsy

agentautopsy.watch()
# your existing agent code — nothing else changes
```

**3. Debug failures**

```bash
agentautopsy runs                  # find the run id
agentautopsy replay <run_id>       # see the full trace
agentautopsy ui                    # open the visual debugger
```

---

## License

MIT — see [LICENSE](LICENSE).
