traceweave 0.1.2__tar.gz

traceweave-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[all]"
+          pip install pytest pytest-cov
+      - name: Run tests
+        run: |
+          pytest tests/ -v --cov=agent_trace --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: ./coverage.xml
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: pip install ruff
+      - name: Lint
+        run: ruff check agent_trace/
+      - name: Format check
+        run: ruff format --check agent_trace/

traceweave-0.1.2/.gitignore

@@ -0,0 +1,81 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# mypy
+.mypy_cache/
+dmypy.json
+dmypy.txt
+
+# ruff
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.agent-trace/

traceweave-0.1.2/LICENSE

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

traceweave-0.1.2/PKG-INFO

@@ -0,0 +1,323 @@
+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>