llm_cost_tracker 0.5.2 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d515abad24d5659f797d5ea0426d6111dc41baf78809181128546e29ac566db
-  data.tar.gz: 90da1dda161661423f6034f28d7bb359e06c39f48b9f4872cb0eba9a123f8948
+  metadata.gz: d3fe81fdf7b12f977d7dfc4aa86f629e8b5ad6e099100bfbfe1b18507db17fff
+  data.tar.gz: dffe0c0ebeb30fa111273b654141ee06e1275426846796b1749435429da3414f
 SHA512:
-  metadata.gz: aa7af4b5caca984cbcb4c8a7a267600251962e1879de8f3bff32d8a3f6e8d22888ba4a26036de09c36345566e3c309a2868012b66b5dcc970e52bcb6b5e444be
-  data.tar.gz: 932f2bb680690ed043eb719debddd58ac85c7f1cbbd0ec9c30c95f5595d71a5f70516b3d8d19ca65929856c4ade902a813da34b4de2053f553aa916eece66865
+  metadata.gz: 4849f0d0b09d640ed3a902bbc19a975e576b0539d2c71eac3165199eed196ecd88f249ff1d571c43b2686d59466dde26a0467f984c2cbb7804a5f771e184df31
+  data.tar.gz: 8aa17efc9dd68b1489cdc69351a67fe2398c35720750cf1440f215bceeef0392c9f3af1d41ebd444ddcd9876c2c1e612ea50d6403fb7f650735fc9d9161a2a85

data/CHANGELOG.md

@@ -4,6 +4,22 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-04-28
+
+### Added
+
+- Official OpenAI SDK streaming capture for Responses streams, Responses raw streams, Responses retrieve streams, and Chat Completions raw streams.
+- Official Anthropic SDK streaming capture for Messages streams and raw streams.
+- Capture verification via `llm_cost_tracker:verify_capture` and expanded doctor capture diagnostics.
+- Pricing explanation via `LlmCostTracker::Pricing.explain` and `llm_cost_tracker:prices:explain`.
+- Extensible storage and SDK integration registries via `Storage.register` and `Integrations.register`.
+
+### Fixed
+
+- OpenAI Responses stream parsing now reads final usage from completed response events.
+- Incomplete price entries now return unknown pricing instead of raising `TypeError`.
+- Retention pruning now keeps ActiveRecord period rollups in sync when deleting rows inside active budget windows.
+
 ## [0.5.2] - 2026-04-27
 
 ### Added

data/README.md

@@ -167,6 +167,12 @@ Refresh on demand from the maintained snapshot:
 bin/rails llm_cost_tracker:prices:refresh
 ```
 
+Explain why a model is priced or unknown:
+
+```bash
+PROVIDER=openai MODEL=gpt-4o bin/rails llm_cost_tracker:prices:explain
+```
+
 Precedence is `pricing_overrides` → `prices_file` → bundled. Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys. Full pricing reference: [`docs/pricing.md`](docs/pricing.md).
 
 ## Budgets
@@ -231,7 +237,7 @@ Auth is your job. Examples for basic auth and Devise: [`docs/dashboard.md`](docs
 
 RubyLLM chat, embedding, and transcription calls are captured through RubyLLM's provider layer when `config.instrument :ruby_llm` is enabled.
 
-Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths whenever the provider emits final-usage events.
+Endpoints covered end-to-end: OpenAI Chat Completions / Responses / Completions / Embeddings, Anthropic Messages, Gemini `generateContent` and `streamGenerateContent`, plus their OpenAI-compatible equivalents. Streaming is captured for Faraday paths and official OpenAI / Anthropic SDK stream helpers whenever the provider emits final-usage events.
 
 ## Privacy
 
@@ -260,7 +266,6 @@ is still brief.
 ## Known limitations
 
 - `:block_requests` is best-effort under concurrency, not a transactional cap.
-- Official OpenAI and Anthropic SDK integrations cover non-streaming calls; streaming via those SDKs falls back to Faraday middleware or `track_stream`.
 - Streaming usage capture relies on the provider emitting a final-usage event. Missing events are stored with `usage_source: "unknown"` so they appear on the data-quality page rather than vanishing.
 - `provider_response_id` is stored only when the provider exposes a stable ID. Gemini is best-effort and varies by endpoint.
 - Cache write TTL variants on Anthropic (1h vs 5min writes) are not modeled separately yet.
@@ -269,7 +274,7 @@ is still brief.
 
 ```bash
 bundle install
-bin/check       # rubocop + rspec
+bin/check       # rubocop + rspec + coverage gate
 ```
 
 Architecture rules and conventions for contributions live in [`AGENTS.md`](AGENTS.md) and [`docs/architecture.md`](docs/architecture.md).

data/docs/architecture.md

@@ -0,0 +1,28 @@
+# Architecture
+
+LLM Cost Tracker is a provider-agnostic billing ledger. Core code should model durable billing concepts, not the naming quirks of one provider or one model family.
+
+Core vocabulary belongs in provider-neutral terms:
+
+- `input_tokens`
+- `cache_read_input_tokens`
+- `cache_write_input_tokens`
+- `output_tokens`
+- `hidden_output_tokens`
+- `pricing_mode`
+- `provider_response_id`
+
+Provider-specific names belong only at ingestion boundaries: parsers and stream adapters. Those adapters translate raw fields into the canonical ledger vocabulary before data reaches `Tracker`, `Pricing`, storage, dashboard services, or reports.
+
+Pricing logic should prefer generic mechanisms over provider branches. Use provider/model price entries only for lookup and rate selection. Use `pricing_mode` plus mode-prefixed price keys for alternate billing modes instead of adding model-specific conditionals.
+
+Tags remain the extension point for app-specific attribution such as tenant, user, feature, trace, job, workflow, or agent session. Do not promote those dimensions into first-class columns unless the ledger itself needs them for provider-agnostic billing behavior.
+
+Hot-path guardrails must not aggregate over the growing call ledger. ActiveRecord period budgets should read maintained rows in `llm_cost_tracker_period_totals`; dashboard analytics may run grouped queries because they are user-initiated reporting paths.
+
+## Technical Docs
+
+- [Module map](technical/module-map.md)
+- [Data flow](technical/data-flow.md)
+- [Extension points](technical/extension-points.md)
+- [Operational notes](technical/operational-notes.md)

data/docs/budgets.md

@@ -0,0 +1,45 @@
+# Budgets and Guardrails
+
+Budgets are safety rails for a Rails app using LLMs in production. They are not
+invoice reconciliation and they are not a transactional quota system.
+
+The full behavior reference is moving here from the README: monthly, daily, and
+per-call budgets; notification payloads; preflight behavior; and failure modes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Budgets](../README.md#budgets)
+- [Known limitations](../README.md#known-limitations)
+- [Operations](operations.md)
+
+## Behaviors
+
+- `:notify`: call `on_budget_exceeded` after a priced event crosses a limit.
+- `:raise`: record the event, then raise `BudgetExceededError`.
+- `:block_requests`: preflight future calls when stored period totals are
+  already over budget.
+
+```ruby
+config.monthly_budget = 500.00
+config.daily_budget = 50.00
+config.per_call_budget = 2.00
+config.budget_exceeded_behavior = :block_requests
+```
+
+`:block_requests` needs ActiveRecord storage for shared period totals. Under
+concurrency it stops the next request after overspend is visible; it does not
+make provider spend transactional.
+
+## Error Payload
+
+`BudgetExceededError` exposes:
+
+- `budget_type`
+- `total`
+- `budget`
+- `monthly_total`
+- `daily_total`
+- `call_cost`
+- `last_event`

data/docs/configuration.md

@@ -0,0 +1,65 @@
+# Configuration
+
+Configuration is the contract between the host app and the ledger: where events
+go, which integrations are enabled, how attribution is attached, and how the app
+reacts when storage, pricing, or budgets need attention.
+
+The full option reference is moving here from the README. Until that migration is
+complete, the README anchors below remain canonical.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Quickstart](../README.md#quickstart)
+- [Capturing calls](../README.md#capturing-calls)
+- [Tags](../README.md#tags-who-burned-this-money)
+- [Pricing](../README.md#pricing)
+- [Budgets](../README.md#budgets)
+
+## Scope
+
+This page is scoped to:
+
+- `storage_backend`: `:log`, `:active_record`, and `:custom`
+- `default_tags`: static tags and per-request callable tags
+- `instrument`: RubyLLM and official SDK integrations
+- `prices_file` and `pricing_overrides`
+- `monthly_budget`, `daily_budget`, and `per_call_budget`
+- `budget_exceeded_behavior`
+- `storage_error_behavior`
+- `unknown_pricing_behavior`
+- `openai_compatible_providers`
+- `report_tag_breakdowns`
+
+## Minimal Production Config
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.storage_backend = :active_record
+  config.default_tags = -> { { environment: Rails.env } }
+  config.prices_file = Rails.root.join("config/llm_cost_tracker_prices.yml")
+  config.instrument :openai
+end
+```
+
+Keep configuration at boot. Mutable shared settings are frozen after
+`configure` returns so request-time code cannot silently change global tracking
+behavior.
+
+Enabled SDK integrations are fail-fast. The client gem must be loaded, meet the
+minimum supported version, and expose the expected classes and methods before
+LLM Cost Tracker installs its wrapper.
+
+## Capture Verification
+
+After boot, run:
+
+```bash
+bin/rails llm_cost_tracker:verify_capture
+```
+
+For ActiveRecord storage, the task records a synthetic manual event inside a
+rollback and checks that notifications and persistence both work. For log and
+custom storage, it reports the configured capture path without invoking external
+sinks.

data/docs/cookbook.md

@@ -0,0 +1,185 @@
+# Cookbook
+
+Short integration recipes for common Ruby clients. Prefer SDK integrations or middleware. Use `track` and `track_stream` only as fallback helpers for unsupported clients.
+
+| Client | Best path | Why |
+|---|---|---|
+| RubyLLM | `config.instrument :ruby_llm` | The integration wraps RubyLLM's provider layer without adding a third-party instrumentation gem. |
+| Official `openai` gem | `config.instrument :openai` | The integration wraps SDK resource methods without changing call sites. |
+| Official `anthropic` gem | `config.instrument :anthropic` | The integration records returned message usage without changing call sites. |
+| `ruby-openai` | Faraday middleware | The client is built on Faraday and accepts middleware via the constructor block. |
+| OpenAI-compatible proxy | Faraday middleware | Use `ruby-openai` or a direct Faraday client against the proxy host. |
+| Custom Faraday client | Faraday middleware | The middleware can parse known provider responses automatically. |
+| Other clients | Adapter first, fallback helpers second | Add a stable integration instead of scattering per-call ledger code. |
+
+## RubyLLM
+
+Enable the integration once, then keep normal RubyLLM calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :ruby_llm
+end
+
+LlmCostTracker.with_tags(feature: "support_chat") do
+  RubyLLM.chat.ask("Hello")
+  RubyLLM.embed("text to embed")
+end
+```
+
+The RubyLLM integration supports `ruby_llm >= 1.14.1` and checks RubyLLM's provider contract at boot. Chat, embedding, and transcription calls are captured. Image generation, moderation, and tool execution are not recorded as separate ledger rows.
+
+## Official OpenAI SDK
+
+Enable the integration once, then keep normal `openai` gem calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :openai
+end
+
+client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+
+client.responses.create(model: "gpt-4o", input: "Hello")
+client.chat.completions.create(
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }]
+)
+
+client.responses.stream(model: "gpt-4o", input: "Hello").each do |event|
+  puts event.type
+end
+
+client.responses.stream_raw(model: "gpt-4o", input: "Hello").each do |event|
+  puts event.type
+end
+
+client.chat.completions.stream_raw(
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }],
+  stream_options: { include_usage: true }
+).each do |event|
+  puts event
+end
+```
+
+The OpenAI SDK integration supports `openai >= 0.59.0`. Streaming calls are recorded after the returned stream is consumed. Chat Completions streams need `stream_options: { include_usage: true }` for final usage.
+
+## Official Anthropic SDK
+
+Enable the integration once, then keep normal `anthropic` gem calls unchanged.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.instrument :anthropic
+end
+
+client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+
+client.messages.create(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+)
+
+client.messages.stream(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+).each do |event|
+  puts event.type
+end
+
+client.messages.stream_raw(
+  max_tokens: 1024,
+  model: "claude-sonnet-4-5-20250929",
+  messages: [{ role: "user", content: "Hello" }]
+).each do |event|
+  puts event.type
+end
+```
+
+The Anthropic SDK integration supports `anthropic >= 1.36.0`. Streaming calls are recorded after the returned stream is consumed.
+
+## ruby-openai
+
+`ruby-openai` is a community client that occupies the same `OpenAI::Client` constant as the official gem; only one of the two can be loaded. `config.instrument :openai` is for the official gem. For `ruby-openai`, attach the Faraday middleware via the constructor block:
+
+```ruby
+client = OpenAI::Client.new(access_token: ENV["OPENAI_API_KEY"]) do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+end
+
+client.chat(
+  parameters: {
+    model: "gpt-4o",
+    messages: [{ role: "user", content: "Hello" }],
+    stream: proc { |chunk, _bytesize| puts chunk.dig("choices", 0, "delta", "content") },
+    stream_options: { include_usage: true }
+  }
+)
+```
+
+Use the constructor block on every client you build, or wrap client creation in your own factory.
+
+## Azure OpenAI
+
+Azure's v1 API works with OpenAI-compatible HTTP shapes, but pricing and deployment names are yours. Register the Azure host, use the Faraday middleware path, and keep Azure-specific prices in `prices_file` or `pricing_overrides`.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.openai_compatible_providers["my-resource.openai.azure.com"] = "azure_openai"
+end
+
+conn = Faraday.new(url: "https://my-resource.openai.azure.com") do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+conn.post(
+  "/openai/v1/responses",
+  { model: "gpt-4o-prod", input: "Hello" },
+  { "api-key" => ENV.fetch("AZURE_OPENAI_API_KEY") }
+)
+```
+
+## Gemini API
+
+Google's official Gemini SDKs do not include Ruby. Use a Faraday client against the REST API so the Gemini parser can capture usage automatically.
+
+```ruby
+conn = Faraday.new(url: "https://generativelanguage.googleapis.com") do |f|
+  f.use :llm_cost_tracker, tags: { feature: "chat" }
+  f.request :json
+  f.response :json
+  f.adapter Faraday.default_adapter
+end
+
+conn.post(
+  "/v1beta/models/gemini-2.5-flash:generateContent?key=#{ENV.fetch("GOOGLE_API_KEY")}",
+  { contents: [{ role: "user", parts: [{ text: "Hello" }] }] }
+)
+```
+
+## LiteLLM proxy
+
+LiteLLM Proxy speaks an OpenAI-compatible HTTP shape, so register the proxy host once and keep using the normal middleware path.
+
+```ruby
+LlmCostTracker.configure do |config|
+  config.openai_compatible_providers["proxy.internal.example"] = "litellm"
+end
+
+client = OpenAI::Client.new(
+  access_token: ENV["LITELLM_API_KEY"],
+  uri_base: "https://proxy.internal.example"
+) do |f|
+  f.use :llm_cost_tracker, tags: { gateway: "litellm" }
+end
+
+client.chat(parameters: { model: "openai/gpt-5-mini", messages: [{ role: "user", content: "Hello" }] })
+```
+
+If your proxy exposes custom model IDs or discounts, add them in `prices_file` or `pricing_overrides`.

data/docs/dashboard.md

@@ -0,0 +1,38 @@
+# Dashboard
+
+The dashboard is a Rails Engine for humans reviewing spend, attribution, and data
+quality. It is server-rendered ERB, has no JavaScript bundle, and reads from the
+host app's `llm_api_calls` table.
+
+The detailed dashboard guide is moving here from the README: mounting, route
+constraints, authentication examples, page map, and operational notes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Dashboard](../README.md#dashboard)
+- [Privacy](../README.md#privacy)
+- [Operations](operations.md)
+
+## Mounting
+
+```ruby
+mount LlmCostTracker::Engine => "/llm-costs"
+```
+
+Use `storage_backend = :active_record` for apps that mount the dashboard.
+
+## Pages
+
+- Overview: spend trend, budget status, anomaly banner, provider rollup, top models
+- Models: spend and usage by provider and model
+- Calls: filterable call ledger with CSV export
+- Tags: tag keys and tag value breakdowns
+- Data Quality: unknown pricing, untagged calls, missing latency, incomplete streams
+
+## Authentication
+
+The gem does not ship dashboard auth. Mount the engine behind the host app's
+existing authentication layer: Devise, basic auth, Cloudflare Access, or your own
+constraints.

data/docs/extending.md

@@ -0,0 +1,32 @@
+# Extending LLM Cost Tracker
+
+Extensions belong at clear boundaries: parsers for response shapes, integrations
+for SDK hooks, pricing files for rates, and custom storage for apps that own
+persistence themselves.
+
+The practical extension guide is moving here from the README. The lower-level
+contracts already live in the technical extension reference.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Capturing calls](../README.md#capturing-calls)
+- [Pricing](pricing.md)
+- [Technical extension points](technical/extension-points.md)
+
+## Extension Points
+
+- Custom parser: translate a provider response into `ParsedUsage`.
+- OpenAI-compatible host: register the host-to-provider mapping.
+- Custom storage: receive the canonical `Event` and write it elsewhere.
+- Notifications subscriber: observe `llm_request.llm_cost_tracker`.
+- Local price file: model gateway IDs, contract rates, or unsupported models.
+
+## Parser Boundary
+
+A parser matches request URLs, translates provider response shapes into
+`ParsedUsage`, and returns `nil` when the response is outside its contract.
+
+Do provider-specific translation at this boundary. Keep `Tracker`, storage,
+dashboard, and pricing in canonical ledger terms.

data/docs/operations.md

@@ -0,0 +1,44 @@
+# Operations
+
+Production use is mostly about choosing the right storage backend, keeping the
+database healthy, and understanding where the gem is intentionally best effort.
+
+The operational guide is moving here from the README: retention, tag storage,
+thread safety, connection pools, and deployment notes.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Privacy](../README.md#privacy)
+- [Known limitations](../README.md#known-limitations)
+- [Technical operational notes](technical/operational-notes.md)
+
+## Production Defaults
+
+- Use `storage_backend = :active_record` for the shared ledger, dashboard, and
+  cross-process budget guardrails.
+- Size the ActiveRecord connection pool for your app plus ledger writes.
+- Keep `storage_error_behavior = :warn` unless losing the LLM response is better
+  than losing the ledger event.
+- Treat `:block_requests` as a guardrail, not a hard quota.
+- Keep `default_tags` callables fast and thread-safe.
+
+## Retention
+
+Retention is explicit. Use the prune task when the ledger should not grow
+forever:
+
+```bash
+DAYS=90 bin/rails llm_cost_tracker:prune
+```
+
+When ActiveRecord period rollups are installed, pruning decrements the
+affected daily and monthly buckets in the same batch transaction as the ledger
+delete.
+
+## Data Shape
+
+Tags are JSONB with a GIN index on PostgreSQL and JSON text elsewhere. The
+dashboard and query helpers work across supported adapters, but PostgreSQL is the
+strongest path for large tag-heavy ledgers.

data/docs/pricing.md

@@ -0,0 +1,94 @@
+# Pricing and Price Refresh
+
+LLM Cost Tracker prices calls locally from recorded usage and a versioned price
+registry. Providers usually return token counts, not a stable per-request price,
+so the gem stores the calculated cost with each ledger row.
+
+The full pricing reference is moving here from the README: registry shape,
+refresh tasks, precedence, provider-qualified keys, and mode-specific rates.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Pricing](../README.md#pricing)
+- [Supported providers](../README.md#supported-providers)
+- [Known limitations](../README.md#known-limitations)
+
+## Registry Rules
+
+- Built-in prices live in `lib/llm_cost_tracker/prices.json`.
+- Local snapshots live wherever `config.prices_file` points.
+- Precedence is `pricing_overrides`, then `prices_file`, then bundled prices.
+- Provider-qualified keys like `openai/gpt-4o-mini` win over model-only keys.
+- Historical rows keep the cost calculated when the call was recorded.
+
+## Refresh Commands
+
+```bash
+bin/rails generate llm_cost_tracker:prices
+bin/rails llm_cost_tracker:prices:refresh
+bin/rails llm_cost_tracker:prices:check
+PROVIDER=openai MODEL=gpt-4o bin/rails llm_cost_tracker:prices:explain
+```
+
+The refresh task reads the maintained LLM Cost Tracker snapshot and writes to
+`ENV["OUTPUT"]`, then `config.prices_file`, then
+`config/llm_cost_tracker_prices.yml`.
+
+## Price Fields
+
+Base fields:
+
+- `input`
+- `output`
+- `cache_read_input`
+- `cache_write_input`
+
+Mode-prefixed fields use the same base terms:
+
+- `batch_input`
+- `batch_output`
+- `priority_input`
+- `batch_cache_read_input`
+
+## Pricing Modes
+
+Pass `pricing_mode: :batch` when usage came from a provider batch job or another
+discounted mode:
+
+```ruby
+LlmCostTracker.track(
+  provider: "openai",
+  model: "gpt-4o",
+  input_tokens: 1_000_000,
+  output_tokens: 250_000,
+  pricing_mode: :batch,
+  feature: "offline_eval"
+)
+```
+
+The calculator uses `batch_input`, `batch_output`, and other matching
+mode-prefixed fields when present, then falls back to the base field for missing
+mode-specific rates.
+
+## Price Explain
+
+Use `prices:explain` when Data Quality shows unknown pricing or a local override
+does not behave as expected:
+
+```bash
+PROVIDER=openai MODEL=gpt-4o PRICING_MODE=batch bin/rails llm_cost_tracker:prices:explain
+```
+
+Optional token env vars let the command check the exact buckets that a call used:
+
+```bash
+PROVIDER=custom MODEL=gateway-model INPUT_TOKENS=1000 OUTPUT_TOKENS=200 CACHE_READ_INPUT_TOKENS=50 bin/rails llm_cost_tracker:prices:explain
+```
+
+The command reports the matched source, matched key, match strategy, effective
+rates, and any missing rate needed to price the event.
+
+Provider-specific pricing pages belong in scrapers and snapshots. Runtime
+pricing should stay in canonical billing terms.

data/docs/querying.md

@@ -0,0 +1,36 @@
+# Querying and Reports
+
+Once calls are in `llm_api_calls`, the host app owns the data. Query it from a
+console, a scheduled job, your admin UI, or the mounted dashboard.
+
+The full querying reference is moving here from the README: ActiveRecord scopes,
+reporting helpers, tag breakdowns, and SQL-side grouping patterns.
+
+## Canonical Sources
+
+Until this page is expanded, use:
+
+- [Querying](../README.md#querying)
+- [Dashboard](dashboard.md)
+- [Operations](operations.md)
+
+## Common Queries
+
+```ruby
+LlmCostTracker::LlmApiCall.today.total_cost
+LlmCostTracker::LlmApiCall.this_month.cost_by_model
+LlmCostTracker::LlmApiCall.this_month.cost_by_provider
+LlmCostTracker::LlmApiCall.this_month.cost_by_tag("feature")
+LlmCostTracker::LlmApiCall.by_tags(user_id: 42, feature: "chat").this_month.total_cost
+LlmCostTracker::LlmApiCall.daily_costs(days: 7)
+```
+
+## Report Task
+
+```bash
+bin/rails llm_cost_tracker:report
+DAYS=7 bin/rails llm_cost_tracker:report
+```
+
+This page is scoped to cost scopes, tag grouping, period grouping, latency
+helpers, unknown-pricing queries, and report tag breakdowns.