Skip to content

Commit 946f4b3

Browse files
isthatdebbiejclaude
isthatdebbiej
and
claude
committed
feat: add Botanu SDK core implementation
Complete Python SDK implementation with: - Run context model with UUIDv7 run_id generation - @botanu_use_case decorator for run span creation - RunContextEnricher processor for baggage propagation - LLM/GenAI tracking with OTel semantic conventions - Data tracking (DB, storage, messaging operations) - AttemptLedger for durable cost event logging - Resource detection (K8s, AWS, GCP, Azure, container) - FastAPI/Starlette middleware - Bootstrap with auto-instrumentation for 20+ libraries - Unit tests for run_context, decorators, and LLM tracking Signed-off-by: Deborah Jacob <deborahjacob@botanu.ai> Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 334e2f7 commit 946f4b3

33 files changed

+4421
-1
lines changed

‎CHANGELOG.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [Unreleased]
9+
10+
### Added
11+
12+
- Initial open-source release
13+
- `enable()` / `disable()` bootstrap
14+
- `@botanu_use_case` decorator with UUIDv7 run_id
15+
- `emit_outcome()` and `set_business_context()` span helpers
16+
- `RunContextEnricher` span processor
17+
- LLM tracking with OTel GenAI semconv alignment
18+
- Data tracking for database, storage, and messaging
19+
- Resource detection for K8s, AWS, GCP, Azure, serverless
20+
- Auto-instrumentation for 20+ libraries
21+
- Optional extras: `[sdk]`, `[instruments]`, `[genai]`, `[carriers]`, `[all]`
22+
23+
[Unreleased]: https://github.com/botanu-ai/botanu-sdk-python/compare/v0.0.0...HEAD

‎CODE_OF_CONDUCT.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Botanu Code of Conduct
2+
3+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers agree to abide by the Code of Conduct available at https://lfprojects.org/policies/code-of-conduct/

‎MAINTAINERS.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#MAINTAINERS Following is the current list of maintainers on this project
2+
3+
The maintainers are listed in alphabetical order.
4+
5+
[@deborahjacob-botanu] https://github.com/deborahjacob-botanu (Deborah Jacob)

‎README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Botanu SDK for Python
2+
3+
[![CI](https://github.com/botanu-ai/botanu-sdk-python/actions/workflows/ci.yml/badge.svg)](https://github.com/botanu-ai/botanu-sdk-python/actions/workflows/ci.yml)
4+
[![PyPI version](https://badge.fury.io/py/botanu.svg)](https://pypi.org/project/botanu/)
5+
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/botanu-ai/botanu-sdk-python/badge)](https://scorecard.dev/viewer/?uri=github.com/botanu-ai/botanu-sdk-python)
6+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
7+
8+
OpenTelemetry-native **run-level cost attribution** for AI workflows.
9+
10+
## Overview
11+
12+
Botanu adds **runs** on top of distributed tracing. A run represents a single business execution that may span multiple traces, retries, and services. By correlating all spans to a stable `run_id`, you get accurate cost attribution without sampling artifacts.
13+
14+
## Quick Start
15+
16+
```python
17+
from botanu import enable, botanu_use_case, emit_outcome
18+
19+
enable(service_name="my-app")
20+
21+
@botanu_use_case(name="Customer Support")
22+
async def handle_ticket(ticket_id: str):
23+
result = await process_ticket(ticket_id)
24+
emit_outcome("success", value_type="tickets_resolved", value_amount=1)
25+
return result
26+
```
27+
28+
## Installation
29+
30+
```bash
31+
pip install botanu # Core (opentelemetry-api only)
32+
pip install botanu[sdk] # + OTel SDK + OTLP exporter
33+
pip install botanu[all] # Everything including GenAI instrumentation
34+
```
35+
36+
## Documentation
37+
38+
Full documentation is available at [docs.botanu.ai](https://docs.botanu.ai) and in the [`docs/`](./docs/) folder.
39+
40+
## Contributing
41+
42+
See [CONTRIBUTING.md](./CONTRIBUTING.md). This project uses [DCO](./DCO) sign-off.
43+
44+
## License
45+
46+
[Apache-2.0](./LICENSE) — see [NOTICE](./NOTICE) for attribution.

‎SECURITY.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Security Policy
2+
3+
## Supported Versions
4+
5+
Please upgrade to latest stable version of Botanu which will have know security issues addressed.
6+
7+
## Reporting a Vulnerability
8+
9+
Please report security vulnerabilities privately to the Botanu [maintainer team] (https://github.com/monocle2ai/monocle/blob/main/MAINTAINER.md). Please do not post security vulnerabilities to the public issue tracker.

‎pyproject.toml‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,25 @@ instruments = [
7272
"opentelemetry-instrumentation >= 0.41b0",
7373
"opentelemetry-instrumentation-fastapi >= 0.41b0",
7474
"opentelemetry-instrumentation-requests >= 0.41b0",
75+
"opentelemetry-instrumentation-httpx >= 0.41b0",
7576
"opentelemetry-instrumentation-flask >= 0.41b0",
77+
"opentelemetry-instrumentation-django >= 0.41b0",
7678
"opentelemetry-instrumentation-urllib3 >= 0.41b0",
79+
"opentelemetry-instrumentation-starlette >= 0.41b0",
80+
"opentelemetry-instrumentation-sqlalchemy >= 0.41b0",
81+
"opentelemetry-instrumentation-redis >= 0.41b0",
82+
"opentelemetry-instrumentation-celery >= 0.41b0",
83+
"opentelemetry-instrumentation-grpc >= 0.41b0",
84+
"opentelemetry-instrumentation-logging >= 0.41b0",
85+
]
86+
87+
# GenAI / AI model auto-instrumentation
88+
genai = [
89+
"opentelemetry-instrumentation-openai-v2 >= 2.0b0",
90+
"opentelemetry-instrumentation-anthropic >= 0.1b0",
91+
"opentelemetry-instrumentation-vertexai >= 0.1b0",
92+
"opentelemetry-instrumentation-google-genai >= 0.1b0",
93+
"opentelemetry-instrumentation-langchain >= 0.1b0",
7794
]
7895

7996
# Cross-service carrier propagation (SQS, Kafka, Celery, Redis)
@@ -84,7 +101,7 @@ carriers = [
84101

85102
# Everything
86103
all = [
87-
"botanu[sdk,instruments,carriers]",
104+
"botanu[sdk,instruments,genai,carriers]",
88105
]
89106

90107
# Development / CI

‎src/botanu/__init__.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
"""Botanu SDK - OpenTelemetry-native cost attribution for AI workflows.
5+
6+
Quick Start::
7+
8+
from botanu import enable, botanu_use_case, emit_outcome
9+
10+
enable(service_name="my-app")
11+
12+
@botanu_use_case(name="Customer Support")
13+
async def handle_request(data):
14+
result = await process(data)
15+
emit_outcome("success", value_type="tickets_resolved", value_amount=1)
16+
return result
17+
"""
18+
19+
from __future__ import annotations
20+
21+
from botanu._version import __version__
22+
23+
# Context helpers (core — no SDK dependency)
24+
from botanu.sdk.context import (
25+
get_baggage,
26+
get_current_span,
27+
get_run_id,
28+
get_use_case,
29+
set_baggage,
30+
)
31+
32+
# Decorators (primary integration point)
33+
from botanu.sdk.decorators import botanu_outcome, botanu_use_case, use_case
34+
35+
# Span helpers
36+
from botanu.sdk.span_helpers import emit_outcome, set_business_context
37+
38+
# Run context model
39+
from botanu.models.run_context import RunContext, RunOutcome, RunStatus
40+
41+
# Bootstrap
42+
from botanu.sdk.bootstrap import (
43+
disable,
44+
enable,
45+
is_enabled,
46+
)
47+
48+
# Configuration
49+
from botanu.sdk.config import BotanuConfig
50+
51+
__all__ = [
52+
"__version__",
53+
# Bootstrap
54+
"enable",
55+
"disable",
56+
"is_enabled",
57+
# Configuration
58+
"BotanuConfig",
59+
# Decorators
60+
"botanu_use_case",
61+
"use_case",
62+
"botanu_outcome",
63+
# Span helpers
64+
"emit_outcome",
65+
"set_business_context",
66+
"get_current_span",
67+
# Context
68+
"get_run_id",
69+
"get_use_case",
70+
"set_baggage",
71+
"get_baggage",
72+
# Run context
73+
"RunContext",
74+
"RunStatus",
75+
"RunOutcome",
76+
]

‎src/botanu/_version.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
"""Dynamic version from package metadata (set by hatch-vcs at build time)."""
5+
6+
from __future__ import annotations
7+
8+
try:
9+
from importlib.metadata import version
10+
11+
__version__: str = version("botanu")
12+
except Exception:
13+
__version__ = "0.0.0.dev0"

‎src/botanu/models/__init__.py‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
"""Botanu data models."""
5+
6+
from __future__ import annotations
7+
8+
from botanu.models.run_context import RunContext, RunOutcome, RunStatus
9+
10+
__all__ = ["RunContext", "RunOutcome", "RunStatus"]

0 commit comments

Comments
 (0)