llm_cost_tracker 0.5.3 → 0.6.1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_cost_tracker
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.1
 platform: ruby
 authors:
 - Sergii Khomenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-28 00:00:00.000000000 Z
+date: 2026-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -283,24 +283,8 @@ files:
 - app/views/llm_cost_tracker/tags/index.html.erb
 - app/views/llm_cost_tracker/tags/show.html.erb
 - config/routes.rb
-- docs/architecture.md
-- docs/budgets.md
-- docs/configuration.md
-- docs/cookbook.md
-- docs/dashboard-overview.png
-- docs/dashboard.md
-- docs/extending.md
-- docs/operations.md
-- docs/pricing.md
-- docs/querying.md
-- docs/streaming.md
-- docs/technical/README.md
-- docs/technical/data-flow.md
-- docs/technical/extension-points.md
-- docs/technical/module-map.md
-- docs/technical/operational-notes.md
-- docs/upgrading.md
 - lib/llm_cost_tracker.rb
+- lib/llm_cost_tracker/active_record_adapter.rb
 - lib/llm_cost_tracker/assets.rb
 - lib/llm_cost_tracker/budget.rb
 - lib/llm_cost_tracker/capture_verifier.rb
@@ -310,11 +294,13 @@ files:
 - lib/llm_cost_tracker/cost.rb
 - lib/llm_cost_tracker/doctor.rb
 - lib/llm_cost_tracker/doctor/capture_check.rb
+- lib/llm_cost_tracker/doctor/ingestion_check.rb
 - lib/llm_cost_tracker/engine.rb
 - lib/llm_cost_tracker/engine_compatibility.rb
 - lib/llm_cost_tracker/errors.rb
 - lib/llm_cost_tracker/event.rb
 - lib/llm_cost_tracker/event_metadata.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/add_ingestion_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_latency_ms_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_period_totals_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_provider_response_id_generator.rb
@@ -322,6 +308,7 @@ files:
 - lib/llm_cost_tracker/generators/llm_cost_tracker/add_usage_breakdown_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/install_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/prices_generator.rb
+- lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_ingestion_to_llm_cost_tracker.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_latency_ms_to_llm_api_calls.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_period_totals_to_llm_cost_tracker.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/add_provider_response_id_to_llm_api_calls.rb.erb
@@ -333,6 +320,8 @@ files:
 - lib/llm_cost_tracker/generators/llm_cost_tracker/templates/upgrade_llm_api_call_tags_to_jsonb.rb.erb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_cost_precision_generator.rb
 - lib/llm_cost_tracker/generators/llm_cost_tracker/upgrade_tags_to_jsonb_generator.rb
+- lib/llm_cost_tracker/inbox_event.rb
+- lib/llm_cost_tracker/ingestor_lease.rb
 - lib/llm_cost_tracker/integrations/anthropic.rb
 - lib/llm_cost_tracker/integrations/base.rb
 - lib/llm_cost_tracker/integrations/object_reader.rb
@@ -375,6 +364,15 @@ files:
 - lib/llm_cost_tracker/request_url.rb
 - lib/llm_cost_tracker/retention.rb
 - lib/llm_cost_tracker/storage/active_record_backend.rb
+- lib/llm_cost_tracker/storage/active_record_connection_cleanup.rb
+- lib/llm_cost_tracker/storage/active_record_inbox.rb
+- lib/llm_cost_tracker/storage/active_record_inbox_batch.rb
+- lib/llm_cost_tracker/storage/active_record_ingestor.rb
+- lib/llm_cost_tracker/storage/active_record_ingestor_lease.rb
+- lib/llm_cost_tracker/storage/active_record_period_totals.rb
+- lib/llm_cost_tracker/storage/active_record_periods.rb
+- lib/llm_cost_tracker/storage/active_record_rollup_batch.rb
+- lib/llm_cost_tracker/storage/active_record_rollup_upsert_sql.rb
 - lib/llm_cost_tracker/storage/active_record_rollups.rb
 - lib/llm_cost_tracker/storage/active_record_store.rb
 - lib/llm_cost_tracker/storage/custom_backend.rb

data/docs/architecture.md

@@ -1,28 +0,0 @@
-# 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

@@ -1,45 +0,0 @@
-# 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

@@ -1,65 +0,0 @@
-# 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

@@ -1,185 +0,0 @@
-# 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

@@ -1,38 +0,0 @@
-# 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

@@ -1,32 +0,0 @@
-# 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

@@ -1,44 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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.