Metadata-Version: 2.5
Name: lode-observe-ai
Version: 0.1.4.dev0
Summary: AI agent observability & tracing platform with OpenTelemetry export, SQLite persistence, and multi-format trace analysis. Real-time debugging for production AI systems.
Author-email: CraftedWithIntent <hello@craftedwithintent.ai>
License: MIT
License-File: LICENSE
Keywords: agents,cost-analytics,debugging,observability,opentelemetry,token-tracking,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.104.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp>=0.41.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: pydantic-core>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: typer>=0.9.0
Requires-Dist: uvicorn>=0.24.0
Provides-Extra: dev
Requires-Dist: black>=23.9.0; extra == 'dev'
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.300; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Lode Observe AI: Agent Observability & Tracing

![License](https://img.shields.io/badge/License-MIT-blue) ![Python](https://img.shields.io/badge/Python-3.11%2B-blue) ![Status](https://img.shields.io/badge/Status-Alpha%20MVP-orange)

**Deep execution tracer for AI agents. Export traces to Jaeger, DataDog, or any OTEL-compatible backend. Includes cost analytics, anomaly detection, and production observability.**

## The Problem

Multi-agent systems are black boxes:
- ❌ No visibility into intermediate steps when agents fail or loop
- ❌ Token costs explode without warning
- ❌ Traditional APM tools fail—they're built for deterministic RPCs, not probabilistic token generation
- ❌ No explanation for why the model entered a runaway loop

## The Solution

Lode Observe AI maps every step of agent execution with **zero overhead** (<0.1ms per span). Track:
- **Every prompt, token, and decision** with hierarchical DAGs
- **Cost attribution** by model, provider, and agent step
- **Anomaly detection** for infinite loops, context exhaustion, and runaway spend
- **Real-time debugging** via Jaeger, DataDog, or local CLI

## Installation

```bash
# Via pip
pip install lode-observe-ai

# Via Docker
docker run -p 3000:3000 ghcr.io/craftedwithintent/lode-observe-ai:0.1.3.dev0
```

## Quick Start

### 1. Analyze Traces Locally

```python
from lode_observe_ai import build_trace_tree, aggregate_costs, detect_anomalies

# Build trace tree from spans
tree = build_trace_tree(spans, root_span_id="root_id")

# Analyze costs
costs = aggregate_costs(tree)
print(f"Total tokens: {costs.total_tokens}")
print(f"Total cost: ${costs.total_cost_usd:.4f}")

# Detect anomalies
anomalies = detect_anomalies(tree)
if anomalies.estimated_infinite_loop:
    print(f"⚠️  Infinite loop detected! {anomalies.max_repeated_tool_calls} repeated calls")
```

### 2. Export to Jaeger

```bash
# Start Jaeger (Docker)
docker run -d -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one

# Export trace
lode-observe-ai export --trace-id <trace-id> --format otel --otel-endpoint http://localhost:4317

# Open browser: http://localhost:16686
```

### 3. Export to Test Suite

```bash
# Convert failed trace into test case
lode-observe-ai export --trace-id abc123 --format assay --output suite.yaml
```

## Key Features

| Feature | Details |
|---------|---------|
| **Instrumentation** | OpenAI, LiteLLM hooks + Python decorators |
| **Analysis** | DAG assembly, cost aggregation, anomaly detection |
| **Export** | JSON, YAML, Assay, OTEL/Jaeger |
| **Deployment** | Docker, Kubernetes, local SQLite |
| **Overhead** | <0.1ms per span, <1ms for 10-step flow |
| **Storage** | SQLite WAL (local), cloud backends (Phase 2) |

## What's Included (Phase 1 MVP)

✅ Core trace analysis (DAG, costs, anomalies)  
✅ OpenTelemetry export (Jaeger, DataDog compatible)  
✅ CLI tools (export, inspect, analyze)  
✅ Docker & Kubernetes deployment  
✅ SQLite storage backend  
✅ <0.1ms instrumentation overhead  

🟡 Phase 2 (coming): Cloud sync, sampling, cycle interceptor  
🟡 Phase 3 (coming): Enterprise auth, multi-tenancy, analytics  

## Configuration

### Python Context Manager API

```python
from lode_observe_ai import start_trace, trace_agent

@trace_agent(name="ResearchAgent", sample_rate=1.0)
def my_agent(topic: str) -> str:
    with start_trace("step") as tracer:
        result = do_work(topic)
        tracer.record_output(result)
    return result
```

### Environment Variables

```bash
# Storage
LODE_STORAGE=sqlite:///./traces.db

# OTEL export
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_SERVICE_NAME=my-agent

# Instrumentation
LODE_SAMPLE_RATE=1.0  # Trace every request
LODE_OVERHEAD_BUDGET_MS=0.5  # Max overhead allowed
```

## Performance

| Operation | Time | Notes |
|-----------|------|-------|
| Instrumentation | <0.1ms/span | Non-blocking async |
| Build DAG (100 spans) | 2ms | Pure functional, O(n) |
| Aggregate costs (100 spans) | 1ms | Single pass |
| Detect anomalies (100 spans) | 3ms | Full analysis |

See the [GitHub repo](https://github.com/CraftedWithIntent/lode-observe-ai) for full benchmarks.

## Documentation

- **[Full README](https://github.com/CraftedWithIntent/lode-observe-ai)** — Comprehensive guide
- **[Deployment Guide](https://github.com/CraftedWithIntent/lode-observe-ai/blob/main/docs/DEPLOYMENT.md)** — Docker, Kubernetes, security
- **[Troubleshooting](https://github.com/CraftedWithIntent/lode-observe-ai/blob/main/docs/TROUBLESHOOTING.md)** — Common issues, debug mode
- **[Performance Guide](https://github.com/CraftedWithIntent/lode-observe-ai/blob/main/docs/PERFORMANCE.md)** — Benchmarks, tuning, scaling
- **[Contributing](https://github.com/CraftedWithIntent/lode-observe-ai/blob/main/CONTRIBUTING.md)** — Development setup, code standards
- **[Examples](https://github.com/CraftedWithIntent/lode-observe-ai/tree/main/examples)** — Research agent with tracing

## Support

- 🐛 [GitHub Issues](https://github.com/CraftedWithIntent/lode-observe-ai/issues) — Bug reports, feature requests
- 💬 [GitHub Discussions](https://github.com/CraftedWithIntent/lode-observe-ai/discussions) — Questions, ideas
- 📖 [Full Repository](https://github.com/CraftedWithIntent/lode-observe-ai) — Source, examples, docs

## License

MIT License — See [LICENSE](https://github.com/CraftedWithIntent/lode-observe-ai/blob/main/LICENSE) for details.

---

**Completely decoupled:** Works standalone. No shared dependencies with other packages. Part of the [CraftedWithIntent](https://github.com/CraftedWithIntent) ecosystem for production AI systems.
