diff --git a/README.md b/README.md index 6054b42..9598837 100644 --- a/README.md +++ b/README.md @@ -5,34 +5,29 @@ [![Python](https://img.shields.io/badge/python-3.9%20|%203.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE) -OpenTelemetry-native **run-level cost attribution** for AI workflows. +OpenTelemetry-native run-level cost attribution for AI workflows. ## Overview Botanu adds **runs** on top of distributed tracing. A run represents a single business transaction that may span multiple LLM calls, database queries, and services. By correlating all operations to a stable `run_id`, you get accurate cost attribution without sampling artifacts. **Key features:** -- 🎯 **Run-level attribution** — Link all costs to business outcomes -- 🔗 **Cross-service correlation** — W3C Baggage propagation -- 📊 **OTel-native** — Works with any OpenTelemetry-compatible backend -- ⚡ **Minimal overhead** — < 0.5ms per request -- 🤖 **GenAI support** — OpenAI, Anthropic, Vertex AI, and more +- **Run-level attribution** — Link all costs to business outcomes +- **Cross-service correlation** — W3C Baggage propagation +- **OTel-native** — Works with any OpenTelemetry-compatible backend +- **GenAI support** — OpenAI, Anthropic, Vertex AI, and more ## Quick Start ```python from botanu import enable, botanu_use_case, emit_outcome -# Initialize at startup enable(service_name="my-app") @botanu_use_case(name="Customer Support") async def handle_ticket(ticket_id: str): - # All operations inside get the same run_id context = await fetch_context(ticket_id) response = await generate_response(context) - - # Record the business outcome emit_outcome("success", value_type="tickets_resolved", value_amount=1) return response ``` @@ -40,34 +35,22 @@ async def handle_ticket(ticket_id: str): ## Installation ```bash -# Core SDK (opentelemetry-api only, ~50KB) -pip install botanu - -# With OTel SDK + OTLP exporter (for standalone use) -pip install "botanu[sdk]" - -# With GenAI provider instrumentation -pip install "botanu[genai]" - -# Everything included -pip install "botanu[all]" +pip install botanu # Core SDK +pip install "botanu[sdk]" # With OTel SDK + OTLP exporter +pip install "botanu[genai]" # With GenAI instrumentation +pip install "botanu[all]" # Everything included ``` -### Extras - | Extra | Description | |-------|-------------| | `sdk` | OpenTelemetry SDK + OTLP HTTP exporter | -| `instruments` | Auto-instrumentation for HTTP, databases, etc. | -| `genai` | GenAI provider instrumentation (OpenAI, Anthropic, etc.) | -| `carriers` | Cross-service propagation helpers (Celery, Kafka) | -| `all` | All of the above | -| `dev` | Development and testing tools | +| `instruments` | Auto-instrumentation for HTTP, databases | +| `genai` | GenAI provider instrumentation | +| `carriers` | Cross-service propagation (Celery, Kafka) | +| `all` | All extras | ## LLM Tracking -Track LLM calls with full cost attribution: - ```python from botanu.tracking.llm import track_llm_call @@ -84,51 +67,20 @@ with track_llm_call(provider="openai", model="gpt-4") as tracker: ## Data Tracking -Track database and storage operations: - ```python from botanu.tracking.data import track_db_operation, track_storage_operation -# Database with track_db_operation(system="postgresql", operation="SELECT") as db: result = await cursor.execute(query) db.set_result(rows_returned=len(result)) -# Storage with track_storage_operation(system="s3", operation="PUT") as storage: await s3.put_object(Bucket="bucket", Key="key", Body=data) storage.set_result(bytes_written=len(data)) ``` -## Architecture - -``` -┌──────────────────────────────────────────────────────────────┐ -│ Your Application │ -│ │ -│ @botanu_use_case track_llm_call() track_db_operation()│ -│ │ │ │ │ -│ └───────────────────┴────────────────────┘ │ -│ │ │ -│ Botanu SDK (thin) │ -│ - Generate run_id (UUIDv7) │ -│ - Set W3C Baggage │ -│ - Record spans │ -└─────────────────────────────┬─────────────────────────────────┘ - │ OTLP - ▼ -┌──────────────────────────────────────────────────────────────┐ -│ OpenTelemetry Collector │ -│ │ -│ - PII redaction - Cost calculation │ -│ - Vendor normalization - Cardinality management │ -└──────────────────────────────────────────────────────────────┘ -``` - ## Documentation -Full documentation is available at [docs.botanu.ai](https://docs.botanu.ai) and in the [`docs/`](./docs/) folder: - - [Getting Started](./docs/getting-started/) - [Concepts](./docs/concepts/) - [Tracking Guides](./docs/tracking/) @@ -138,11 +90,11 @@ Full documentation is available at [docs.botanu.ai](https://docs.botanu.ai) and ## Requirements - Python 3.9+ -- OpenTelemetry Collector (for production use) +- OpenTelemetry Collector (recommended for production) ## Contributing -See [CONTRIBUTING.md](./CONTRIBUTING.md). This project uses [DCO](./DCO) sign-off. +See [CONTRIBUTING.md](./CONTRIBUTING.md). This project uses DCO sign-off. ```bash git commit -s -m "Your commit message" @@ -150,6 +102,6 @@ git commit -s -m "Your commit message" ## License -[Apache-2.0](./LICENSE) — see [NOTICE](./NOTICE) for attribution. +[Apache-2.0](./LICENSE) This project is an [LF AI & Data Foundation](https://lfaidata.foundation/) project.