agent-autopsy 0.1.0__tar.gz

agent_autopsy-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg
+.eggs/
+htmlcov/
+.coverage

agent_autopsy-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [0.1.0] - 2026-03-05
+
+### Added
+- `Autopsy` context manager for zero-config error tracing
+- `AutopsyLangChainHandler` for automatic LangChain event capture
+- CLI tool (`autopsy view`) with terminal tree rendering and ANSI colors
+- JSON trace file format with timestamps, durations, and error details
+- Thread-safe trace capture
+- 40 comprehensive tests

agent_autopsy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aegis Ledger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_autopsy-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+recursive-include tests *.py *.json

agent_autopsy-0.1.0/MARKETING.md

@@ -0,0 +1,107 @@
+# agent-autopsy Marketing Plan
+
+## Awesome Lists
+
+### awesome-langchain
+
+**PR Title:** Add agent-autopsy -- debug tool for LangChain agent traces
+
+**Category:** Tools / Debugging
+
+**Entry:**
+```markdown
+- [agent-autopsy](https://github.com/VladislavRoss/agent-autopsy-sdk) - Debug tool that captures and visualizes LangChain agent execution traces with timeline, tool calls, and decision reasoning.
+```
+
+**Checklist before PR:**
+- [ ] Package on PyPI
+- [ ] README with usage examples
+- [ ] At least 30 GitHub stars (soft requirement)
+- [ ] Working demo/screenshot
+
+### awesome-python
+
+**PR Title:** Add agent-autopsy to Debugging Tools
+
+**Category:** Debugging Tools
+
+**Entry:**
+```markdown
+- [agent-autopsy](https://github.com/VladislavRoss/agent-autopsy-sdk) - Execution trace debugger for AI agents (LangChain, CrewAI, OpenAI Agents SDK).
+```
+
+---
+
+## Reddit Strategy
+
+### r/LangChain
+
+**Post Title:** "I built a free debugging tool for LangChain agents -- agent-autopsy"
+
+**Body:**
+- Problem: debugging multi-step agents is painful (print statements, manual logging)
+- Solution: drop-in callback handler that captures the full execution trace
+- Show: timeline visualization, tool call details, decision reasoning
+- Free, MIT licensed, pip install agent-autopsy
+- Upgrade path: for tamperproof traces, there's aegis-ledger-sdk (link in footer)
+
+**Rules:** No hard sell. Genuine value first. Mention Aegis only in context of upgrade.
+
+### r/MachineLearning
+
+**Post Title:** "[P] agent-autopsy: Execution trace debugger for AI agents"
+
+**Body:** Focus on the debugging problem. Technical audience. Link to GitHub.
+
+---
+
+## Discord Communities
+
+| Community | Channel | Approach |
+|-----------|---------|----------|
+| LangChain Discord | #showcase | Share with demo |
+| CrewAI Discord | #showcase | Integration example |
+| AI Engineer Discord | #tools | Technical deep-dive |
+
+**Rule:** Always provide genuine value. Never spam. Answer questions. Be helpful.
+
+---
+
+## Growth Funnel
+
+```
+agent-autopsy (free, OSS)
+    |
+    | Footer: "For tamperproof traces: aegis-ledger.com"
+    | upgrade_code: "from aegis.langchain import AegisCallbackHandler"
+    |
+    v
+aegis-ledger-sdk (freemium)
+    |
+    | 10k free events/month
+    | Pro: CHF 39/mo (500k events)
+    | Business: CHF 149/mo (5M events)
+    |
+    v
+Enterprise (custom)
+```
+
+## PyPI Publication
+
+**Package name:** `agent-autopsy`
+
+**Steps:**
+1. Ensure all 40 tests pass
+2. Update version in pyproject.toml
+3. `hatch build && hatch publish`
+4. Verify: `pip install agent-autopsy`
+
+## Success Metrics (First 30 Days)
+
+| Metric | Target |
+|--------|--------|
+| PyPI installs | 200+ |
+| GitHub stars | 25+ |
+| Reddit post upvotes | 20+ |
+| awesome-langchain PR merged | Yes |
+| Users clicking upgrade link | 10+ |

agent_autopsy-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: agent-autopsy
+Version: 0.1.0
+Summary: Debug AI agent failures with zero-config execution traces
+Project-URL: Homepage, https://github.com/VladislavRoss/agent-autopsy-sdk
+Project-URL: Documentation, https://github.com/VladislavRoss/agent-autopsy-sdk#readme
+Project-URL: Production Tracing, https://www.aegis-ledger.com
+Author-email: Aegis Ledger <info@aegis-ledger.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,debugging,langchain,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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# agent-autopsy
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**Zero-dependency post-mortem traces for AI agent failures.**
+
+Wrap your agent code in a single context manager. On success, nothing happens.
+On error, a detailed JSON trace file is written automatically -- ready for
+debugging, sharing, or replaying.
+
+```
++======================================================+
+|  AGENT AUTOPSY -- sess_a7f3b2c                       |
+|  2026-03-05 14:32:01 -> 14:32:08 (7.2s)              |
++======================================================+
+|                                                      |
+|  |- [tool_call] search_orders ........... v 340ms    |
+|  |- [llm_call] gpt-4o .................. v 1.2s      |
+|  |- [tool_call] stripe.create_refund .... x 89ms     |
+|  |   +-- ERROR: Card declined                        |
+|  +- [error] Unhandled exception ......... x 0ms      |
+|      +-- ValueError: amount must be positive         |
+|                                                      |
++======================================================+
+    For tamperproof traces: https://www.aegis-ledger.com
+```
+
+## Install
+
+```bash
+pip install agent-autopsy
+```
+
+For LangChain integration:
+
+```bash
+pip install agent-autopsy[langchain]
+```
+
+## Usage
+
+### 1. Basic -- wrap any agent code
+
+```python
+from agent_autopsy import Autopsy
+
+with Autopsy() as trace:
+    trace.log("tool_call", "search_web", input="refund policy", duration_ms=340)
+    trace.log("llm_call", "gpt-4o", input="Summarise results", duration_ms=1200)
+    # If an exception occurs here, a JSON trace file is written automatically.
+    result = my_agent.invoke({"input": "Process refund for order #9281"})
+
+# Success -> nothing written (silent)
+# Error   -> ./autopsy_sess_<hash>.json created
+```
+
+### 2. With LangChain -- automatic event capture
+
+```python
+from agent_autopsy import Autopsy
+from agent_autopsy.langchain_handler import AutopsyLangChainHandler
+
+handler = AutopsyLangChainHandler()
+
+with Autopsy(handler=handler) as trace:
+    chain.invoke(
+        {"input": "Process refunds"},
+        config={"callbacks": [handler]},
+    )
+# All LLM calls, tool calls, and chain steps are captured automatically.
+# On error, everything is written to a single JSON file.
+```
+
+### 3. CLI -- view a trace file
+
+```bash
+# Pretty-printed terminal tree (with colours)
+autopsy view autopsy_sess_a7f3b2c.json
+
+# Raw JSON output
+autopsy view autopsy_sess_a7f3b2c.json --raw
+```
+
+## How it works
+
+1. `Autopsy()` creates a trace session with a unique ID
+2. During the `with` block, call `trace.log()` to record events (or use the
+   LangChain handler for automatic capture)
+3. On `__exit__`:
+   - **No exception** -- session is discarded, no file written, zero overhead
+   - **Exception** -- session + full traceback are written to a JSON file
+
+Every JSON file includes all captured events with timestamps, durations,
+input/output previews, and error messages.
+
+## JSON output format
+
+```json
+{
+  "session_id": "a7f3b2c",
+  "start_time": "2026-03-05T14:32:01.000000+00:00",
+  "end_time": "2026-03-05T14:32:08.200000+00:00",
+  "error": "Traceback (most recent call last): ...",
+  "entries": [
+    {
+      "timestamp": "2026-03-05T14:32:01.500000+00:00",
+      "type": "tool_call",
+      "name": "search_orders",
+      "input_preview": "{\"order_id\": \"9281\"}",
+      "output_preview": "{\"order\": {\"id\": 9281}}",
+      "duration_ms": 340,
+      "status": "ok"
+    }
+  ],
+  "_aegis_footer": {
+    "message": "For tamperproof, legally defensible traces: https://www.aegis-ledger.com",
+    "upgrade": "pip install aegis-ledger-sdk[langchain]"
+  }
+}
+```
+
+## Going to Production?
+
+`agent-autopsy` is a **debugging tool** for local development. When you need
+tamperproof, hash-chained, cryptographically signed traces for production --
+upgrade to the full **Aegis Ledger SDK**:
+
+```bash
+pip install aegis-ledger-sdk[langchain]
+```
+
+```python
+# 2 lines to upgrade from agent-autopsy to production tracing:
+from aegis.langchain import AegisCallbackHandler
+handler = AegisCallbackHandler(api_key="your-key")
+```
+
+Every trace is hash-chained (SHA-256) and signed (Ed25519) on the Internet
+Computer blockchain. Immutable. Auditable. Legally defensible.
+
+Learn more at [aegis-ledger.com](https://www.aegis-ledger.com).
+
+## License
+
+MIT

agent_autopsy-0.1.0/README.md

@@ -0,0 +1,146 @@
+# agent-autopsy
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**Zero-dependency post-mortem traces for AI agent failures.**
+
+Wrap your agent code in a single context manager. On success, nothing happens.
+On error, a detailed JSON trace file is written automatically -- ready for
+debugging, sharing, or replaying.
+
+```
++======================================================+
+|  AGENT AUTOPSY -- sess_a7f3b2c                       |
+|  2026-03-05 14:32:01 -> 14:32:08 (7.2s)              |
++======================================================+
+|                                                      |
+|  |- [tool_call] search_orders ........... v 340ms    |
+|  |- [llm_call] gpt-4o .................. v 1.2s      |
+|  |- [tool_call] stripe.create_refund .... x 89ms     |
+|  |   +-- ERROR: Card declined                        |
+|  +- [error] Unhandled exception ......... x 0ms      |
+|      +-- ValueError: amount must be positive         |
+|                                                      |
++======================================================+
+    For tamperproof traces: https://www.aegis-ledger.com
+```
+
+## Install
+
+```bash
+pip install agent-autopsy
+```
+
+For LangChain integration:
+
+```bash
+pip install agent-autopsy[langchain]
+```
+
+## Usage
+
+### 1. Basic -- wrap any agent code
+
+```python
+from agent_autopsy import Autopsy
+
+with Autopsy() as trace:
+    trace.log("tool_call", "search_web", input="refund policy", duration_ms=340)
+    trace.log("llm_call", "gpt-4o", input="Summarise results", duration_ms=1200)
+    # If an exception occurs here, a JSON trace file is written automatically.
+    result = my_agent.invoke({"input": "Process refund for order #9281"})
+
+# Success -> nothing written (silent)
+# Error   -> ./autopsy_sess_<hash>.json created
+```
+
+### 2. With LangChain -- automatic event capture
+
+```python
+from agent_autopsy import Autopsy
+from agent_autopsy.langchain_handler import AutopsyLangChainHandler
+
+handler = AutopsyLangChainHandler()
+
+with Autopsy(handler=handler) as trace:
+    chain.invoke(
+        {"input": "Process refunds"},
+        config={"callbacks": [handler]},
+    )
+# All LLM calls, tool calls, and chain steps are captured automatically.
+# On error, everything is written to a single JSON file.
+```
+
+### 3. CLI -- view a trace file
+
+```bash
+# Pretty-printed terminal tree (with colours)
+autopsy view autopsy_sess_a7f3b2c.json
+
+# Raw JSON output
+autopsy view autopsy_sess_a7f3b2c.json --raw
+```
+
+## How it works
+
+1. `Autopsy()` creates a trace session with a unique ID
+2. During the `with` block, call `trace.log()` to record events (or use the
+   LangChain handler for automatic capture)
+3. On `__exit__`:
+   - **No exception** -- session is discarded, no file written, zero overhead
+   - **Exception** -- session + full traceback are written to a JSON file
+
+Every JSON file includes all captured events with timestamps, durations,
+input/output previews, and error messages.
+
+## JSON output format
+
+```json
+{
+  "session_id": "a7f3b2c",
+  "start_time": "2026-03-05T14:32:01.000000+00:00",
+  "end_time": "2026-03-05T14:32:08.200000+00:00",
+  "error": "Traceback (most recent call last): ...",
+  "entries": [
+    {
+      "timestamp": "2026-03-05T14:32:01.500000+00:00",
+      "type": "tool_call",
+      "name": "search_orders",
+      "input_preview": "{\"order_id\": \"9281\"}",
+      "output_preview": "{\"order\": {\"id\": 9281}}",
+      "duration_ms": 340,
+      "status": "ok"
+    }
+  ],
+  "_aegis_footer": {
+    "message": "For tamperproof, legally defensible traces: https://www.aegis-ledger.com",
+    "upgrade": "pip install aegis-ledger-sdk[langchain]"
+  }
+}
+```
+
+## Going to Production?
+
+`agent-autopsy` is a **debugging tool** for local development. When you need
+tamperproof, hash-chained, cryptographically signed traces for production --
+upgrade to the full **Aegis Ledger SDK**:
+
+```bash
+pip install aegis-ledger-sdk[langchain]
+```
+
+```python
+# 2 lines to upgrade from agent-autopsy to production tracing:
+from aegis.langchain import AegisCallbackHandler
+handler = AegisCallbackHandler(api_key="your-key")
+```
+
+Every trace is hash-chained (SHA-256) and signed (Ed25519) on the Internet
+Computer blockchain. Immutable. Auditable. Legally defensible.
+
+Learn more at [aegis-ledger.com](https://www.aegis-ledger.com).
+
+## License
+
+MIT

agent_autopsy-0.1.0/agent_autopsy/__init__.py

@@ -0,0 +1,9 @@
+"""agent-autopsy -- Debug AI agent failures with zero-config execution traces."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from agent_autopsy.capture import Autopsy
+from agent_autopsy.models import TraceEntry, TraceSession
+
+__all__ = ["Autopsy", "TraceEntry", "TraceSession", "__version__"]

agent_autopsy-0.1.0/agent_autopsy/_footer.py

@@ -0,0 +1,12 @@
+"""Aegis footer — single source of truth for the upgrade nudge."""
+from __future__ import annotations
+
+AEGIS_FOOTER: dict[str, dict[str, str]] = {
+    "_aegis_footer": {
+        "message": "This trace is stored locally and can be modified. For tamperproof traces: https://www.aegis-ledger.com",
+        "upgrade": "pip install aegis-ledger-sdk[langchain]",
+        "upgrade_code": (
+            "from aegis.langchain import AegisCallbackHandler  # 2 lines to upgrade"
+        ),
+    }
+}

agent_autopsy-0.1.0/agent_autopsy/capture.py

@@ -0,0 +1,156 @@
+"""Context manager that buffers trace events and writes JSON on error."""
+from __future__ import annotations
+
+import json
+import re
+import sys
+import threading
+import traceback
+from datetime import datetime, timezone
+from pathlib import Path
+from types import TracebackType
+from typing import TYPE_CHECKING, Any
+
+from agent_autopsy._footer import AEGIS_FOOTER
+from agent_autopsy.models import EntryStatus, EntryType, TraceEntry, TraceSession
+
+if TYPE_CHECKING:
+    from agent_autopsy.langchain_handler import AutopsyLangChainHandler
+
+
+class Autopsy:
+    """Capture agent execution traces and write them to JSON on failure.
+
+    Usage::
+
+        with Autopsy() as trace:
+            trace.log("tool_call", "search_web", input="query", output="results", duration_ms=340)
+            agent.invoke({"input": "Process refunds"})
+        # On error  -> writes ./autopsy_sess_<hash>.json
+        # On success -> silently discarded
+
+    Parameters
+    ----------
+    output_dir:
+        Directory where trace files are written on error. Defaults to ``"."``.
+    prefix:
+        Filename prefix. The full name is ``<prefix>_sess_<session_id>.json``.
+    handler:
+        Optional :class:`AutopsyLangChainHandler` whose buffered entries will
+        be merged into this session on exit.
+    """
+
+    def __init__(
+        self,
+        output_dir: str | Path = ".",
+        prefix: str = "autopsy",
+        handler: AutopsyLangChainHandler | None = None,
+    ) -> None:
+        if not re.fullmatch(r"[a-zA-Z0-9_-]{1,32}", prefix):
+            raise ValueError(
+                f"prefix must be 1-32 alphanumeric/dash/underscore chars, got {prefix!r}"
+            )
+        self._output_dir = Path(output_dir)
+        self._prefix = prefix
+        self._handler = handler
+        self._session = TraceSession()
+        self._lock = threading.Lock()
+
+    # -- public API ----------------------------------------------------------
+
+    @property
+    def session(self) -> TraceSession:
+        """The current trace session."""
+        return self._session
+
+    def log(
+        self,
+        type: EntryType,  # noqa: A002 — shadows built-in on purpose for DX
+        name: str,
+        *,
+        input: str = "",  # noqa: A002
+        output: str = "",
+        duration_ms: float = 0.0,
+        status: EntryStatus = "ok",
+        error_message: str | None = None,
+    ) -> None:
+        """Append a trace entry (thread-safe)."""
+        entry = TraceEntry(
+            type=type,
+            name=name,
+            input_preview=input,
+            output_preview=output,
+            duration_ms=duration_ms,
+            status=status,
+            error_message=error_message,
+        )
+        with self._lock:
+            self._session.entries.append(entry)
+
+    # -- context manager -----------------------------------------------------
+
+    def __enter__(self) -> Autopsy:
+        self._session = TraceSession()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool:
+        self._session.end_time = datetime.now(timezone.utc).isoformat()
+
+        # Merge handler entries if present
+        if self._handler is not None:
+            with self._lock:
+                self._session.entries.extend(self._handler.entries)
+
+        if exc_type is None:
+            # Success — discard session, write nothing
+            return False
+
+        # Failure — record error and write JSON
+        self._session.error = "".join(
+            traceback.format_exception(exc_type, exc_val, exc_tb)
+        )
+
+        # Add an error entry for the unhandled exception
+        self.log(
+            "error",
+            "Unhandled exception",
+            status="error",
+            error_message=f"{exc_type.__name__}: {exc_val}" if exc_type else str(exc_val),
+        )
+
+        try:
+            self._write_json()
+        except Exception as write_err:
+            print(f"Warning: failed to write trace file: {write_err}", file=sys.stderr)
+        # Do NOT suppress the exception — let it propagate
+        return False
+
+    def on_text(self, text: str, *, name: str = "stream") -> None:
+        """Log a streaming text event (e.g. LLM token output).
+
+        This is a lightweight callback for streaming integrations.
+        Text events are logged as ``chain_step`` entries with the
+        output_preview set to the text content.
+        """
+        self.log("chain_step", name, output=text[:500])
+
+    # -- private -------------------------------------------------------------
+
+    def _build_payload(self) -> dict[str, Any]:
+        """Build the final JSON payload including the Aegis footer."""
+        payload: dict[str, Any] = self._session.to_dict()
+        payload.update(AEGIS_FOOTER)
+        return payload
+
+    def _write_json(self) -> None:
+        """Write the trace session to a JSON file."""
+        self._output_dir.mkdir(parents=True, exist_ok=True)
+        filename = f"{self._prefix}_sess_{self._session.session_id}.json"
+        filepath = self._output_dir / filename
+        payload = self._build_payload()
+        filepath.write_text(json.dumps(payload, indent=2, default=str), encoding="utf-8")