tokenhelm 0.1.0rc1__tar.gz

tokenhelm-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TokenHelm contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenhelm-0.1.0rc1/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: tokenhelm
+Version: 0.1.0rc1
+Summary: Lightweight, framework-agnostic token tracking and LLM cost calculation across providers.
+Author: TokenHelm contributors
+License: MIT
+Project-URL: Homepage, https://github.com/quadkeys/tokenhelm
+Keywords: llm,tokens,cost,openai,anthropic,gemini,ollama,observability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.1; extra == "gemini"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.1; extra == "ollama"
+Provides-Extra: all
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: google-genai>=0.1; extra == "all"
+Requires-Dist: anthropic>=0.40; extra == "all"
+Requires-Dist: ollama>=0.1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Dynamic: license-file
+
+# TokenHelm
+
+**Lightweight, framework-agnostic token tracking and LLM cost calculation across providers.**
+
+TokenHelm gives you one normalized usage/cost event for every LLM call — OpenAI, Gemini,
+Anthropic, or Ollama — without locking you into any framework, patching any provider SDK, or
+ever touching your credentials. It simply **observes** the response object your own client
+already returns.
+
+```python
+from tokenhelm import TokenHelm
+
+tracker = TokenHelm()                      # zero-config
+response = client.chat.completions.create(...)   # your own OpenAI call
+event = tracker.track(response)            # normalized LLMEvent
+print(event.to_dict())
+# {'provider': 'openai', 'model': 'gpt-4o', 'input_tokens': 1000,
+#  'output_tokens': 500, 'total_tokens': 1500, 'latency': 0.0,
+#  'cost': '0.00750', 'timestamp': '...', 'usage_complete': True,
+#  'priced': True, 'currency': 'USD'}
+```
+
+---
+
+## Installation
+
+```bash
+pip install tokenhelm                  # core (only dependency: PyYAML)
+pip install "tokenhelm[openai]"        # + OpenAI extras (for your own client)
+pip install "tokenhelm[anthropic]"     # + Anthropic
+pip install "tokenhelm[gemini]"        # + Google Gemini
+pip install "tokenhelm[ollama]"        # + Ollama
+pip install "tokenhelm[all]"           # all provider extras
+pip install "tokenhelm[dev]"           # test/lint toolchain
+```
+
+Requires **Python 3.11+**. The extras only pull in the provider SDKs *you* call — TokenHelm
+itself never imports them to read a response.
+
+---
+
+## Quick Start
+
+```python
+from tokenhelm import TokenHelm
+
+tracker = TokenHelm()
+
+# 1. Manual tracking — track any completed response
+event = tracker.track(response)
+
+# 2. Scoped tracking — collect every event in a block
+with tracker.trace() as scope:
+    response = client.chat.completions.create(...)
+    scope.track(response)
+print(scope.events)           # [LLMEvent(...)]
+
+# 3. Choose where events go (any logger, callable, or storage)
+from tokenhelm import ConsoleLogger
+tracker = TokenHelm(logger=[ConsoleLogger(), lambda e: metrics.push(e.to_dict())])
+
+# 4. Bring your own pricing (file, dict, or a full PricingProvider)
+tracker = TokenHelm(pricing="my_rates.yaml")
+tracker = TokenHelm(pricing={"openai": {"gpt-4o": {"input": 2.5, "output": 10.0}}})
+
+# 5. Reconfigure later without rebuilding
+tracker.configure(currency="EUR")
+
+# 6. Streaming — exactly one event after the stream is exhausted
+for chunk in tracker.track_stream(client.chat.completions.create(..., stream=True)):
+    ...   # consume chunks as usual
+
+# 7. Async — same API with `async with` / `async for`
+async with tracker.trace() as scope:
+    scope.track(await aclient.chat.completions.create(...))
+```
+
+Every tracked request yields the same normalized **`LLMEvent`** with the eight mandated
+fields — `provider, model, input_tokens, output_tokens, total_tokens, latency, cost,
+timestamp` — plus `usage_complete` / `priced` status flags. Consumers never see a
+provider-specific usage object. Costs use `decimal.Decimal` (no float drift). Missing usage or
+unknown pricing degrade gracefully via the flags — tracking never raises on missing data.
+
+---
+
+## Architecture
+
+TokenHelm is built around five replaceable extension points; the core depends only on their
+interfaces, never on a concrete implementation.
+
+```
+            ┌──────────────────────────────────────────────────────────┐
+            │                     Your Application                       │
+            └───────────────────────────┬──────────────────────────────┘
+                                         │  track() / trace() / configure()
+                                         ▼
+                              ┌────────────────────┐
+                              │      TokenHelm      │   (sdk: client + TraceScope)
+                              └─────────┬──────────┘
+                                        ▼
+                              ┌────────────────────┐
+                              │    TokenTracker     │   builds the normalized LLMEvent
+                              └───┬────────────┬───┘
+                  extract usage  │            │  compute cost
+                                 ▼            ▼
+                   ┌──────────────────┐   ┌──────────────────┐
+                   │   BaseAdapter ①  │   │ CostCalculator   │
+                   │ OpenAI/Gemini/   │   └────────┬─────────┘
+                   │ Anthropic/Ollama │            ▼
+                   └──────────────────┘   ┌──────────────────┐
+                                          │ PricingProvider ② │  (YAML default)
+                                          └──────────────────┘
+                                        │
+                                        ▼  emit (tracker is unaware of sinks)
+                              ┌────────────────────┐
+                              │  EventDispatcher ③ │
+                              └───┬────────────┬───┘
+                                  ▼            ▼
+                        ┌──────────────┐  ┌──────────────────┐
+                        │   Logger ④   │  │ StorageBackend ⑤ │  (optional)
+                        │ Console/...  │  └──────────────────┘
+                        └──────────────┘
+```
+
+**Extension points** (all public & stable — Constitution Principle VI):
+
+| # | Interface | Default | Swap it to… |
+|---|-----------|---------|-------------|
+| ① | `BaseAdapter` | OpenAI, Gemini, Anthropic, Ollama | add a new provider |
+| ② | `PricingProvider` | `YamlPricingProvider` | remote/dynamic pricing, AI FinOps |
+| ③ | `EventDispatcher` | `DefaultEventDispatcher` | custom routing/batching/export |
+| ④ | `Logger` | `ConsoleLogger` | JSON/file/metrics/dashboards |
+| ⑤ | `StorageBackend` | none (opt-in) | in-memory/SQLite/warehouse/analytics |
+
+**Dependency direction is strictly one-way** (no reverse dependencies):
+
+```
+Application → TokenHelm → TokenTracker → EventDispatcher → Logger / StorageBackend
+                              └────────→ CostCalculator → PricingProvider
+                              └────────→ UsageParser → BaseAdapter
+```
+
+`CostCalculator` depends *only* on `PricingProvider`; `TokenTracker` emits *only* through
+`EventDispatcher`. Analytics, dashboards, and FinOps are downstream consumers of `LLMEvent`
+behind these interfaces — they require no change to the core.
+
+---
+
+## Supported Providers
+
+All four providers are supported, with streaming and async, in v0.1.0.
+
+| Provider | Status | Usage fields read |
+|----------|--------|-------------------|
+| **OpenAI** | ✅ supported | `usage.prompt_tokens` / `completion_tokens` (Chat); `input_tokens` / `output_tokens` (Responses) |
+| **Google Gemini** | ✅ supported | `usage_metadata.prompt_token_count` / `candidates_token_count` |
+| **Anthropic** | ✅ supported | `usage.input_tokens` / `output_tokens` (+ cache token extras) |
+| **Ollama** (local) | ✅ supported | `prompt_eval_count` / `eval_count` |
+
+All providers normalize into the **same** `LLMEvent` schema — switching providers is a
+configuration change, not a code change. Each adapter handles both completed responses and
+streaming.
+
+---
+
+## Roadmap
+
+**v0.1.0 — Core SDK ✅ (current)**
+
+- [x] Track usage and cost across one provider (MVP): cost calculation, normalized event,
+      scoped `trace()`, console logging, graceful degradation.
+- [x] Provider parity: OpenAI, Gemini, Anthropic, Ollama adapters; identical event shape.
+- [x] Output choice: `JSONLogger`, `FileLogger`, `InMemoryStorageBackend`, full `configure()`
+      and multi-sink dispatch.
+- [x] Streaming & async: `track_stream()` (one final event), async `trace()`.
+- [x] Hardening: <5 ms / <20 MB budgets, thread/async isolation suite, docs, packaging.
+
+**Beyond v0.1** — each tier is additive on the five extension points; the v0.1 core API does
+not change. See [`ROADMAP.md`](ROADMAP.md).
+
+- [ ] **v0.2 — Analytics SDK** (`SQLiteStorageBackend` + usage queries)
+- [ ] **v0.3 — Prompt Intelligence** (per-prompt/template attribution)
+- [ ] **v0.4 — RAG Intelligence** (retrieval-aware accounting)
+- [ ] **v0.5 — AI FinOps** (budgets, alerts, remote pricing)
+- [ ] **v1.0 — Enterprise Platform** (stabilize the v0.x surface; dashboard, plugins)
+
+---
+
+## Design principles
+
+Framework-agnostic · provider-independent · zero vendor lock-in · <5 ms overhead ·
+observe-don't-patch · one standardized event · everything replaceable.
+
+See `specs/001-core-sdk/` for the constitution, spec, plan, data model, and public API
+contract.
+
+## Release Process
+
+Releases follow a documented, automated procedure (Conventional Commits → release-please →
+Trusted Publishing on PyPI via OIDC). The canonical, end-to-end release procedure is the
+**[Go-Live & Release checklist](docs/go-live-checklist.md)** — follow it for every release.
+
+Supporting docs:
+
+- [`docs/releasing.md`](docs/releasing.md) — how publishing works (TestPyPI → PyPI, OIDC).
+- [`docs/repository-setup.md`](docs/repository-setup.md) — branch protection, required checks,
+  Dependabot, security features.
+- [`docs/release-checklist.md`](docs/release-checklist.md) — per-version quality gates.
+
+Contributors: see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev workflow, versioning, and
+deprecation policy.
+
+## License
+
+MIT
+

tokenhelm-0.1.0rc1/README.md

@@ -0,0 +1,216 @@
+# TokenHelm
+
+**Lightweight, framework-agnostic token tracking and LLM cost calculation across providers.**
+
+TokenHelm gives you one normalized usage/cost event for every LLM call — OpenAI, Gemini,
+Anthropic, or Ollama — without locking you into any framework, patching any provider SDK, or
+ever touching your credentials. It simply **observes** the response object your own client
+already returns.
+
+```python
+from tokenhelm import TokenHelm
+
+tracker = TokenHelm()                      # zero-config
+response = client.chat.completions.create(...)   # your own OpenAI call
+event = tracker.track(response)            # normalized LLMEvent
+print(event.to_dict())
+# {'provider': 'openai', 'model': 'gpt-4o', 'input_tokens': 1000,
+#  'output_tokens': 500, 'total_tokens': 1500, 'latency': 0.0,
+#  'cost': '0.00750', 'timestamp': '...', 'usage_complete': True,
+#  'priced': True, 'currency': 'USD'}
+```
+
+---
+
+## Installation
+
+```bash
+pip install tokenhelm                  # core (only dependency: PyYAML)
+pip install "tokenhelm[openai]"        # + OpenAI extras (for your own client)
+pip install "tokenhelm[anthropic]"     # + Anthropic
+pip install "tokenhelm[gemini]"        # + Google Gemini
+pip install "tokenhelm[ollama]"        # + Ollama
+pip install "tokenhelm[all]"           # all provider extras
+pip install "tokenhelm[dev]"           # test/lint toolchain
+```
+
+Requires **Python 3.11+**. The extras only pull in the provider SDKs *you* call — TokenHelm
+itself never imports them to read a response.
+
+---
+
+## Quick Start
+
+```python
+from tokenhelm import TokenHelm
+
+tracker = TokenHelm()
+
+# 1. Manual tracking — track any completed response
+event = tracker.track(response)
+
+# 2. Scoped tracking — collect every event in a block
+with tracker.trace() as scope:
+    response = client.chat.completions.create(...)
+    scope.track(response)
+print(scope.events)           # [LLMEvent(...)]
+
+# 3. Choose where events go (any logger, callable, or storage)
+from tokenhelm import ConsoleLogger
+tracker = TokenHelm(logger=[ConsoleLogger(), lambda e: metrics.push(e.to_dict())])
+
+# 4. Bring your own pricing (file, dict, or a full PricingProvider)
+tracker = TokenHelm(pricing="my_rates.yaml")
+tracker = TokenHelm(pricing={"openai": {"gpt-4o": {"input": 2.5, "output": 10.0}}})
+
+# 5. Reconfigure later without rebuilding
+tracker.configure(currency="EUR")
+
+# 6. Streaming — exactly one event after the stream is exhausted
+for chunk in tracker.track_stream(client.chat.completions.create(..., stream=True)):
+    ...   # consume chunks as usual
+
+# 7. Async — same API with `async with` / `async for`
+async with tracker.trace() as scope:
+    scope.track(await aclient.chat.completions.create(...))
+```
+
+Every tracked request yields the same normalized **`LLMEvent`** with the eight mandated
+fields — `provider, model, input_tokens, output_tokens, total_tokens, latency, cost,
+timestamp` — plus `usage_complete` / `priced` status flags. Consumers never see a
+provider-specific usage object. Costs use `decimal.Decimal` (no float drift). Missing usage or
+unknown pricing degrade gracefully via the flags — tracking never raises on missing data.
+
+---
+
+## Architecture
+
+TokenHelm is built around five replaceable extension points; the core depends only on their
+interfaces, never on a concrete implementation.
+
+```
+            ┌──────────────────────────────────────────────────────────┐
+            │                     Your Application                       │
+            └───────────────────────────┬──────────────────────────────┘
+                                         │  track() / trace() / configure()
+                                         ▼
+                              ┌────────────────────┐
+                              │      TokenHelm      │   (sdk: client + TraceScope)
+                              └─────────┬──────────┘
+                                        ▼
+                              ┌────────────────────┐
+                              │    TokenTracker     │   builds the normalized LLMEvent
+                              └───┬────────────┬───┘
+                  extract usage  │            │  compute cost
+                                 ▼            ▼
+                   ┌──────────────────┐   ┌──────────────────┐
+                   │   BaseAdapter ①  │   │ CostCalculator   │
+                   │ OpenAI/Gemini/   │   └────────┬─────────┘
+                   │ Anthropic/Ollama │            ▼
+                   └──────────────────┘   ┌──────────────────┐
+                                          │ PricingProvider ② │  (YAML default)
+                                          └──────────────────┘
+                                        │
+                                        ▼  emit (tracker is unaware of sinks)
+                              ┌────────────────────┐
+                              │  EventDispatcher ③ │
+                              └───┬────────────┬───┘
+                                  ▼            ▼
+                        ┌──────────────┐  ┌──────────────────┐
+                        │   Logger ④   │  │ StorageBackend ⑤ │  (optional)
+                        │ Console/...  │  └──────────────────┘
+                        └──────────────┘
+```
+
+**Extension points** (all public & stable — Constitution Principle VI):
+
+| # | Interface | Default | Swap it to… |
+|---|-----------|---------|-------------|
+| ① | `BaseAdapter` | OpenAI, Gemini, Anthropic, Ollama | add a new provider |
+| ② | `PricingProvider` | `YamlPricingProvider` | remote/dynamic pricing, AI FinOps |
+| ③ | `EventDispatcher` | `DefaultEventDispatcher` | custom routing/batching/export |
+| ④ | `Logger` | `ConsoleLogger` | JSON/file/metrics/dashboards |
+| ⑤ | `StorageBackend` | none (opt-in) | in-memory/SQLite/warehouse/analytics |
+
+**Dependency direction is strictly one-way** (no reverse dependencies):
+
+```
+Application → TokenHelm → TokenTracker → EventDispatcher → Logger / StorageBackend
+                              └────────→ CostCalculator → PricingProvider
+                              └────────→ UsageParser → BaseAdapter
+```
+
+`CostCalculator` depends *only* on `PricingProvider`; `TokenTracker` emits *only* through
+`EventDispatcher`. Analytics, dashboards, and FinOps are downstream consumers of `LLMEvent`
+behind these interfaces — they require no change to the core.
+
+---
+
+## Supported Providers
+
+All four providers are supported, with streaming and async, in v0.1.0.
+
+| Provider | Status | Usage fields read |
+|----------|--------|-------------------|
+| **OpenAI** | ✅ supported | `usage.prompt_tokens` / `completion_tokens` (Chat); `input_tokens` / `output_tokens` (Responses) |
+| **Google Gemini** | ✅ supported | `usage_metadata.prompt_token_count` / `candidates_token_count` |
+| **Anthropic** | ✅ supported | `usage.input_tokens` / `output_tokens` (+ cache token extras) |
+| **Ollama** (local) | ✅ supported | `prompt_eval_count` / `eval_count` |
+
+All providers normalize into the **same** `LLMEvent` schema — switching providers is a
+configuration change, not a code change. Each adapter handles both completed responses and
+streaming.
+
+---
+
+## Roadmap
+
+**v0.1.0 — Core SDK ✅ (current)**
+
+- [x] Track usage and cost across one provider (MVP): cost calculation, normalized event,
+      scoped `trace()`, console logging, graceful degradation.
+- [x] Provider parity: OpenAI, Gemini, Anthropic, Ollama adapters; identical event shape.
+- [x] Output choice: `JSONLogger`, `FileLogger`, `InMemoryStorageBackend`, full `configure()`
+      and multi-sink dispatch.
+- [x] Streaming & async: `track_stream()` (one final event), async `trace()`.
+- [x] Hardening: <5 ms / <20 MB budgets, thread/async isolation suite, docs, packaging.
+
+**Beyond v0.1** — each tier is additive on the five extension points; the v0.1 core API does
+not change. See [`ROADMAP.md`](ROADMAP.md).
+
+- [ ] **v0.2 — Analytics SDK** (`SQLiteStorageBackend` + usage queries)
+- [ ] **v0.3 — Prompt Intelligence** (per-prompt/template attribution)
+- [ ] **v0.4 — RAG Intelligence** (retrieval-aware accounting)
+- [ ] **v0.5 — AI FinOps** (budgets, alerts, remote pricing)
+- [ ] **v1.0 — Enterprise Platform** (stabilize the v0.x surface; dashboard, plugins)
+
+---
+
+## Design principles
+
+Framework-agnostic · provider-independent · zero vendor lock-in · <5 ms overhead ·
+observe-don't-patch · one standardized event · everything replaceable.
+
+See `specs/001-core-sdk/` for the constitution, spec, plan, data model, and public API
+contract.
+
+## Release Process
+
+Releases follow a documented, automated procedure (Conventional Commits → release-please →
+Trusted Publishing on PyPI via OIDC). The canonical, end-to-end release procedure is the
+**[Go-Live & Release checklist](docs/go-live-checklist.md)** — follow it for every release.
+
+Supporting docs:
+
+- [`docs/releasing.md`](docs/releasing.md) — how publishing works (TestPyPI → PyPI, OIDC).
+- [`docs/repository-setup.md`](docs/repository-setup.md) — branch protection, required checks,
+  Dependabot, security features.
+- [`docs/release-checklist.md`](docs/release-checklist.md) — per-version quality gates.
+
+Contributors: see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev workflow, versioning, and
+deprecation policy.
+
+## License
+
+MIT
+

tokenhelm-0.1.0rc1/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tokenhelm"
+version = "0.1.0rc1"
+description = "Lightweight, framework-agnostic token tracking and LLM cost calculation across providers."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "TokenHelm contributors" }]
+keywords = ["llm", "tokens", "cost", "openai", "anthropic", "gemini", "ollama", "observability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+dependencies = ["PyYAML>=6.0"]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+gemini = ["google-genai>=0.1"]
+anthropic = ["anthropic>=0.40"]
+ollama = ["ollama>=0.1"]
+all = ["openai>=1.0", "google-genai>=0.1", "anthropic>=0.40", "ollama>=0.1"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23", "pytest-cov>=5.0", "ruff>=0.6", "build>=1.0"]
+
+[project.urls]
+Homepage = "https://github.com/quadkeys/tokenhelm"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tokenhelm = ["data/*.yaml", "py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+# UP042: LLMProvider deliberately subclasses (str, Enum) with an explicit __str__ for broad
+# compatibility and stable value semantics. Migrating to enum.StrEnum is a deferrable cleanup,
+# not done right before the v0.1 release (it changes a public type's base class).
+ignore = ["UP042"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov=tokenhelm --cov-report=term-missing --cov-fail-under=90"
+markers = ["benchmark: performance/memory budget checks (deselect with -m 'not benchmark')"]
+
+[tool.coverage.run]
+source = ["tokenhelm"]
+branch = true
+
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "semver"
+version_provider = "pep621"
+update_changelog_on_bump = false   # CHANGELOG is owned by release-please in CI
+major_version_zero = true

tokenhelm-0.1.0rc1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tokenhelm-0.1.0rc1/src/tokenhelm/__init__.py

@@ -0,0 +1,82 @@
+"""TokenHelm — lightweight, framework-agnostic LLM token tracking and cost calculation.
+
+Public surface per ``specs/001-core-sdk/contracts/public-api.md``. Names exported here are the
+v0.x stable contract (Principle X). This slice (User Story 1) ships the OpenAI vertical;
+additional providers, loggers, storage, and streaming land in later phases.
+"""
+
+from __future__ import annotations
+
+# Errors
+# Extension-point interfaces (Principle VI)
+from .adapters.anthropic import AnthropicAdapter
+from .adapters.base import BaseAdapter, StreamAggregator
+from .adapters.gemini import GeminiAdapter
+from .adapters.ollama import OllamaAdapter
+from .adapters.openai import OpenAIAdapter
+from .core.calculator import CostCalculator
+from .core.errors import ProviderNotInstalledError, TokenHelmError
+
+# Core data model
+from .core.models import (
+    LLMCost,
+    LLMEvent,
+    LLMProvider,
+    LLMRequest,
+    LLMUsage,
+    RateEntry,
+)
+from .dispatch.base import EventDispatcher
+from .dispatch.default import DefaultEventDispatcher
+from .logging.base import Logger
+from .logging.console import ConsoleLogger
+from .logging.file import FileLogger
+from .logging.json import JSONLogger
+from .pricing.base import PricingProvider
+from .pricing.yaml_provider import YamlPricingProvider
+
+# Client + scope
+from .sdk.client import TokenHelm
+from .sdk.context import StreamSession, TraceScope
+from .storage.base import StorageBackend
+from .storage.memory import InMemoryStorageBackend
+
+__version__ = "0.1.0rc1"  # x-release-please-version
+
+__all__ = [
+    "__version__",
+    # client
+    "TokenHelm",
+    "TraceScope",
+    "StreamSession",
+    # event + enum
+    "LLMEvent",
+    "LLMProvider",
+    "LLMUsage",
+    "LLMCost",
+    "LLMRequest",
+    "RateEntry",
+    # interfaces
+    "BaseAdapter",
+    "StreamAggregator",
+    "PricingProvider",
+    "EventDispatcher",
+    "Logger",
+    "StorageBackend",
+    # built-in adapters
+    "OpenAIAdapter",
+    "AnthropicAdapter",
+    "GeminiAdapter",
+    "OllamaAdapter",
+    # default implementations
+    "YamlPricingProvider",
+    "DefaultEventDispatcher",
+    "ConsoleLogger",
+    "JSONLogger",
+    "FileLogger",
+    "InMemoryStorageBackend",
+    "CostCalculator",
+    # errors
+    "TokenHelmError",
+    "ProviderNotInstalledError",
+]

tokenhelm-0.1.0rc1/src/tokenhelm/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""Provider adapters (extension point #1).
+
+``default_adapters()`` is the built-in adapter set the client registers by default. It lives
+here (not in ``core``) so the core stays decoupled from concrete adapter implementations —
+``core.extraction.UsageParser`` depends only on :class:`BaseAdapter`.
+"""
+
+from __future__ import annotations
+
+from .base import BaseAdapter
+
+
+def default_adapters() -> list[BaseAdapter]:
+    """Built-in adapters, in resolution order (US1 ships OpenAI; US2 adds the rest)."""
+    from .anthropic import AnthropicAdapter
+    from .gemini import GeminiAdapter
+    from .ollama import OllamaAdapter
+    from .openai import OpenAIAdapter
+
+    return [OpenAIAdapter(), AnthropicAdapter(), GeminiAdapter(), OllamaAdapter()]