tokenjam 0.3.0__tar.gz → 0.3.2__tar.gz

tokenjam-0.3.2/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: tokenjam
+Version: 0.3.2
+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.2/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.0 → tokenjam-0.3.2}/docs/configuration.md

@@ -90,7 +90,7 @@ Set limits via CLI (`tj budget --daily 10`), the REST API (`POST /api/v1/budget`
 
 ## Content capture and privacy
 
-By default, `tj` does not capture prompt content, completion content, or tool inputs/outputs — only token counts, model names, tool names, timestamps, and structural metadata. Enable content capture selectively when you need it (for debugging, prompt-bloat analysis, or evaluation):
+By default, `tj` does not capture prompt content, completion content, or tool inputs/outputs — only token counts, model names, tool names, timestamps, and structural metadata. Enable content capture selectively when you need it (for debugging, trim analysis, or evaluation):
 
 ```toml
 [capture]
@@ -108,9 +108,9 @@ The four flags are independent: capture prompts without completions, or tool inp
 
 **What this means for downstream analyzers.**
 
-- `tj optimize --finding cache-efficacy` reads token-count fields and works without content capture.
-- `tj optimize --finding prompt-bloat` reads prompt text and requires `capture.prompts = true`.
-- `tj optimize --finding cache-recommend` reads prompts and requires `capture.prompts = true`.
+- `tj optimize cache` reads token-count fields and works without content capture.
+- `tj optimize trim` reads prompt text and requires `capture.prompts = true`.
+- `tj optimize cache-recommend` reads prompts and requires `capture.prompts = true`.
 
 The analyzers that need content fail with a clear message ("set `capture.prompts = true` in tj.toml and let the daemon collect a fresh window of data") rather than running on partial data.
 

{tokenjam-0.3.0 → tokenjam-0.3.2}/docs/installation.md

@@ -27,7 +27,7 @@ TokenJam keeps heavyweight ML dependencies, framework adapters, and the MCP serv
 | Extra | What it pulls in | Why it's optional |
 |---|---|---|
 | `tokenjam[mcp]` | `fastmcp` | Only needed for the Claude Code / Codex MCP server (`tj mcp`). Pulled by `tj onboard --claude-code` automatically when invoked through the documented one-liner. |
-| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize --finding prompt-bloat`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install means `pip install tokenjam` stays small and fast on machines that don't have a GPU/CPU build of torch already. |
+| `tokenjam[bloat]` | `llmlingua>=0.2`, transitively PyTorch + transformers (~2GB) | The Trim analyzer (`tj optimize trim`) scores token significance with LLMLingua-2. Most users don't run it; keeping torch out of the base install means `pip install tokenjam` stays small and fast on machines that don't have a GPU/CPU build of torch already. |
 | `tokenjam[langchain]` | `langchain>=0.2` | Convenience pin for `patch_langchain()`; you can also install langchain yourself. |
 | `tokenjam[crewai]` | `crewai>=0.28` | Convenience pin for `patch_crewai()`. |
 | `tokenjam[autogen]` | `pyautogen>=0.2` | Convenience pin for `patch_autogen()`. |
@@ -44,7 +44,7 @@ pip install "tokenjam[mcp,bloat]"
 
 `tokenjam[bloat]` is the largest extra — LLMLingua-2 transitively pulls in PyTorch and Hugging Face transformers, roughly 2GB on disk. On first run the analyzer downloads a ~110MB BERT-class classifier model under `~/.cache/tokenjam/models/` (override via `TOKENJAM_MODEL_CACHE`); subsequent runs are offline-capable.
 
-If you run `tj optimize --finding prompt-bloat` without the extra installed, the analyzer self-registers and exits with a clear hint pointing at this install command — nothing in the base install crashes from its absence.
+If you run `tj optimize trim` without the extra installed, the analyzer self-registers and exits with a clear hint pointing at this install command — nothing in the base install crashes from its absence.
 
 See [`docs/optimize/trim.md`](optimize/trim.md) for performance numbers, capture requirements, and what the analyzer actually reports.
 

{tokenjam-0.3.0 → tokenjam-0.3.2}/docs/optimize/cache.md

@@ -1,13 +1,13 @@
 # Cache
 
-Product name: **Cache**. Internal/CLI names: `cache-efficacy` and `cache-recommend`. Two related findings under the same product — both surface prompt-caching opportunities; they differ in what they need and what they recommend.
+Product name: **Cache**. Internal/CLI names: `cache` and `cache-recommend`. Two related findings under the same product — both surface prompt-caching opportunities; they differ in what they need and what they recommend.
 
 ```bash
-tj optimize --finding cache-efficacy
-tj optimize --finding cache-recommend
+tj optimize cache
+tj optimize cache-recommend
 ```
 
-## `cache-efficacy` — measure current caching
+## `cache` — measure current caching
 
 Reads aggregate `input_tokens` and `cache_tokens` from spans in the
 window. Computes the share of input bytes served from cache per

{tokenjam-0.3.0 → tokenjam-0.3.2}/docs/optimize/downsize.md

@@ -1,9 +1,9 @@
 # Downsize
 
-Product name: **Downsize**. Internal/CLI name: `model-downgrade`.
+Product name: **Downsize**. Internal/CLI name: `downsize`.
 
 ```bash
-tj optimize --finding model-downgrade
+tj optimize downsize
 ```
 
 Flags sessions whose structural shape — short input (< 5K tokens), short output (< 500 tokens), few tool calls (≤ 5) — matches a class of work where a cheaper model in the same provider family is worth reviewing.
@@ -37,7 +37,7 @@ JSON output mirrors the same data with top-level `plan` and `pricing_mode` field
 
 ## Confidence
 
-`structural`. The model-downgrade finding identifies a structural pattern in the captured data; it does not validate that the cheaper model would produce equivalent output. The mandatory caveat is the honest framing of that limitation.
+`structural`. The downsize finding identifies a structural pattern in the captured data; it does not validate that the cheaper model would produce equivalent output. The mandatory caveat is the honest framing of that limitation.
 
 ## See also
 

{tokenjam-0.3.0 → tokenjam-0.3.2}/docs/optimize/script.md

@@ -1,9 +1,9 @@
 # Script
 
-Product name: **Script**. Internal/CLI name: `workflow-restructure`.
+Product name: **Script**. Internal/CLI name: `script`.
 
 ```bash
-tj optimize --finding workflow-restructure
+tj optimize script
 ```
 
 Flags sessions whose tool-call sequence is structurally identical

{tokenjam-0.3.0 → tokenjam-0.3.2}/docs/optimize/trim.md

@@ -1,9 +1,9 @@
 # Trim
 
-Product name: **Trim**. Internal/CLI name: `prompt-bloat`.
+Product name: **Trim**. Internal/CLI name: `trim`.
 
 ```bash
-tj optimize --finding prompt-bloat
+tj optimize trim
 ```
 
 Scores token-by-token significance in captured prompts using
@@ -26,7 +26,7 @@ pip install "tokenjam[bloat]"
 ```
 
 The base `pip install tokenjam` does NOT pull torch. Trim shows up in
-`tj optimize --finding` choices regardless, but running it without the
+`tj optimize` analyzer choices regardless, but running it without the
 extra prints a clear install hint and exits.
 
 ## Requirements
@@ -56,10 +56,10 @@ marked.
 ## HTML report
 
 ```bash
-tj report --bloat                # all agents, 30d window
-tj report --bloat my-agent       # scope to one agent
-tj report --bloat --since 7d     # custom window
-tj report --bloat --no-open      # write file without opening browser
+tj report --trim                # all agents, 30d window
+tj report --trim my-agent       # scope to one agent
+tj report --trim --since 7d     # custom window
+tj report --trim --no-open      # write file without opening browser
 ```
 
 Output goes to `~/.cache/tokenjam/reports/trim-<timestamp>.html` and