Skip to content

Commit 3fb662c

Browse files
deborahjacob-botanudeborahjacob-botanu
authored
Merge pull request #11 from botanu-ai/developer-deborah
docs: add comprehensive LF-format documentation
2 parents c1988f4 + a9635c8 commit 3fb662c

22 files changed

+5980
-53
lines changed

‎.github/workflows/release.yml‎

Lines changed: 61 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,24 @@ on:
77
push:
88
tags:
99
- "v*"
10+
workflow_dispatch:
11+
inputs:
12+
publish_target:
13+
description: 'Publish target'
14+
required: true
15+
default: 'testpypi'
16+
type: choice
17+
options:
18+
- testpypi
19+
- pypi
1020

1121
permissions:
1222
contents: read
1323

1424
jobs:
25+
# -------------------------------------------------------------------
26+
# Build the package
27+
# -------------------------------------------------------------------
1528
build:
1629
runs-on: ubuntu-latest
1730
steps:
@@ -24,23 +37,61 @@ jobs:
2437
python-version: "3.12"
2538

2639
- name: Install build tools
27-
run: pip install build
40+
run: pip install build twine
2841

2942
- name: Build sdist and wheel
3043
run: python -m build
3144

45+
- name: Check package with twine
46+
run: twine check dist/*
47+
48+
- name: List build artifacts
49+
run: ls -la dist/
50+
3251
- uses: actions/upload-artifact@v4
3352
with:
3453
name: dist
3554
path: dist/
3655

56+
# -------------------------------------------------------------------
57+
# Publish to TestPyPI (manual trigger or pre-release tags)
58+
# Uses Trusted Publishing (OIDC — no API tokens needed)
59+
# Requires TestPyPI project to be configured for GitHub OIDC:
60+
# https://test.pypi.org/manage/project/botanu/settings/publishing/
61+
# -------------------------------------------------------------------
62+
publish-testpypi:
63+
needs: build
64+
if: |
65+
github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target == 'testpypi'
66+
|| (github.event_name == 'push' && contains(github.ref, '-alpha') || contains(github.ref, '-beta') || contains(github.ref, '-rc'))
67+
runs-on: ubuntu-latest
68+
environment:
69+
name: testpypi
70+
url: https://test.pypi.org/p/botanu
71+
permissions:
72+
id-token: write # required for OIDC trusted publishing
73+
steps:
74+
- uses: actions/download-artifact@v4
75+
with:
76+
name: dist
77+
path: dist/
78+
79+
- name: Publish to TestPyPI
80+
uses: pypa/gh-action-pypi-publish@release/v1
81+
with:
82+
repository-url: https://test.pypi.org/legacy/
83+
skip-existing: true
84+
3785
# -------------------------------------------------------------------
3886
# Publish to PyPI via Trusted Publishing (OIDC — no API tokens)
3987
# Requires PyPI project to be configured for GitHub OIDC:
40-
# https://docs.pypi.org/trusted-publishers/
88+
# https://pypi.org/manage/project/botanu/settings/publishing/
4189
# -------------------------------------------------------------------
4290
publish-pypi:
4391
needs: build
92+
if: |
93+
github.event_name == 'workflow_dispatch' && github.event.inputs.publish_target == 'pypi'
94+
|| (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref, '-'))
4495
runs-on: ubuntu-latest
4596
environment:
4697
name: pypi
@@ -60,7 +111,8 @@ jobs:
60111
# Create GitHub Release with auto-generated notes
61112
# -------------------------------------------------------------------
62113
github-release:
63-
needs: publish-pypi
114+
needs: [build, publish-pypi]
115+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
64116
runs-on: ubuntu-latest
65117
permissions:
66118
contents: write
@@ -77,4 +129,9 @@ jobs:
77129
- name: Create GitHub Release
78130
env:
79131
GH_TOKEN: ${{ github.token }}
80-
run: gh release create "${{ github.ref_name }}" dist/* --generate-notes
132+
run: |
133+
if [[ "${{ github.ref_name }}" == *"-"* ]]; then
134+
gh release create "${{ github.ref_name }}" dist/* --generate-notes --prerelease
135+
else
136+
gh release create "${{ github.ref_name }}" dist/* --generate-notes
137+
fi

‎CHANGELOG.md‎

Lines changed: 64 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.1.0] - 2026-02-05
11+
1012
### Added
1113

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
14+
- Initial open-source release under Apache-2.0 license
15+
- **Core SDK**
16+
- `enable()` / `disable()` bootstrap functions for SDK initialization
17+
- `@botanu_use_case` decorator with UUIDv7 run_id generation
18+
- `@botanu_outcome` decorator for sub-function outcome tracking
19+
- `emit_outcome()` helper for recording business outcomes
20+
- `set_business_context()` for cost attribution dimensions
21+
- `RunContextEnricher` span processor for automatic run_id propagation
22+
23+
- **LLM Tracking** (aligned with OTel GenAI semantic conventions)
24+
- `track_llm_call()` context manager for LLM/model operations
25+
- `track_tool_call()` context manager for tool/function calls
26+
- Token usage tracking (input, output, cached)
27+
- Provider normalization for 15+ LLM providers
28+
- Support for all GenAI operations (chat, embeddings, etc.)
29+
30+
- **Data Tracking**
31+
- `track_db_operation()` for database operations
32+
- `track_storage_operation()` for object storage (S3, GCS, Azure Blob)
33+
- `track_messaging_operation()` for message queues (SQS, Kafka, Pub/Sub)
34+
- System normalization for 30+ database/storage systems
35+
36+
- **Context Propagation**
37+
- W3C Baggage propagation for cross-service run_id correlation
38+
- Lean mode (default) and full mode propagation options
39+
- `RunContext` model with retry tracking and deadline support
40+
41+
- **Resource Detection**
42+
- Kubernetes (pod, namespace, container)
43+
- AWS (EC2, ECS, Lambda, Fargate)
44+
- GCP (GCE, Cloud Run, Cloud Functions)
45+
- Azure (VM, Container Apps, Functions)
46+
47+
- **Auto-Instrumentation Support**
48+
- HTTP clients: requests, httpx, urllib3, aiohttp
49+
- Web frameworks: FastAPI, Flask, Django, Starlette
50+
- Databases: SQLAlchemy, psycopg2, asyncpg, pymongo, Redis
51+
- Messaging: Celery, Kafka
52+
- GenAI: OpenAI, Anthropic, Vertex AI, Google GenAI, LangChain
53+
54+
- **Optional Extras**
55+
- `[sdk]` - OTel SDK + OTLP exporter
56+
- `[instruments]` - Common library instrumentation
57+
- `[genai]` - GenAI provider instrumentation
58+
- `[carriers]` - Cross-service propagation helpers
59+
- `[all]` - Everything included
60+
- `[dev]` - Development and testing tools
61+
62+
- **Documentation**
63+
- Comprehensive docs in `/docs` following LF format
64+
- Getting started guides
65+
- API reference
66+
- Best practices and anti-patterns
67+
68+
### Dependencies
69+
70+
- Core: `opentelemetry-api >= 1.20.0`
71+
- SDK extra: `opentelemetry-sdk`, `opentelemetry-exporter-otlp-proto-http`
72+
- Python: `>= 3.9`
73+
74+
[Unreleased]: https://github.com/botanu-ai/botanu-sdk-python/compare/v0.1.0...HEAD
75+
[0.1.0]: https://github.com/botanu-ai/botanu-sdk-python/releases/tag/v0.1.0

‎README.md‎

Lines changed: 117 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,45 +2,155 @@
22

33
[![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)
44
[![PyPI version](https://badge.fury.io/py/botanu.svg)](https://pypi.org/project/botanu/)
5+
[![Python versions](https://img.shields.io/pypi/pyversions/botanu.svg)](https://pypi.org/project/botanu/)
56
[![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)
67
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
78

89
OpenTelemetry-native **run-level cost attribution** for AI workflows.
910

1011
## Overview
1112

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+
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.
14+
15+
**Key features:**
16+
- 🎯 **Run-level attribution** — Link all costs to business outcomes
17+
- 🔗 **Cross-service correlation** — W3C Baggage propagation
18+
- 📊 **OTel-native** — Works with any OpenTelemetry-compatible backend
19+
- ⚡ **Minimal overhead** — < 0.5ms per request
20+
- 🤖 **GenAI support** — OpenAI, Anthropic, Vertex AI, and more
1321

1422
## Quick Start
1523

1624
```python
1725
from botanu import enable, botanu_use_case, emit_outcome
1826

27+
# Initialize at startup
1928
enable(service_name="my-app")
2029

2130
@botanu_use_case(name="Customer Support")
2231
async def handle_ticket(ticket_id: str):
23-
result = await process_ticket(ticket_id)
32+
# All operations inside get the same run_id
33+
context = await fetch_context(ticket_id)
34+
response = await generate_response(context)
35+
36+
# Record the business outcome
2437
emit_outcome("success", value_type="tickets_resolved", value_amount=1)
25-
return result
38+
return response
2639
```
2740

2841
## Installation
2942

3043
```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
44+
# Core SDK (opentelemetry-api only, ~50KB)
45+
pip install botanu
46+
47+
# With OTel SDK + OTLP exporter (for standalone use)
48+
pip install "botanu[sdk]"
49+
50+
# With GenAI provider instrumentation
51+
pip install "botanu[genai]"
52+
53+
# Everything included
54+
pip install "botanu[all]"
55+
```
56+
57+
### Extras
58+
59+
| Extra | Description |
60+
|-------|-------------|
61+
| `sdk` | OpenTelemetry SDK + OTLP HTTP exporter |
62+
| `instruments` | Auto-instrumentation for HTTP, databases, etc. |
63+
| `genai` | GenAI provider instrumentation (OpenAI, Anthropic, etc.) |
64+
| `carriers` | Cross-service propagation helpers (Celery, Kafka) |
65+
| `all` | All of the above |
66+
| `dev` | Development and testing tools |
67+
68+
## LLM Tracking
69+
70+
Track LLM calls with full cost attribution:
71+
72+
```python
73+
from botanu.tracking.llm import track_llm_call
74+
75+
with track_llm_call(provider="openai", model="gpt-4") as tracker:
76+
response = await openai.chat.completions.create(
77+
model="gpt-4",
78+
messages=[{"role": "user", "content": "Hello"}]
79+
)
80+
tracker.set_tokens(
81+
input_tokens=response.usage.prompt_tokens,
82+
output_tokens=response.usage.completion_tokens,
83+
)
84+
```
85+
86+
## Data Tracking
87+
88+
Track database and storage operations:
89+
90+
```python
91+
from botanu.tracking.data import track_db_operation, track_storage_operation
92+
93+
# Database
94+
with track_db_operation(system="postgresql", operation="SELECT") as db:
95+
result = await cursor.execute(query)
96+
db.set_result(rows_returned=len(result))
97+
98+
# Storage
99+
with track_storage_operation(system="s3", operation="PUT") as storage:
100+
await s3.put_object(Bucket="bucket", Key="key", Body=data)
101+
storage.set_result(bytes_written=len(data))
102+
```
103+
104+
## Architecture
105+
106+
```
107+
┌──────────────────────────────────────────────────────────────┐
108+
│ Your Application │
109+
│ │
110+
│ @botanu_use_case track_llm_call() track_db_operation()│
111+
│ │ │ │ │
112+
│ └───────────────────┴────────────────────┘ │
113+
│ │ │
114+
│ Botanu SDK (thin) │
115+
│ - Generate run_id (UUIDv7) │
116+
│ - Set W3C Baggage │
117+
│ - Record spans │
118+
└─────────────────────────────┬─────────────────────────────────┘
119+
│ OTLP
120+
▼
121+
┌──────────────────────────────────────────────────────────────┐
122+
│ OpenTelemetry Collector │
123+
│ │
124+
│ - PII redaction - Cost calculation │
125+
│ - Vendor normalization - Cardinality management │
126+
└──────────────────────────────────────────────────────────────┘
34127
```
35128

36129
## Documentation
37130

38-
Full documentation is available at [docs.botanu.ai](https://docs.botanu.ai) and in the [`docs/`](./docs/) folder.
131+
Full documentation is available at [docs.botanu.ai](https://docs.botanu.ai) and in the [`docs/`](./docs/) folder:
132+
133+
- [Getting Started](./docs/getting-started/)
134+
- [Concepts](./docs/concepts/)
135+
- [Tracking Guides](./docs/tracking/)
136+
- [Integration](./docs/integration/)
137+
- [API Reference](./docs/api/)
138+
139+
## Requirements
140+
141+
- Python 3.9+
142+
- OpenTelemetry Collector (for production use)
39143

40144
## Contributing
41145

42146
See [CONTRIBUTING.md](./CONTRIBUTING.md). This project uses [DCO](./DCO) sign-off.
43147

148+
```bash
149+
git commit -s -m "Your commit message"
150+
```
151+
44152
## License
45153

46154
[Apache-2.0](./LICENSE) — see [NOTICE](./NOTICE) for attribution.
155+
156+
This project is an [LF AI & Data Foundation](https://lfaidata.foundation/) project.

0 commit comments

Comments
 (0)