agenttrace-ai 0.1.1__tar.gz

agenttrace_ai-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentTrace Contributors
+
+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.

agenttrace_ai-0.1.1/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include agenttrace/static *

agenttrace_ai-0.1.1/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: agenttrace-ai
+Version: 0.1.1
+Summary: Zero-config local-first visual debugging and auto-evaluation for LLM agents.
+Author: AgentTrace Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/CURSED-ME/AgentTrace
+Project-URL: Issues, https://github.com/CURSED-ME/AgentTrace/issues
+Keywords: llm,agent,debugging,observability,opentelemetry,tracing
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.23.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Requires-Dist: opentelemetry-instrumentation-openai>=0.1.0; extra == "openai"
+Provides-Extra: judge
+Requires-Dist: groq>=0.9.0; extra == "judge"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == "langchain"
+Provides-Extra: all
+Requires-Dist: openai>=1.0.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-openai>=0.1.0; extra == "all"
+Requires-Dist: groq>=0.9.0; extra == "all"
+Requires-Dist: langchain-core>=0.2.0; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+
+# 🔍 AgentTrace
+
+**Zero-config visual debugging and auto-evaluation for LLM agents.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-native-blueviolet)](https://opentelemetry.io/)
+
+*One import. Zero config. Instant visual timeline of every LLM call, tool execution, and crash your agent makes.*
+
+</div>
+
+---
+
+## The Problem
+
+You build an AI agent. It calls an LLM, uses tools, chains prompts together. Then it hallucinates, loops infinitely, or silently drops context — and you have **no idea where it went wrong.**
+
+Every other observability tool requires accounts, API keys, cloud dashboards, and framework-specific setup. You just want to **see what happened.**
+
+## The Solution
+
+```python
+import agenttrace.auto  # ← That's it. One line.
+
+# ... your existing agent code runs normally ...
+# When it finishes, a local dashboard opens automatically at localhost:8000
+```
+
+AgentTrace intercepts every LLM call, tool execution, and unhandled crash — then serves a beautiful local timeline you can replay step-by-step.
+
+---
+
+## ✨ Features
+
+### 🪄 True Zero-Config
+Add `import agenttrace.auto` to the top of your script. No API keys, no accounts, no cloud. Works with **OpenAI**, **Groq**, **LangChain**, and **CrewAI** out of the box.
+
+### 🧠 Smart Auto-Judge
+AgentTrace doesn't just *show* you what happened — it *tells you what went wrong:*
+
+| Evaluation | How It Works | Cost |
+|---|---|---|
+| 🔁 **Loop Detection** | Flags 3+ identical consecutive tool calls | Free (pure Python) |
+| 💰 **Cost Anomaly** | Flags steps using >2x average tokens | Free (pure Python) |
+| ⏱️ **Latency Regression** | Flags steps >3x slower than average | Free (pure Python) |
+| 🔧 **Tool Misuse** | Detects wrong arguments or failed tool calls | LLM-powered (optional) |
+| 📝 **Instruction Drift** | Detects when LLM ignores the system prompt | LLM-powered (optional) |
+
+> LLM-powered checks require a free [Groq API key](https://console.groq.com). Install with `pip install "agenttrace-ai[judge]"`.
+
+### ▶️ Trace Replay
+Press **Play** and watch your agent's execution animate step-by-step — like a video recording of its thought process. Drag the scrubber to jump to any moment. Flagged steps pulse red.
+
+### 💥 Crash Detection
+If your agent throws an unhandled exception, AgentTrace catches it and logs the full traceback as a trace step — so you never lose debugging data.
+
+### 🔌 Framework Support
+| Framework | Status | Setup Required |
+|---|---|---|
+| OpenAI SDK | ✅ Native | `pip install "agenttrace-ai[openai]"` |
+| Groq SDK | ✅ Native | `pip install "agenttrace-ai[openai]"` |
+| LangChain | ✅ Adapter | None (auto-detected) |
+| CrewAI | ✅ Adapter | None (auto-detected) |
+
+---
+
+## 🚀 Quickstart
+
+### Install
+
+```bash
+# Core (works with LangChain out of the box)
+pip install agenttrace-ai
+
+# With OpenAI/Groq support
+pip install "agenttrace-ai[openai]"
+
+# With everything (OpenAI + Auto-Judge + LangChain)
+pip install "agenttrace-ai[all]"
+```
+
+### Basic Usage (OpenAI / Groq)
+
+```python
+import agenttrace.auto  # ← Add this one line
+import openai
+
+client = openai.OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "What is the capital of France?"}]
+)
+print(response.choices[0].message.content)
+# Dashboard opens automatically at http://localhost:8000 when your script finishes
+```
+
+### LangChain (Zero-Config)
+
+```python
+import agenttrace.auto  # ← Same one line
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+
+llm = ChatOpenAI(model="gpt-4")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant."),
+    ("human", "{input}")
+])
+
+chain = prompt | llm
+result = chain.invoke({"input": "Explain quantum computing"})
+# All LLM calls automatically appear in the AgentTrace dashboard
+```
+
+### Custom Tool Tracking
+
+```python
+from agenttrace import track_tool, track_agent
+
+@track_tool
+def search_database(query: str) -> str:
+    return db.search(query)
+
+@track_agent
+def my_agent(task: str) -> str:
+    data = search_database(task)
+    return llm.complete(f"Answer based on: {data}")
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+Your Agent Script
+       │
+       ▼
+  import agenttrace.auto
+       │
+       ├─── OpenTelemetry TracerProvider
+       │         │
+       │         ├── OpenAI Instrumentor (optional)
+       │         ├── LangChain Callback Adapter
+       │         └── CrewAI Callback Adapter
+       │         │
+       │         ▼
+       │    AgentTraceExporter → SQLite (.agenttrace.db)
+       │
+       ├─── sys.excepthook → Crash capture
+       │
+       └─── atexit → FastAPI Server (localhost:8000)
+                         │
+                         ├── /api/traces
+                         ├── /api/trace/{id}
+                         └── React Dashboard (Vite + Tailwind)
+```
+
+### Key Design Decisions
+- **OpenTelemetry** for instrumentation (industry standard, not fragile monkey-patching)
+- **SQLite with WAL mode** for zero-config persistence that survives crashes
+- **`contextvars`** for thread-safe multi-agent isolation
+- **Pre-compiled React UI** bundled inside the Python package
+
+---
+
+## 📁 Project Structure
+
+```
+agenttrace/
+├── auto.py              # Zero-config entry point (import this)
+├── exporter.py          # OTel SpanExporter → SQLite
+├── judge.py             # Smart Auto-Judge engine (5 eval types)
+├── models.py            # Pydantic data models
+├── storage.py           # SQLite with WAL mode
+├── server.py            # FastAPI dashboard server
+├── decorators.py        # @track_tool, @track_agent
+├── utils.py             # Payload truncation
+├── integrations/
+│   ├── langchain.py     # LangChain callback adapter
+│   └── crewai.py        # CrewAI callback adapter
+└── static/              # Pre-compiled React dashboard
+```
+
+---
+
+## ⚙️ Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `GROQ_API_KEY` | — | Required for LLM-powered judge evaluations |
+| `AGENTTRACE_DB_PATH` | `.agenttrace.db` | Custom database file path |
+| `AGENTTRACE_FULL_PAYLOAD` | `0` | Set to `1` to disable payload truncation |
+| `AGENTTRACE_MAX_CONTENT` | `500` | Max characters before truncation |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to set up the dev environment:
+
+```bash
+git clone https://github.com/CURSED-ME/AgentTrace.git
+cd AgentTrace
+pip install -e ".[all]"
+
+# Frontend development
+cd ui
+npm install
+npm run dev    # Dev server with hot reload
+npm run build  # Compile to agenttrace/static/
+```
+
+See [.env.example](.env.example) for required environment variables.
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Built with ❤️ for the agent builder community.**
+
+*If AgentTrace helped you debug an agent, give us a ⭐ on GitHub!*
+
+</div>

agenttrace_ai-0.1.1/README.md

@@ -0,0 +1,232 @@
+<div align="center">
+
+# 🔍 AgentTrace
+
+**Zero-config visual debugging and auto-evaluation for LLM agents.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-native-blueviolet)](https://opentelemetry.io/)
+
+*One import. Zero config. Instant visual timeline of every LLM call, tool execution, and crash your agent makes.*
+
+</div>
+
+---
+
+## The Problem
+
+You build an AI agent. It calls an LLM, uses tools, chains prompts together. Then it hallucinates, loops infinitely, or silently drops context — and you have **no idea where it went wrong.**
+
+Every other observability tool requires accounts, API keys, cloud dashboards, and framework-specific setup. You just want to **see what happened.**
+
+## The Solution
+
+```python
+import agenttrace.auto  # ← That's it. One line.
+
+# ... your existing agent code runs normally ...
+# When it finishes, a local dashboard opens automatically at localhost:8000
+```
+
+AgentTrace intercepts every LLM call, tool execution, and unhandled crash — then serves a beautiful local timeline you can replay step-by-step.
+
+---
+
+## ✨ Features
+
+### 🪄 True Zero-Config
+Add `import agenttrace.auto` to the top of your script. No API keys, no accounts, no cloud. Works with **OpenAI**, **Groq**, **LangChain**, and **CrewAI** out of the box.
+
+### 🧠 Smart Auto-Judge
+AgentTrace doesn't just *show* you what happened — it *tells you what went wrong:*
+
+| Evaluation | How It Works | Cost |
+|---|---|---|
+| 🔁 **Loop Detection** | Flags 3+ identical consecutive tool calls | Free (pure Python) |
+| 💰 **Cost Anomaly** | Flags steps using >2x average tokens | Free (pure Python) |
+| ⏱️ **Latency Regression** | Flags steps >3x slower than average | Free (pure Python) |
+| 🔧 **Tool Misuse** | Detects wrong arguments or failed tool calls | LLM-powered (optional) |
+| 📝 **Instruction Drift** | Detects when LLM ignores the system prompt | LLM-powered (optional) |
+
+> LLM-powered checks require a free [Groq API key](https://console.groq.com). Install with `pip install "agenttrace-ai[judge]"`.
+
+### ▶️ Trace Replay
+Press **Play** and watch your agent's execution animate step-by-step — like a video recording of its thought process. Drag the scrubber to jump to any moment. Flagged steps pulse red.
+
+### 💥 Crash Detection
+If your agent throws an unhandled exception, AgentTrace catches it and logs the full traceback as a trace step — so you never lose debugging data.
+
+### 🔌 Framework Support
+| Framework | Status | Setup Required |
+|---|---|---|
+| OpenAI SDK | ✅ Native | `pip install "agenttrace-ai[openai]"` |
+| Groq SDK | ✅ Native | `pip install "agenttrace-ai[openai]"` |
+| LangChain | ✅ Adapter | None (auto-detected) |
+| CrewAI | ✅ Adapter | None (auto-detected) |
+
+---
+
+## 🚀 Quickstart
+
+### Install
+
+```bash
+# Core (works with LangChain out of the box)
+pip install agenttrace-ai
+
+# With OpenAI/Groq support
+pip install "agenttrace-ai[openai]"
+
+# With everything (OpenAI + Auto-Judge + LangChain)
+pip install "agenttrace-ai[all]"
+```
+
+### Basic Usage (OpenAI / Groq)
+
+```python
+import agenttrace.auto  # ← Add this one line
+import openai
+
+client = openai.OpenAI()
+response = client.chat.completions.create(
+    model="gpt-4",
+    messages=[{"role": "user", "content": "What is the capital of France?"}]
+)
+print(response.choices[0].message.content)
+# Dashboard opens automatically at http://localhost:8000 when your script finishes
+```
+
+### LangChain (Zero-Config)
+
+```python
+import agenttrace.auto  # ← Same one line
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+
+llm = ChatOpenAI(model="gpt-4")
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful assistant."),
+    ("human", "{input}")
+])
+
+chain = prompt | llm
+result = chain.invoke({"input": "Explain quantum computing"})
+# All LLM calls automatically appear in the AgentTrace dashboard
+```
+
+### Custom Tool Tracking
+
+```python
+from agenttrace import track_tool, track_agent
+
+@track_tool
+def search_database(query: str) -> str:
+    return db.search(query)
+
+@track_agent
+def my_agent(task: str) -> str:
+    data = search_database(task)
+    return llm.complete(f"Answer based on: {data}")
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+Your Agent Script
+       │
+       ▼
+  import agenttrace.auto
+       │
+       ├─── OpenTelemetry TracerProvider
+       │         │
+       │         ├── OpenAI Instrumentor (optional)
+       │         ├── LangChain Callback Adapter
+       │         └── CrewAI Callback Adapter
+       │         │
+       │         ▼
+       │    AgentTraceExporter → SQLite (.agenttrace.db)
+       │
+       ├─── sys.excepthook → Crash capture
+       │
+       └─── atexit → FastAPI Server (localhost:8000)
+                         │
+                         ├── /api/traces
+                         ├── /api/trace/{id}
+                         └── React Dashboard (Vite + Tailwind)
+```
+
+### Key Design Decisions
+- **OpenTelemetry** for instrumentation (industry standard, not fragile monkey-patching)
+- **SQLite with WAL mode** for zero-config persistence that survives crashes
+- **`contextvars`** for thread-safe multi-agent isolation
+- **Pre-compiled React UI** bundled inside the Python package
+
+---
+
+## 📁 Project Structure
+
+```
+agenttrace/
+├── auto.py              # Zero-config entry point (import this)
+├── exporter.py          # OTel SpanExporter → SQLite
+├── judge.py             # Smart Auto-Judge engine (5 eval types)
+├── models.py            # Pydantic data models
+├── storage.py           # SQLite with WAL mode
+├── server.py            # FastAPI dashboard server
+├── decorators.py        # @track_tool, @track_agent
+├── utils.py             # Payload truncation
+├── integrations/
+│   ├── langchain.py     # LangChain callback adapter
+│   └── crewai.py        # CrewAI callback adapter
+└── static/              # Pre-compiled React dashboard
+```
+
+---
+
+## ⚙️ Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `GROQ_API_KEY` | — | Required for LLM-powered judge evaluations |
+| `AGENTTRACE_DB_PATH` | `.agenttrace.db` | Custom database file path |
+| `AGENTTRACE_FULL_PAYLOAD` | `0` | Set to `1` to disable payload truncation |
+| `AGENTTRACE_MAX_CONTENT` | `500` | Max characters before truncation |
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! Here's how to set up the dev environment:
+
+```bash
+git clone https://github.com/CURSED-ME/AgentTrace.git
+cd AgentTrace
+pip install -e ".[all]"
+
+# Frontend development
+cd ui
+npm install
+npm run dev    # Dev server with hot reload
+npm run build  # Compile to agenttrace/static/
+```
+
+See [.env.example](.env.example) for required environment variables.
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+
+**Built with ❤️ for the agent builder community.**
+
+*If AgentTrace helped you debug an agent, give us a ⭐ on GitHub!*
+
+</div>

agenttrace_ai-0.1.1/agenttrace/__init__.py

@@ -0,0 +1,4 @@
+from .decorators import track_tool, track_agent
+
+__version__ = "0.1.0"
+__all__ = ["track_tool", "track_agent"]

agenttrace_ai-0.1.1/agenttrace/auto.py

@@ -0,0 +1,104 @@
+import atexit
+import threading
+import time
+import sys
+import traceback
+from .models import TraceStep, StepMetrics, StepEvaluation
+from .storage import add_step
+
+_original_excepthook = sys.excepthook
+
+
+def crash_handler(exc_type, exc_value, exc_traceback):
+    err_msg = "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
+
+    # Add a special trace step for the crash
+    add_step(
+        TraceStep(
+            type="server_crash",
+            name="Unhandled Exception",
+            inputs={
+                "type": exc_type.__name__
+                if hasattr(exc_type, "__name__")
+                else str(exc_type),
+                "value": str(exc_value),
+            },
+            outputs={"traceback": err_msg},
+            metrics=StepMetrics(),
+            evaluation=StepEvaluation(
+                status="error", reasoning="Script terminated unexpectedly."
+            ),
+        )
+    )
+
+    # Call the original hook
+    _original_excepthook(exc_type, exc_value, exc_traceback)
+
+
+def _run_server():
+    import uvicorn
+    from .server import app
+
+    print(
+        "\n✨ AgentTrace: Run complete! Dashboard opened at http://localhost:8000. (Press Ctrl+C to close server and return to terminal)\n"
+    )
+
+    def open_browser():
+        time.sleep(1.5)
+        import webbrowser
+
+        try:
+            webbrowser.open("http://localhost:8000")
+        except Exception:
+            pass
+
+    t = threading.Thread(target=open_browser)
+    t.daemon = True
+    t.start()
+
+    try:
+        uvicorn.run(app, host="127.0.0.1", port=8000, log_level="warning")
+    except OSError:
+        print(
+            "AgentTrace: Dashboard is already running on port 8000 in another process."
+        )
+    except Exception as e:
+        print(f"AgentTrace: Dashboard failed to start: {e}")
+
+
+def init():
+    # Set up OpenTelemetry
+    try:
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+        from .exporter import AgentTraceExporter
+
+        provider = TracerProvider()
+        provider.add_span_processor(SimpleSpanProcessor(AgentTraceExporter()))
+        trace.set_tracer_provider(provider)
+
+        # Auto-instrument OpenTelemetry for OpenAI (also catches Groq since Groq is an OpenAI SDK wrapper)
+        try:
+            from opentelemetry.instrumentation.openai import OpenAIInstrumentor
+
+            OpenAIInstrumentor().instrument()
+        except ImportError:
+            pass  # openai extra not installed, skip native OpenAI instrumentation
+
+        # Auto-register external frameworks
+        from .integrations import auto_register
+
+        auto_register()
+    except ImportError as e:
+        import warnings
+
+        warnings.warn(
+            f"AgentTrace: OTel dependencies missing ({e}). Native LLM tracing disabled."
+        )
+
+    sys.excepthook = crash_handler
+    atexit.register(_run_server)
+
+
+init()