tokenjam 0.3.1__tar.gz → 0.3.3__tar.gz

{tokenjam-0.3.1 → tokenjam-0.3.3}/CLAUDE.md

@@ -191,9 +191,9 @@ The Agent Incident Library at `incidents/` is separate: each scenario is a `scen
 
 ## Pricing
 
-Model pricing lives in `pricing/models.toml` (USD per million tokens). Structure: `[provider.model_name]` with `input_per_mtok`, `output_per_mtok`, and optional `cache_read_per_mtok`/`cache_write_per_mtok`. Unknown models fall back to default rates ($0.50/$2.00 per MTok) with a logged warning. The pricing table is LRU-cached at process startup — restart to pick up changes.
+Model pricing lives in `tokenjam/pricing/models.toml` (USD per million tokens) — the packaged file `core/pricing.py` loads via `PRICING_FILE = Path(__file__).parent.parent / "pricing" / "models.toml"`. There is no repo-root `pricing/` copy (it was moved into the package in v0.1.x so it ships in the wheel; editing a repo-root file would have no runtime effect). Structure: `[provider.model_name]` with `input_per_mtok`, `output_per_mtok`, and optional `cache_read_per_mtok`/`cache_write_per_mtok`. Unknown models fall back to default rates ($0.50/$2.00 per MTok) with a logged warning. The pricing table is LRU-cached at process startup — restart to pick up changes.
 
-Pricing is community-maintained: submit a PR editing `pricing/models.toml` when provider prices change. No code changes needed — the file is loaded at runtime.
+Pricing is community-maintained: submit a PR editing `tokenjam/pricing/models.toml` when provider prices change. No code changes needed — the file is loaded at runtime.
 
 ## CI
 

{tokenjam-0.3.1 → tokenjam-0.3.3}/CONTRIBUTING.md

@@ -43,7 +43,7 @@ tokenjam/sdk/               @watch() decorator and provider/framework patches
 tokenjam/otel/              OTel TracerProvider and span exporter wiring
 tokenjam/utils/             Formatting, time parsing, ID generation
 sdk-ts/src/            TypeScript SDK (@tokenjam/sdk)
-pricing/models.toml    Community-maintained model pricing — PRs welcome here
+tokenjam/pricing/models.toml  Community-maintained model pricing — PRs welcome here
 tests/factories.py     Span factory — use this in all synthetic tests, never
                        construct NormalizedSpan directly
 ```
@@ -57,7 +57,7 @@ This project was built using parallel Claude Code agents. The `.claude/` directo
 
 ## Pricing table contributions
 
-The file `pricing/models.toml` is intentionally community-maintained. If a model is missing or prices have changed, open a PR with the update — no issue needed, just update the TOML and verify the format matches existing entries.
+The file `tokenjam/pricing/models.toml` is intentionally community-maintained. If a model is missing or prices have changed, open a PR with the update — no issue needed, just update the TOML and verify the format matches existing entries. (This is the file the cost engine loads at runtime; there is no separate repo-root copy.)
 
 ## Reporting issues
 

tokenjam-0.3.3/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: tokenjam
+Version: 0.3.3
+Summary: TokenJam — local-first OTel-native observability for Autonomous AI agents
+Project-URL: Homepage, https://opencla.watch
+Project-URL: Repository, https://github.com/Metabuilder-Labs/openclawwatch
+Project-URL: Issues, https://github.com/Metabuilder-Labs/openclawwatch/issues
+Author-email: Anil Murty <anil@metabldr.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,llm,observability,opentelemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Requires-Dist: apscheduler>=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: duckdb>=0.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: genson>=1.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.25
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25
+Requires-Dist: opentelemetry-exporter-prometheus>=0.46b0
+Requires-Dist: opentelemetry-sdk>=1.25
+Requires-Dist: pytz>=2024.1
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: autogen
+Requires-Dist: pyautogen>=0.2; extra == 'autogen'
+Provides-Extra: bloat
+Requires-Dist: llmlingua>=0.2; extra == 'bloat'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.2; extra == 'langchain'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.40; extra == 'litellm'
+Provides-Extra: mcp
+Requires-Dist: fastmcp; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://tokenjam.dev/icon.svg" alt="TokenJam" width="72" height="72">
+
+# TokenJam
+
+### Token Efficiency For AI Agents
+
+TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, and what to script. The result is a lower AI bill. Runs entirely on your machine.
+
+[![CI](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml/badge.svg)](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
+[![OTel](https://img.shields.io/badge/OTel-GenAI%20SemConv-3d8eff?labelColor=0d1117)](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+
+```
+pip install tokenjam
+```
+
+**No cloud · No signup · No vendor lock-in**
+
+</div>
+
+---
+
+## Four Analyzers. One Install.
+
+TokenJam reads telemetry from every major agent runtime, framework, provider, and observability tool and surfaces savings across four areas.
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🪶 Downsize
+
+Flags sessions where a cheaper model in the same family is worth a look. Never claims quality equivalence — surfaces examples so you can spot-check.
+
+<pre><code>tj optimize downsize</code></pre>
+
+[Details →](docs/optimize/downsize.md)
+
+</td>
+<td width="50%" valign="top">
+
+### 💾 Cache
+
+Shows your current caching ratio per (provider, model) and suggests Anthropic prompt-cache breakpoints from stable prefixes in your real usage.
+
+<pre><code>tj optimize cache</code></pre>
+
+[Details →](docs/optimize/cache.md)
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 📜 Script
+
+Finds clusters of deterministic `(tool_name, arg_shape)` sequences that match the shape of work a plain script could replace.
+
+<pre><code>tj optimize script</code></pre>
+
+[Details →](docs/optimize/script.md)
+
+</td>
+<td width="50%" valign="top">
+
+### ✂️ Trim
+
+Predicts which regions of your prompts the model gives little weight to. Surfaces what's safe to cut.
+
+<pre><code>tj optimize trim</code></pre>
+
+[Details →](docs/optimize/trim.md)
+
+</td>
+</tr>
+</table>
+
+Run all four with `tj optimize`. Run several with `tj optimize downsize cache trim`.
+
+---
+
+## 30-second quickstart
+
+For **Claude Code** users — zero code, auto-backfills your last 30 days:
+
+```bash
+pip install "tokenjam[mcp]"
+tj onboard --claude-code
+tj optimize          # cost-saving candidates from your actual usage
+```
+
+For any Python agent:
+
+```python
+from tokenjam.sdk import watch
+from tokenjam.sdk.integrations.anthropic import patch_anthropic
+
+patch_anthropic()
+
+@watch(agent_id="my-agent")
+def run(task: str) -> str:
+    ...
+```
+
+→ [Python SDK](docs/python-sdk.md) · [TypeScript SDK](docs/typescript-sdk.md) · [Codex](docs/claude-code-integration.md#codex) · [OTel-compatible agents](docs/framework-support.md)
+
+---
+
+## Why local-first matters
+
+Your spans contain prompts, completions, tool inputs, and customer data. Shipping that to a SaaS vendor for "observability" is a data-egress decision most teams aren't ready to make.
+
+|                                            | TokenJam | LangSmith | Langfuse | Datadog LLM Obs |
+|---|---|---|---|---|
+| Signup required                            | ❌       | ✅        | ✅       | ✅              |
+| Data leaves your machine                   | ❌       | ✅        | cloud only | ✅           |
+| Cost-optimization analyzers (Downsize, Cache, Script, Trim) | ✅ | ❌ | ❌ | ❌ |
+| Real-time sensitive-action alerts          | ✅       | ❌        | ❌       | ❌              |
+| Behavioral drift detection                 | ✅       | ❌        | ❌       | ❌              |
+| OTel GenAI SemConv native                  | ✅       | partial   | partial  | partial         |
+| Works with any agent / framework           | ✅       | LangChain-first | partial | ❌            |
+| Free, MIT licensed                         | ✅       | freemium  | freemium | paid            |
+
+---
+
+## Web UI
+
+`tj serve` runs a local dashboard at `http://127.0.0.1:7391/` with status, traces, cost breakdown, alerts, budget, and drift.
+
+<table>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-status.png" alt="tj status page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="tj cost page" /></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="tj traces page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-alerts.png" alt="tj alerts page" /></td>
+</tr>
+</table>
+
+---
+
+## Beyond optimization
+
+TokenJam is also a full observability stack. The four analyzers ride on top.
+
+- **Real-time cost tracking** — every LLM call priced as it happens
+- **Safety alerts** — 13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, file, stdout)
+- **Behavioral drift detection** — Z-score baselines, no LLM required
+- **Schema validation** — declare or infer JSON Schema for tool outputs
+- **OTel-native** — point any OTLP exporter at `tj serve` and you're done
+- **MCP server** — 14 tools letting Claude Code query its own telemetry mid-session
+
+---
+
+## CLI
+
+```bash
+tj optimize            # all four cost-optimization analyzers
+tj optimize downsize   # one analyzer
+tj status              # current cost, tokens, active alerts
+tj cost --since 7d     # spend by agent / model / day / tool
+tj alerts              # everything that fired while you were away
+tj drift               # behavioral drift Z-scores
+tj backfill claude-code # ingest historical ~/.claude/projects/ sessions
+tj serve               # start the web UI + REST API
+```
+
+[Full CLI reference →](docs/cli-reference.md)
+
+---
+
+## Documentation
+
+| Topic | Where |
+|---|---|
+| 🪶 Downsize / Cache / Script / Trim deep-dives | [docs/optimize/](docs/optimize/) |
+| Claude Code & Codex integration | [docs/claude-code-integration.md](docs/claude-code-integration.md) |
+| Python SDK reference | [docs/python-sdk.md](docs/python-sdk.md) |
+| TypeScript SDK reference | [docs/typescript-sdk.md](docs/typescript-sdk.md) |
+| Framework support (LangChain / CrewAI / etc.) | [docs/framework-support.md](docs/framework-support.md) |
+| Alert channels & rule reference | [docs/alerts.md](docs/alerts.md) |
+| Backfill from Langfuse / Helicone / OTLP | [docs/backfill/](docs/backfill/) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Architecture deep-dive | [docs/architecture.md](docs/architecture.md) |
+| Installation extras (Trim, framework patches) | [docs/installation.md](docs/installation.md) |
+| Export to Grafana / Datadog / NDJSON | [docs/export.md](docs/export.md) |
+| NemoClaw sandbox observer | [docs/nemoclaw-integration.md](docs/nemoclaw-integration.md) |
+
+---
+
+## Roadmap
+
+**Shipped in 0.3.x:** Downsize · Cache · Script · Trim · Claude Code + Codex onboarding · MCP server · Web UI · Backfill adapters (Langfuse, Helicone, OTLP) · Period comparison · Routing-config export · Read-only policy preview
+
+**Up next:**
+- [ ] `tj policy add | edit | apply` — unified rule surface
+- [ ] `tj replay` — replay captured sessions against new model versions
+- [ ] TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
+- [ ] Vercel AI SDK & Mastra integrations
+- [ ] Docker image
+- [ ] GitHub Actions for CI drift/cost checks
+
+---
+
+<div align="center">
+
+**[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)
+
+MIT License · Built by [Metabuilder Labs](https://github.com/Metabuilder-Labs)
+
+</div>

tokenjam-0.3.3/README.md

@@ -0,0 +1,217 @@
+<div align="center">
+
+<img src="https://tokenjam.dev/icon.svg" alt="TokenJam" width="72" height="72">
+
+# TokenJam
+
+### Token Efficiency For AI Agents
+
+TokenJam reads your agent's telemetry and tells you when to downsize, when to trim prompts, what to cache, and what to script. The result is a lower AI bill. Runs entirely on your machine.
+
+[![CI](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml/badge.svg)](https://github.com/Metabuilder-Labs/tokenjam/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenjam?color=3d8eff&labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3d8eff?labelColor=0d1117)](https://pypi.org/project/tokenjam/)
+[![npm](https://img.shields.io/npm/v/@tokenjam/sdk?color=3d8eff&labelColor=0d1117)](https://www.npmjs.com/package/@tokenjam/sdk)
+[![License: MIT](https://img.shields.io/badge/license-MIT-3d8eff?labelColor=0d1117)](LICENSE)
+[![OTel](https://img.shields.io/badge/OTel-GenAI%20SemConv-3d8eff?labelColor=0d1117)](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
+
+```
+pip install tokenjam
+```
+
+**No cloud · No signup · No vendor lock-in**
+
+</div>
+
+---
+
+## Four Analyzers. One Install.
+
+TokenJam reads telemetry from every major agent runtime, framework, provider, and observability tool and surfaces savings across four areas.
+
+<table>
+<tr>
+<td width="50%" valign="top">
+
+### 🪶 Downsize
+
+Flags sessions where a cheaper model in the same family is worth a look. Never claims quality equivalence — surfaces examples so you can spot-check.
+
+<pre><code>tj optimize downsize</code></pre>
+
+[Details →](docs/optimize/downsize.md)
+
+</td>
+<td width="50%" valign="top">
+
+### 💾 Cache
+
+Shows your current caching ratio per (provider, model) and suggests Anthropic prompt-cache breakpoints from stable prefixes in your real usage.
+
+<pre><code>tj optimize cache</code></pre>
+
+[Details →](docs/optimize/cache.md)
+
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top">
+
+### 📜 Script
+
+Finds clusters of deterministic `(tool_name, arg_shape)` sequences that match the shape of work a plain script could replace.
+
+<pre><code>tj optimize script</code></pre>
+
+[Details →](docs/optimize/script.md)
+
+</td>
+<td width="50%" valign="top">
+
+### ✂️ Trim
+
+Predicts which regions of your prompts the model gives little weight to. Surfaces what's safe to cut.
+
+<pre><code>tj optimize trim</code></pre>
+
+[Details →](docs/optimize/trim.md)
+
+</td>
+</tr>
+</table>
+
+Run all four with `tj optimize`. Run several with `tj optimize downsize cache trim`.
+
+---
+
+## 30-second quickstart
+
+For **Claude Code** users — zero code, auto-backfills your last 30 days:
+
+```bash
+pip install "tokenjam[mcp]"
+tj onboard --claude-code
+tj optimize          # cost-saving candidates from your actual usage
+```
+
+For any Python agent:
+
+```python
+from tokenjam.sdk import watch
+from tokenjam.sdk.integrations.anthropic import patch_anthropic
+
+patch_anthropic()
+
+@watch(agent_id="my-agent")
+def run(task: str) -> str:
+    ...
+```
+
+→ [Python SDK](docs/python-sdk.md) · [TypeScript SDK](docs/typescript-sdk.md) · [Codex](docs/claude-code-integration.md#codex) · [OTel-compatible agents](docs/framework-support.md)
+
+---
+
+## Why local-first matters
+
+Your spans contain prompts, completions, tool inputs, and customer data. Shipping that to a SaaS vendor for "observability" is a data-egress decision most teams aren't ready to make.
+
+|                                            | TokenJam | LangSmith | Langfuse | Datadog LLM Obs |
+|---|---|---|---|---|
+| Signup required                            | ❌       | ✅        | ✅       | ✅              |
+| Data leaves your machine                   | ❌       | ✅        | cloud only | ✅           |
+| Cost-optimization analyzers (Downsize, Cache, Script, Trim) | ✅ | ❌ | ❌ | ❌ |
+| Real-time sensitive-action alerts          | ✅       | ❌        | ❌       | ❌              |
+| Behavioral drift detection                 | ✅       | ❌        | ❌       | ❌              |
+| OTel GenAI SemConv native                  | ✅       | partial   | partial  | partial         |
+| Works with any agent / framework           | ✅       | LangChain-first | partial | ❌            |
+| Free, MIT licensed                         | ✅       | freemium  | freemium | paid            |
+
+---
+
+## Web UI
+
+`tj serve` runs a local dashboard at `http://127.0.0.1:7391/` with status, traces, cost breakdown, alerts, budget, and drift.
+
+<table>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-status.png" alt="tj status page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-cost.png" alt="tj cost page" /></td>
+</tr>
+<tr>
+<td width="50%"><img src="docs/screenshots/tj-traces.png" alt="tj traces page" /></td>
+<td width="50%"><img src="docs/screenshots/tj-alerts.png" alt="tj alerts page" /></td>
+</tr>
+</table>
+
+---
+
+## Beyond optimization
+
+TokenJam is also a full observability stack. The four analyzers ride on top.
+
+- **Real-time cost tracking** — every LLM call priced as it happens
+- **Safety alerts** — 13 alert types, 6 channels (ntfy, Discord, Telegram, webhook, file, stdout)
+- **Behavioral drift detection** — Z-score baselines, no LLM required
+- **Schema validation** — declare or infer JSON Schema for tool outputs
+- **OTel-native** — point any OTLP exporter at `tj serve` and you're done
+- **MCP server** — 14 tools letting Claude Code query its own telemetry mid-session
+
+---
+
+## CLI
+
+```bash
+tj optimize            # all four cost-optimization analyzers
+tj optimize downsize   # one analyzer
+tj status              # current cost, tokens, active alerts
+tj cost --since 7d     # spend by agent / model / day / tool
+tj alerts              # everything that fired while you were away
+tj drift               # behavioral drift Z-scores
+tj backfill claude-code # ingest historical ~/.claude/projects/ sessions
+tj serve               # start the web UI + REST API
+```
+
+[Full CLI reference →](docs/cli-reference.md)
+
+---
+
+## Documentation
+
+| Topic | Where |
+|---|---|
+| 🪶 Downsize / Cache / Script / Trim deep-dives | [docs/optimize/](docs/optimize/) |
+| Claude Code & Codex integration | [docs/claude-code-integration.md](docs/claude-code-integration.md) |
+| Python SDK reference | [docs/python-sdk.md](docs/python-sdk.md) |
+| TypeScript SDK reference | [docs/typescript-sdk.md](docs/typescript-sdk.md) |
+| Framework support (LangChain / CrewAI / etc.) | [docs/framework-support.md](docs/framework-support.md) |
+| Alert channels & rule reference | [docs/alerts.md](docs/alerts.md) |
+| Backfill from Langfuse / Helicone / OTLP | [docs/backfill/](docs/backfill/) |
+| Configuration | [docs/configuration.md](docs/configuration.md) |
+| Architecture deep-dive | [docs/architecture.md](docs/architecture.md) |
+| Installation extras (Trim, framework patches) | [docs/installation.md](docs/installation.md) |
+| Export to Grafana / Datadog / NDJSON | [docs/export.md](docs/export.md) |
+| NemoClaw sandbox observer | [docs/nemoclaw-integration.md](docs/nemoclaw-integration.md) |
+
+---
+
+## Roadmap
+
+**Shipped in 0.3.x:** Downsize · Cache · Script · Trim · Claude Code + Codex onboarding · MCP server · Web UI · Backfill adapters (Langfuse, Helicone, OTLP) · Period comparison · Routing-config export · Read-only policy preview
+
+**Up next:**
+- [ ] `tj policy add | edit | apply` — unified rule surface
+- [ ] `tj replay` — replay captured sessions against new model versions
+- [ ] TypeScript framework patches (LangChain JS, OpenAI Agents SDK)
+- [ ] Vercel AI SDK & Mastra integrations
+- [ ] Docker image
+- [ ] GitHub Actions for CI drift/cost checks
+
+---
+
+<div align="center">
+
+**[tokenjam.dev](https://tokenjam.dev)** · [PyPI](https://pypi.org/project/tokenjam/) · [npm](https://www.npmjs.com/package/@tokenjam/sdk) · [Issues](https://github.com/Metabuilder-Labs/tokenjam/issues)
+
+MIT License · Built by [Metabuilder Labs](https://github.com/Metabuilder-Labs)
+
+</div>

tokenjam-0.3.3/docs/python-sdk.md

@@ -0,0 +1,79 @@
+# Python SDK
+
+For any Python agent — Anthropic, OpenAI, Gemini, Bedrock, LangChain, CrewAI, and 10+ more frameworks.
+
+## Install
+
+```bash
+pip install tokenjam
+tj onboard    # creates config, generates ingest secret
+tj doctor     # verify your setup
+```
+
+## Quick start
+
+```python
+from tokenjam.sdk import watch
+from tokenjam.sdk.integrations.anthropic import patch_anthropic
+
+patch_anthropic()    # auto-intercepts all Anthropic API calls
+
+@watch(agent_id="my-agent")
+def run(task: str) -> str:
+    # your agent code — nothing else to change
+    ...
+```
+
+## Provider patches
+
+Intercept at the API level. Framework-agnostic.
+
+```python
+from tokenjam.sdk.integrations.anthropic import patch_anthropic   # Anthropic
+from tokenjam.sdk.integrations.openai    import patch_openai      # OpenAI
+from tokenjam.sdk.integrations.gemini    import patch_gemini      # Google Gemini
+from tokenjam.sdk.integrations.bedrock   import patch_bedrock     # AWS Bedrock
+from tokenjam.sdk.integrations.litellm   import patch_litellm     # LiteLLM (100+ providers)
+```
+
+`patch_litellm()` covers all providers LiteLLM routes to (OpenAI, Anthropic, Bedrock, Vertex, Cohere, Mistral, Ollama, etc.). If you use LiteLLM, you don't need individual patches.
+
+OpenAI-compatible providers (Groq, Together, Fireworks, xAI, Azure OpenAI) work via `patch_openai(base_url=...)`.
+
+## Framework patches
+
+Instrument the framework's own abstractions:
+
+```python
+from tokenjam.sdk.integrations.langchain         import patch_langchain        # BaseLLM + BaseTool
+from tokenjam.sdk.integrations.langgraph         import patch_langgraph        # CompiledGraph
+from tokenjam.sdk.integrations.crewai            import patch_crewai           # Task + Agent
+from tokenjam.sdk.integrations.autogen           import patch_autogen          # ConversableAgent
+from tokenjam.sdk.integrations.llamaindex        import patch_llamaindex       # Native OTel
+from tokenjam.sdk.integrations.openai_agents_sdk import patch_openai_agents    # Native OTel
+from tokenjam.sdk.integrations.nemoclaw          import watch_nemoclaw         # NemoClaw Gateway
+```
+
+Full framework support guide: [docs/framework-support.md](framework-support.md)
+
+## Manual instrumentation
+
+If you can't (or don't want to) use a patch, record spans manually:
+
+```python
+from tokenjam.sdk.agent import record_llm_call, record_tool_call
+
+record_llm_call(
+    agent_id="my-agent", provider="anthropic", model="claude-opus-4-7",
+    input_tokens=450, output_tokens=120, duration_ms=1200,
+)
+
+record_tool_call(
+    agent_id="my-agent", tool_name="send_email", duration_ms=300,
+    success=True,
+)
+```
+
+## Examples
+
+The [`examples/`](../examples/) directory has runnable agents for every integration. See [`examples/README.md`](../examples/README.md) for the full list.

tokenjam-0.3.3/docs/typescript-sdk.md

@@ -0,0 +1,73 @@
+# TypeScript SDK
+
+For any Node.js / TypeScript agent. Sends spans to `tj serve` over HTTP — no in-process state, no patches.
+
+## Install
+
+```bash
+npm install @tokenjam/sdk
+```
+
+`tj serve` must be running locally for the SDK to send spans. Set `TJ_INGEST_SECRET` to the secret from `~/.config/tj/config.toml`.
+
+## Quick start
+
+```typescript
+import { TjClient, SpanBuilder } from "@tokenjam/sdk";
+
+const client = new TjClient({
+  baseUrl:      "http://127.0.0.1:7391",
+  ingestSecret: process.env.TJ_INGEST_SECRET ?? "",
+});
+
+const span = new SpanBuilder("invoke_agent")
+  .agentId("my-ts-agent")
+  .model("gpt-4o-mini")
+  .provider("openai")
+  .inputTokens(450)
+  .outputTokens(120)
+  .build();
+
+await client.send([span]);
+```
+
+## Sessions
+
+For long-running agent sessions, use `startSession` / `endSession`:
+
+```typescript
+const session = await client.startSession({ agentId: "my-ts-agent" });
+
+// ... agent runs, sends spans tagged with session.id ...
+
+await client.endSession(session.id);
+```
+
+## Span builder
+
+`SpanBuilder` follows the OTel GenAI semantic conventions:
+
+```typescript
+new SpanBuilder("invoke_agent")
+  .agentId("agent-1")
+  .sessionId("sess-abc")
+  .provider("anthropic")
+  .model("claude-opus-4-7")
+  .inputTokens(450)
+  .outputTokens(120)
+  .cacheReadTokens(0)
+  .cacheWriteTokens(0)
+  .durationMs(1200)
+  .attribute("custom.key", "value")
+  .build();
+```
+
+## Errors and retries
+
+The client buffers up to 1000 spans if `tj serve` is unreachable, retries with exponential backoff (3 attempts, 2s base delay), and drops the buffer on process exit.
+
+On `401 Unauthorized`, the client fails fast (no retries) and logs the configured secret fingerprint so you can spot a mismatch with the daemon's secret.
+
+## API
+
+Full type signatures and parameter docs: see [`sdk-ts/README.md`](../sdk-ts/README.md).

{tokenjam-0.3.1 → tokenjam-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tokenjam"
-version = "0.3.1"
+version = "0.3.3"
 description = "TokenJam — local-first OTel-native observability for Autonomous AI agents"
 readme = "README.md"
 requires-python = ">=3.10"