Metadata-Version: 2.4
Name: pyagent-trace
Version: 0.1.0
Summary: Pattern-aware OpenTelemetry tracing for multi-agent LLM systems
License: MIT
Keywords: LLM,OpenTelemetry,agents,observability,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api>=1.25
Requires-Dist: opentelemetry-sdk>=1.25
Requires-Dist: pyagent-patterns>=0.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: langfuse
Requires-Dist: langfuse>=2.0; extra == 'langfuse'
Description-Content-Type: text/markdown

# pyagent-trace

**Pattern-aware OpenTelemetry tracing** for multi-agent LLM systems. Track costs, record interactions, debug with replay.

## Install

```bash
pip install pyagent-trace              # Core (CostTracker, Recorder work without OTel)
pip install pyagent-trace[otel]        # With OpenTelemetry spans
```

## Components

- **CostTracker** — Accumulate costs by pattern, agent, and model (no OTel required)
- **Recorder** — Record all messages + LLM responses to JSONL for replay/debug
- **PatternSpanEmitter** — Create OTel spans for pattern executions (requires OTel)
- **traced_pattern / traced_agent** — Decorators for automatic tracing (requires OTel)
- **PyAgentAttributes** — Custom `pyagent.*` attribute constants

## Quick Example (no OTel required)

```python
from pyagent_trace import CostTracker, Recorder

tracker = CostTracker()
tracker.record("debate", "bull_agent", "gpt-4o", 500, 200, 0.003)
print(f"Total: ${tracker.total_cost:.4f}")
print(f"By model: {tracker.by_model()}")

recorder = Recorder()
recorder.start("debate")
recorder.record_llm_call("bull", messages, "Bull case: ...")
recorder.end("Final decision")
recorder.save("traces/debug.jsonl")
```
