llm-usage-metrics 0.3.5 → 0.3.7

package/README.md

@@ -29,8 +29,9 @@ Aggregate token usage and costs from your local coding agent sessions. Supports
 - **LiteLLM Pricing** — Real-time pricing sync with offline caching support
 - **Flexible Reports** — Daily, weekly, and monthly aggregations
 - **Efficiency Reports** — Correlate cost/tokens with repository commit outcomes
+- **Optimize Reports** — Counterfactual candidate-model pricing against observed token mix
 - **Multiple Outputs** — Terminal tables, JSON, or Markdown
-- **Smart Filtering** — By source, provider, model, and date ranges
+- **Smart Filtering** — By source, billing provider, model, and date ranges
 
 ## 🚀 Quick Start
 
@@ -63,6 +64,8 @@ llm-usage daily
 
 OpenCode source support requires Node.js 24+ runtime with built-in `node:sqlite`.
 
+For `droid`, `Input`, `Output`, `Reasoning`, `Cache Read`, and `Cache Write` come directly from session files, and `totalTokens` is billable raw tokens (`Input + Output + Cache Read + Cache Write`, excluding `Reasoning`). Factory dashboard totals may differ because Factory applies standard-token normalization/multipliers.
+
 ## 🎯 Usage
 
 ### Basic Reports
@@ -132,6 +135,18 @@ llm-usage efficiency monthly --repo-dir /path/to/repo --source opencode
 
 Note: usage filters (`--source`, `--provider`, `--model`, `--pi-dir`, `--codex-dir`, `--gemini-dir`, `--droid-dir`, `--opencode-db`, `--source-dir`) also constrain commit attribution: only commit days with matching repo-attributed usage events are counted.
 
+### Optimize Reports
+
+```bash
+# Counterfactual pricing across candidate models
+llm-usage optimize monthly --provider openai --candidate-model gpt-4.1 --candidate-model gpt-5-codex
+
+# Keep only the cheapest candidate in JSON output
+llm-usage optimize weekly --provider openai --candidate-model gpt-4.1,gpt-5-codex --top 1 --json
+```
+
+`--provider` filters by billing entity. Provider aliases are normalized to billing roots (for example, `openai-codex` is treated as `openai`).
+
 ### Filtering
 
 ```bash
@@ -148,6 +163,8 @@ llm-usage monthly --model claude
 llm-usage monthly --source opencode --provider openai --model gpt-4.1
 ```
 
+Use `--source` to scope where events came from (`pi`, `codex`, `gemini`, `droid`, `opencode`), and `--provider` to scope the billing entity behind those events.
+
 ### Custom Paths
 
 ```bash
@@ -256,6 +273,8 @@ pnpm run perf:production-benchmark -- \
 | `LLM_USAGE_PARSE_MAX_PARALLEL`   | Max parallel file parses (`1-64`) |
 | `LLM_USAGE_PARSE_CACHE_ENABLED`  | Enable parse cache (`1/0`)        |
 
+Parse cache is source-sharded on disk (`parse-file-cache.<source>.json`) so source-scoped runs avoid loading unrelated cache blobs.
+
 See full environment variable reference in the [documentation](https://ayagmar.github.io/llm-usage-metrics/configuration/).
 
 ### Update Checks
@@ -296,6 +315,7 @@ pnpm cli daily
 - **[Getting Started](https://ayagmar.github.io/llm-usage-metrics/getting-started/)** — Installation and first steps
 - **[CLI Reference](https://ayagmar.github.io/llm-usage-metrics/cli-reference/)** — Complete command reference
 - **[Efficiency](https://ayagmar.github.io/llm-usage-metrics/efficiency/)** — Efficiency report semantics and interpretation
+- **[Optimize](https://ayagmar.github.io/llm-usage-metrics/optimize/)** — Counterfactual candidate-model pricing semantics
 - **[Data Sources](https://ayagmar.github.io/llm-usage-metrics/sources/)** — Source configuration
 - **[Configuration](https://ayagmar.github.io/llm-usage-metrics/configuration/)** — Environment variables
 - **[Benchmarks](https://ayagmar.github.io/llm-usage-metrics/benchmarks/)** — Production benchmark methodology and results