Metadata-Version: 2.4
Name: botanu
Version: 0.1.dev77
Summary: OpenTelemetry-native run-level cost attribution for AI workflows
Project-URL: Homepage, https://github.com/botanu-ai/botanu-sdk-python
Project-URL: Documentation, https://docs.botanu.ai
Project-URL: Repository, https://github.com/botanu-ai/botanu-sdk-python
Project-URL: Changelog, https://github.com/botanu-ai/botanu-sdk-python/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/botanu-ai/botanu-sdk-python/issues
Author-email: The Botanu Authors <oss@botanu.ai>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,cost-attribution,llm,mlops,observability,opentelemetry,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
Requires-Dist: opentelemetry-instrumentation-aio-pika>=0.41b0
Requires-Dist: opentelemetry-instrumentation-aiohttp-client>=0.41b0
Requires-Dist: opentelemetry-instrumentation-aiohttp-server>=0.41b0
Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.41b0
Requires-Dist: opentelemetry-instrumentation-aiopg>=0.41b0
Requires-Dist: opentelemetry-instrumentation-anthropic>=0.1b0; python_version >= '3.10'
Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
Requires-Dist: opentelemetry-instrumentation-boto3sqs>=0.41b0
Requires-Dist: opentelemetry-instrumentation-botocore>=0.41b0
Requires-Dist: opentelemetry-instrumentation-cassandra>=0.41b0
Requires-Dist: opentelemetry-instrumentation-celery>=0.41b0
Requires-Dist: opentelemetry-instrumentation-confluent-kafka>=0.41b0
Requires-Dist: opentelemetry-instrumentation-crewai>=0.1b0; python_version >= '3.10'
Requires-Dist: opentelemetry-instrumentation-django>=0.41b0
Requires-Dist: opentelemetry-instrumentation-elasticsearch>=0.41b0
Requires-Dist: opentelemetry-instrumentation-falcon>=0.41b0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0
Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0
Requires-Dist: opentelemetry-instrumentation-google-generativeai>=0.1b0; python_version >= '3.10'
Requires-Dist: opentelemetry-instrumentation-grpc>=0.41b0
Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
Requires-Dist: opentelemetry-instrumentation-kafka-python>=0.41b0
Requires-Dist: opentelemetry-instrumentation-langchain>=0.1b0; python_version >= '3.10'
Requires-Dist: opentelemetry-instrumentation-logging>=0.41b0
Requires-Dist: opentelemetry-instrumentation-mysql>=0.41b0
Requires-Dist: opentelemetry-instrumentation-mysqlclient>=0.41b0
Requires-Dist: opentelemetry-instrumentation-ollama>=0.1b0
Requires-Dist: opentelemetry-instrumentation-openai-v2>=2.0b0
Requires-Dist: opentelemetry-instrumentation-pika>=0.41b0
Requires-Dist: opentelemetry-instrumentation-psycopg2>=0.41b0
Requires-Dist: opentelemetry-instrumentation-psycopg>=0.41b0
Requires-Dist: opentelemetry-instrumentation-pymemcache>=0.41b0
Requires-Dist: opentelemetry-instrumentation-pymongo>=0.41b0
Requires-Dist: opentelemetry-instrumentation-pymysql>=0.41b0
Requires-Dist: opentelemetry-instrumentation-pyramid>=0.41b0
Requires-Dist: opentelemetry-instrumentation-redis>=0.41b0
Requires-Dist: opentelemetry-instrumentation-requests>=0.41b0
Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.41b0
Requires-Dist: opentelemetry-instrumentation-sqlite3>=0.41b0
Requires-Dist: opentelemetry-instrumentation-starlette>=0.41b0
Requires-Dist: opentelemetry-instrumentation-threading>=0.41b0
Requires-Dist: opentelemetry-instrumentation-tornado>=0.41b0
Requires-Dist: opentelemetry-instrumentation-tortoiseorm>=0.41b0
Requires-Dist: opentelemetry-instrumentation-urllib3>=0.41b0
Requires-Dist: opentelemetry-instrumentation-urllib>=0.41b0
Requires-Dist: opentelemetry-instrumentation-vertexai>=0.1b0; python_version >= '3.10'
Requires-Dist: opentelemetry-instrumentation>=0.41b0
Requires-Dist: opentelemetry-sdk>=1.20.0
Provides-Extra: aws
Requires-Dist: opentelemetry-resource-detector-aws>=0.1b0; extra == 'aws'
Provides-Extra: azure
Requires-Dist: opentelemetry-resource-detector-azure>=0.1b0; extra == 'azure'
Provides-Extra: cloud
Requires-Dist: opentelemetry-resource-detector-aws>=0.1b0; extra == 'cloud'
Requires-Dist: opentelemetry-resource-detector-azure>=0.1b0; extra == 'cloud'
Requires-Dist: opentelemetry-resource-detector-container>=0.1b0; extra == 'cloud'
Requires-Dist: opentelemetry-resource-detector-gcp>=0.1b0; extra == 'cloud'
Provides-Extra: container
Requires-Dist: opentelemetry-resource-detector-container>=0.1b0; extra == 'container'
Provides-Extra: dev
Requires-Dist: coverage[toml]>=7.0; extra == 'dev'
Requires-Dist: httpx<0.28.0,>=0.24.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: starlette<0.30.0,>=0.27.0; extra == 'dev'
Provides-Extra: gcp
Requires-Dist: opentelemetry-resource-detector-gcp>=0.1b0; extra == 'gcp'
Provides-Extra: pii-nlp
Requires-Dist: presidio-analyzer>=2.2; extra == 'pii-nlp'
Requires-Dist: presidio-anonymizer>=2.2; extra == 'pii-nlp'
Description-Content-Type: text/markdown

# botanu SDK for Python

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE)

[botanu](https://botanu.ai/) is platform that helps AI companies understand the real cost of their AI features per customer, enabling outcome-based pricing and smarter scaling.
This SDK is built on [OpenTelemetry](https://opentelemetry.io/) for event-level cost attribution for AI workflow. For more email- deborah@botanu.ai


## Getting Started

An **event** is one business transaction — resolving a support ticket, processing an order, generating a report. Each event may involve multiple **runs** (LLM calls, retries, sub-workflows) across multiple services. By correlating every run to a stable `event_id`, Botanu gives you per-event cost attribution and outcome tracking without sampling artefacts.

## Install

```bash
pip install botanu
```

An **event** is one business transaction — resolving a support ticket, processing
an order, generating a report. Each event may involve multiple **runs** (LLM calls,
retries, sub-workflows) across multiple services. By correlating every run to a
stable `event_id`, botanu gives you per-event cost attribution and outcome
tracking without sampling artifacts.

```bash
export BOTANU_API_KEY=<your-api-key>
```

Wrap your agent:

```python
import botanu

with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
    agent.run(ticket)
```

That single wrap captures every LLM call, HTTP call, and DB call inside and stamps them with `event_id`, `customer_id`, and `workflow`.

### Decorator form

```python
import botanu

@botanu.event(
    workflow="Support",
    event_id=lambda ticket: ticket.id,
    customer_id=lambda ticket: ticket.user_id,
)
def handle_ticket(ticket):
    return agent.run(ticket)
```

Works for both sync and `async def` functions.

### Multi-phase workflows

```python
with botanu.event(event_id=ticket.id, customer_id=user.id, workflow="Support"):
    with botanu.step("retrieval"):
        docs = vector_db.query(ticket.query)
    with botanu.step("generation"):
        response = llm.complete(docs)
```

See the [Quickstart](./docs/getting-started/quickstart.md) for the full five-minute walkthrough.

## Documentation

| Topic | |
| --- | --- |
| [Installation](./docs/getting-started/installation.md) | Install and configure |
| [Quickstart](./docs/getting-started/quickstart.md) | Zero-to-first-trace in five minutes |
| [Configuration](./docs/getting-started/configuration.md) | Env vars, YAML, trusted-host auth |
| [Run Context](./docs/concepts/run-context.md) | Events, runs, retries, baggage |
| [Context Propagation](./docs/concepts/context-propagation.md) | Cross-service and queue propagation |
| [Architecture](./docs/concepts/architecture.md) | SDK + collector split |
| [LLM Tracking](./docs/tracking/llm-tracking.md) | Manual LLM instrumentation (usually not needed) |
| [Data Tracking](./docs/tracking/data-tracking.md) | DB, storage, messaging (usually not needed) |
| [Content Capture](./docs/tracking/content-capture.md) | Prompt/response capture for eval, with PII scrubbing |
| [Outcomes](./docs/tracking/outcomes.md) | Diagnostic annotations and server-side resolution |
| [Auto-Instrumentation](./docs/integration/auto-instrumentation.md) | Supported libraries |
| [Kubernetes](./docs/integration/kubernetes.md) | Zero-code instrumentation at scale |
| [Existing OTel / Datadog](./docs/integration/existing-otel.md) | Brownfield coexistence |
| [`event` / `step` API](./docs/api/event.md) | Primary API reference |
| [Best Practices](./docs/patterns/best-practices.md) | Patterns that work |
| [Anti-Patterns](./docs/patterns/anti-patterns.md) | Patterns that break cost attribution |

## Requirements

- Python 3.9 or newer
- An OpenTelemetry Collector (Botanu Cloud runs one for you; self-hosted is supported too)

## Contributing

Contributions are welcome. Read the [Contributing Guide](./CONTRIBUTING.md) before opening a pull request.

All commits require [DCO sign-off](https://developercertificate.org/):

```bash
git commit -s -m "Your commit message"
```

Looking for a place to start? See the [good first issues](https://github.com/botanu-ai/botanu-sdk-python/labels/good%20first%20issue).

## Community

- [GitHub Discussions](https://github.com/botanu-ai/botanu-sdk-python/discussions) — questions, ideas, show & tell
- [GitHub Issues](https://github.com/botanu-ai/botanu-sdk-python/issues) — bugs and feature requests

## Governance

See [GOVERNANCE.md](./GOVERNANCE.md) for roles, decision-making, and the contributor ladder. Current maintainers are in [MAINTAINERS.md](./MAINTAINERS.md).

## Security

Report security vulnerabilities via [GitHub Security Advisories](https://github.com/botanu-ai/botanu-sdk-python/security/advisories/new) or see [SECURITY.md](./SECURITY.md). **Do not file a public issue.**


## Code of Conduct

This project follows the [LF Projects Code of Conduct](https://lfprojects.org/policies/code-of-conduct/). See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).

## License

[Apache License 2.0](./LICENSE)
