Skip to content

Commit 17b87ef

Browse files
deborahjacob-botanuclaude
deborahjacob-botanu
and
claude
committed
feat: Botanu SDK for Python - OpenTelemetry-native cost attribution
Initial implementation of the Botanu SDK providing run-level cost attribution for AI workflows. Features: - @botanu_use_case decorator for entry point registration - UUIDv7 run_id generation and W3C Baggage propagation - Auto-instrumentation for LLM providers (OpenAI, Anthropic, etc.) - Auto-instrumentation for databases, HTTP clients, frameworks - Kubernetes zero-code deployment via OTel Operator - AttemptLedger for durable cost tracking - 100% trace capture (no sampling) for accurate cost attribution Documentation: - Getting started guide and quickstart - Kubernetes deployment guide for 2000+ services - API reference for decorators and configuration - Best practices and anti-patterns Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Signed-off-by: Deborah Jacob <deborah@botanu.ai>
1 parent 9217770 commit 17b87ef

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+13009
-17
lines changed

‎.clomonitor.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
#
4+
# CLOMonitor metadata — used by LF AI & Data Foundation to track
5+
# project maturity and best-practice adoption.
6+
# See: https://clomonitor.io/docs/topics/checks/
7+
8+
# Documentation
9+
documentation:
10+
adopters: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/ADOPTERS.md"
11+
changelog: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/CHANGELOG.md"
12+
code_of_conduct: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/CODE_OF_CONDUCT.md"
13+
contributing: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/CONTRIBUTING.md"
14+
governance: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/GOVERNANCE.md"
15+
maintainers: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/MAINTAINERS.md"
16+
readme: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/README.md"
17+
security: "https://github.com/botanu-ai/botanu-sdk-python/blob/main/SECURITY.md"
18+
19+
# License
20+
license:
21+
approved: true
22+
spdx_id: "Apache-2.0"
23+
24+
# Best practices
25+
best_practices:
26+
dco: true
27+
openssf_badge: false # TODO: apply at https://www.bestpractices.dev/

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
name: Bug Report
5+
description: Report a bug in the Botanu SDK
6+
labels: ["bug", "triage"]
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for taking the time to report a bug.
12+
Please fill in the details below to help us reproduce and fix the issue.
13+
14+
- type: input
15+
id: version
16+
attributes:
17+
label: Botanu SDK version
18+
description: "Output of `python -c 'import botanu; print(botanu.__version__)'`"
19+
placeholder: "0.1.0"
20+
validations:
21+
required: true
22+
23+
- type: input
24+
id: python-version
25+
attributes:
26+
label: Python version
27+
description: "Output of `python --version`"
28+
placeholder: "3.12.1"
29+
validations:
30+
required: true
31+
32+
- type: dropdown
33+
id: init-mode
34+
attributes:
35+
label: Initialization mode
36+
options:
37+
- Standalone (no existing TracerProvider)
38+
- Attach (OTEL-native vendor — Splunk, Honeycomb, etc.)
39+
- Alongside (proprietary agent — Datadog, New Relic, etc.)
40+
- Unknown / not sure
41+
validations:
42+
required: true
43+
44+
- type: textarea
45+
id: description
46+
attributes:
47+
label: Description
48+
description: A clear and concise description of the bug.
49+
validations:
50+
required: true
51+
52+
- type: textarea
53+
id: reproduce
54+
attributes:
55+
label: Steps to reproduce
56+
description: Minimal code or steps to reproduce the issue.
57+
render: python
58+
validations:
59+
required: true
60+
61+
- type: textarea
62+
id: expected
63+
attributes:
64+
label: Expected behavior
65+
description: What you expected to happen.
66+
validations:
67+
required: true
68+
69+
- type: textarea
70+
id: actual
71+
attributes:
72+
label: Actual behavior
73+
description: What actually happened. Include tracebacks if applicable.
74+
render: shell
75+
validations:
76+
required: true
77+
78+
- type: textarea
79+
id: context
80+
attributes:
81+
label: Additional context
82+
description: |
83+
- OS and platform
84+
- OTel SDK / instrumentation versions
85+
- Existing observability vendor (Datadog, Splunk, etc.)
86+
- Collector configuration
87+
validations:
88+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
blank_issues_enabled: false
5+
contact_links:
6+
- name: Questions & Discussions
7+
url: https://github.com/botanu-ai/botanu-sdk-python/discussions
8+
about: Ask questions and discuss ideas
9+
- name: Security Vulnerabilities
10+
url: https://github.com/botanu-ai/botanu-sdk-python/blob/main/SECURITY.md
11+
about: Report security vulnerabilities privately (do NOT open a public issue)

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
name: Feature Request
5+
description: Suggest a new feature or enhancement
6+
labels: ["enhancement"]
7+
body:
8+
- type: markdown
9+
attributes:
10+
value: |
11+
Thanks for suggesting an improvement to Botanu SDK!
12+
13+
- type: textarea
14+
id: problem
15+
attributes:
16+
label: Problem statement
17+
description: What problem does this feature solve? Is this related to a frustration?
18+
validations:
19+
required: true
20+
21+
- type: textarea
22+
id: solution
23+
attributes:
24+
label: Proposed solution
25+
description: Describe the solution you'd like. Include API sketches if possible.
26+
validations:
27+
required: true
28+
29+
- type: textarea
30+
id: alternatives
31+
attributes:
32+
label: Alternatives considered
33+
description: Any alternative approaches you've considered.
34+
validations:
35+
required: false
36+
37+
- type: dropdown
38+
id: scope
39+
attributes:
40+
label: Which component does this affect?
41+
multiple: true
42+
options:
43+
- Core SDK (bootstrap / attach)
44+
- Run context / decorators
45+
- Span processors
46+
- Carrier propagation (SQS, Kafka, Celery)
47+
- LLM / GenAI tracking
48+
- Resource detection
49+
- Collector configuration
50+
- Documentation
51+
- Other
52+
validations:
53+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
<!-- SPDX-FileCopyrightText: 2026 The Botanu Authors -->
2+
<!-- SPDX-License-Identifier: Apache-2.0 -->
3+
4+
## Summary
5+
6+
<!-- Brief description of what this PR does and why. -->
7+
8+
## Changes
9+
10+
<!-- Bulleted list of changes. -->
11+
12+
-
13+
14+
## Type of change
15+
16+
<!-- Check all that apply. -->
17+
18+
- [ ] Bug fix (non-breaking change that fixes an issue)
19+
- [ ] New feature (non-breaking change that adds functionality)
20+
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
21+
- [ ] Documentation update
22+
- [ ] CI / build / tooling
23+
24+
## Testing
25+
26+
<!-- How was this tested? Include commands, screenshots, or links. -->
27+
28+
- [ ] Unit tests pass (`pytest`)
29+
- [ ] Lint passes (`ruff check`)
30+
- [ ] Type check passes (`mypy`)
31+
32+
## Checklist
33+
34+
- [ ] My code follows the project's coding style
35+
- [ ] I have added SPDX headers to new files
36+
- [ ] I have added tests for my changes
37+
- [ ] I have updated documentation if needed
38+
- [ ] All commits are signed off (`git commit -s`) per the [DCO](../DCO)

‎.github/workflows/ci.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
name: CI
5+
6+
on:
7+
push:
8+
branches: [main, developer-deborah]
9+
pull_request:
10+
branches: [main]
11+
12+
permissions:
13+
contents: read
14+
15+
jobs:
16+
# -------------------------------------------------------------------
17+
# Lint & format check
18+
# -------------------------------------------------------------------
19+
lint:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- uses: actions/setup-python@v5
24+
with:
25+
python-version: "3.12"
26+
- run: pip install ruff
27+
- run: ruff check src/ tests/
28+
- run: ruff format --check src/ tests/
29+
30+
# -------------------------------------------------------------------
31+
# Type checking
32+
# -------------------------------------------------------------------
33+
typecheck:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- uses: actions/checkout@v4
37+
- uses: actions/setup-python@v5
38+
with:
39+
python-version: "3.12"
40+
- run: pip install -e ".[dev]"
41+
- run: mypy src/botanu/
42+
43+
# -------------------------------------------------------------------
44+
# Test matrix — Python 3.9 → 3.13
45+
# -------------------------------------------------------------------
46+
test:
47+
runs-on: ubuntu-latest
48+
strategy:
49+
fail-fast: false
50+
matrix:
51+
python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
52+
steps:
53+
- uses: actions/checkout@v4
54+
with:
55+
fetch-depth: 0 # hatch-vcs needs full history
56+
57+
- uses: actions/setup-python@v5
58+
with:
59+
python-version: ${{ matrix.python-version }}
60+
61+
- name: Install dependencies
62+
run: pip install -e ".[dev]"
63+
64+
- name: Run tests with coverage
65+
run: pytest --cov=botanu --cov-report=xml --cov-report=term-missing
66+
67+
- name: Upload coverage
68+
if: matrix.python-version == '3.12'
69+
uses: codecov/codecov-action@v4
70+
with:
71+
file: coverage.xml
72+
fail_ci_if_error: false
73+
74+
# -------------------------------------------------------------------
75+
# Build verification — ensure the package builds cleanly
76+
# -------------------------------------------------------------------
77+
build:
78+
runs-on: ubuntu-latest
79+
steps:
80+
- uses: actions/checkout@v4
81+
with:
82+
fetch-depth: 0
83+
- uses: actions/setup-python@v5
84+
with:
85+
python-version: "3.12"
86+
- run: pip install build
87+
- run: python -m build
88+
- uses: actions/upload-artifact@v4
89+
with:
90+
name: dist
91+
path: dist/
92+
93+
# -------------------------------------------------------------------
94+
# DCO sign-off check (required by Linux Foundation)
95+
# -------------------------------------------------------------------
96+
dco:
97+
runs-on: ubuntu-latest
98+
if: github.event_name == 'pull_request'
99+
steps:
100+
- uses: actions/checkout@v4
101+
with:
102+
fetch-depth: 0
103+
- name: DCO check
104+
uses: dcoapp/app@v1

‎.github/workflows/codeql.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# SPDX-FileCopyrightText: 2026 The Botanu Authors
2+
# SPDX-License-Identifier: Apache-2.0
3+
4+
name: CodeQL
5+
6+
on:
7+
push:
8+
branches: [main]
9+
pull_request:
10+
branches: [main]
11+
schedule:
12+
- cron: "23 4 * * 1" # Weekly Monday 04:23 UTC
13+
14+
permissions:
15+
contents: read
16+
17+
jobs:
18+
analyze:
19+
runs-on: ubuntu-latest
20+
permissions:
21+
security-events: write
22+
strategy:
23+
fail-fast: false
24+
matrix:
25+
language: [python]
26+
steps:
27+
- uses: actions/checkout@v4
28+
29+
- name: Initialize CodeQL
30+
uses: github/codeql-action/init@v3
31+
with:
32+
languages: ${{ matrix.language }}
33+
34+
- name: Autobuild
35+
uses: github/codeql-action/autobuild@v3
36+
37+
- name: Perform CodeQL Analysis
38+
uses: github/codeql-action/analyze@v3
39+
with:
40+
category: "/language:${{ matrix.language }}"

0 commit comments

Comments
 (0)