llm_cost_tracker 0.1.4 → 0.2.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb8f35c3d464bc7adea3b8376055e23c2ff704d815247de8ec40c82cbab41d29
-  data.tar.gz: ec3fecd6c98f9c3c9664f12db2ca411440d698f5743d2ac77827e86f04fca380
+  metadata.gz: '043255892f8db58b53a84d26d25ee09561b8349b72f463429f0f31691c6449a5'
+  data.tar.gz: a4577ed5935b1f65e85c4d73700bde447715875d40846d1bf6a8575b0588e2fc
 SHA512:
-  metadata.gz: 76ccf3b2d160eb3d9e7dd22545e7a53515f48334f6fd7a6aae89684ad660721eb1fcedc27f572b669f95da91e4afe01b9bc5e6762801a36b0ac78fbbb5229b80
-  data.tar.gz: 7456155944b169f3a5c293c0d256b1a4200de22f24f1433f387475fdefedb9a5ad1e66776b0263eba9ea7be4de2e9fbd4315346c05cc1d0dfa76cadd94699199
+  metadata.gz: 0a7d8c3454cb88b93da2ef83d4b8cda330060200e3cb5073017f2d9c927d2d6e6ceef6e8d3cbc29120d8e44d955c8c1800126271ebb92f981253f9315d9abde8
+  data.tar.gz: 239c293ddf252d5933adf294329f20b9f5df2e1322bb5413aa4392b43077f26385ad89bbf382f786e1bc79a94252b47ed157d19464973beb4467a312cef368eb

data/CHANGELOG.md

@@ -1,133 +1,100 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.2.0.alpha1, 0.2.0.alpha2] - 2026-04-20
 
-## [0.1.4] - 2026-04-18
-
-### Breaking Changes
+### Breaking
 
-- Removed `LlmApiCall.by_user(id)` and `LlmApiCall.by_feature(name)` convenience scopes. Use
-  `by_tag("user_id", id)`, `by_tag("feature", name)`, or `by_tags(...)` for filters.
-- Removed `LlmApiCall#user_id` and `LlmApiCall#feature` tag accessors. Use
-  `parsed_tags["user_id"]` or `parsed_tags["feature"]` when reading stored tags.
-- Removed `ReportData#cost_by_feature`. Use `ReportData#cost_by_tags.fetch("feature")` or
-  `LlmApiCall.cost_by_tag("feature")`.
+- Require Ruby 3.3+ (was 3.1), Rails/ActiveRecord 7.1+ (was 7.0), Faraday 2.0+ (was 1.0).
+- `Event`, `Cost`, and `ParsedUsage` are plain `Data.define` value objects; use method access (`event.cost.total_cost`) instead of Hash lookups. `ActiveSupport::Notifications` payloads are unchanged.
+- Rename `LlmCostTracker::InvalidFilter` → `InvalidFilterError`.
+- Drop `LlmApiCall.by_provider` / `by_model` scopes — use `where(provider:)` / `where(model:)`.
+- `ReportData` no longer hardcodes a `"feature"` tag breakdown. Configure `config.report_tag_breakdowns = %w[feature env]` (or pass `tag_breakdowns:` to `ReportData.build` / `Report.generate`). Default is empty.
 
 ### Added
 
-- Add SQL-side `group_by_tag(key)` and `cost_by_tag(key)` aggregations across any attribution tag.
-- Use generic tag breakdowns in reports instead of feature-specific report data.
+- `LlmApiCall.group_by_period(:day/:month)` — SQL-side period grouping.
+- Opt-in `LlmCostTracker::Engine` dashboard (Rails 7.1+): overview with delta-vs-previous-period, provider rollup, models, filterable call list with CSV export and outlier sort modes, call details, tag key explorer, per-key tag breakdown, data quality. PostgreSQL/SQLite use adapter-specific SQL; MySQL falls back to an in-Ruby scan capped at 50k rows. Core middleware still works without Rails.
 
-## [0.1.3] - 2026-04-18
+## [0.1.4] - 2026-04-18
 
-### Thread-safety, pricing UX, and internal hardening
+### Breaking
 
-**Thread-safety**
+- Drop `LlmApiCall.by_user` / `by_feature` scopes and `LlmApiCall#user_id` / `#feature` accessors. Use `by_tag("user_id", id)` / `by_tag("feature", name)` or `by_tags(...)`; read stored tags via `parsed_tags[...]`.
+- Drop `ReportData#cost_by_feature` — use `cost_by_tags.fetch("feature")` or `LlmApiCall.cost_by_tag("feature")`.
 
-- Guard `PriceRegistry.file_prices` and `Pricing.sorted_price_keys` memoization with mutexes.
+### Added
 
-**Pricing UX**
+- `group_by_tag(key)` / `cost_by_tag(key)` SQL aggregations across any tag key.
+- Generic tag breakdowns in reports.
 
+## [0.1.3] - 2026-04-18
+
+### Fixed / Changed
+
+- Mutex-guard `PriceRegistry.file_prices` and `Pricing.sorted_price_keys` memoization.
 - Warn on unknown keys in local prices files.
-- Add `llm_cost_tracker:prices` generator for creating a local price override template.
 - Document that budget guardrails skip events with unknown pricing.
 
-**Onboarding UX**
+### Added
 
-- Add callable Faraday `tags:` support for per-request Rails attribution with `Current`.
-- Add `llm_cost_tracker:report` rake task for a quick terminal cost report.
-- Rework README with a no-database quick try, report output, and safety guarantees.
+- `llm_cost_tracker:prices` generator for a local price override template.
+- Callable Faraday `tags:` for per-request Rails attribution via `Current`.
+- `llm_cost_tracker:report` rake task.
 
-**Internal refactor (no behavior change)**
+### Internal
 
-- Extract `Logging` module and remove duplicated warning helpers.
-- Extract `TagQuery`, `TagsColumn`, and `TagAccessors` helpers from `LlmApiCall`.
-- Introduce typed `Cost`, `Event`, and `ParsedUsage` value objects while preserving hash-like access.
-- Move storage dispatch into dedicated backend objects with a uniform save contract.
-- Split `Report` into `ReportData` and `ReportFormatter`.
-- Use `OpenaiUsage` composition for OpenAI-compatible providers instead of parser inheritance.
-- Move config enum validation into `Configuration` setters.
-- Memoize the merged built-in/file/override prices table.
-- Restrict the Gemini parser to `generateContent` and `streamGenerateContent` paths.
+- Extract `Logging`, `TagQuery`, `TagsColumn`, `TagAccessors` helpers; `Cost`, `Event`, `ParsedUsage` value objects; storage backend objects; split `Report` into data + formatter; `OpenaiUsage` composition for OpenAI-compatible providers; move enum validation into `Configuration`; memoize merged prices table; restrict Gemini parser to `generateContent` / `streamGenerateContent`.
 
 ## [0.1.2] - 2026-04-18
 
 ### Added
 
-- Auto-detect OpenRouter and DeepSeek as OpenAI-compatible providers.
-- Add `openai_compatible_providers` configuration for private OpenAI-compatible gateways.
-- Add `BudgetExceededError` and `budget_exceeded_behavior` for best-effort budget guardrails.
-- Add `:raise` and `:block_requests` budget behaviors; `:block_requests` is not a hard cap under concurrency.
-- Add `StorageError` and `storage_error_behavior` so storage failures do not have to break host LLM calls.
-- Add `UnknownPricingError` and `unknown_pricing_behavior` for unknown model pricing.
-- Add built-in `prices.json` registry with metadata and source URLs.
-- Add `prices_file` configuration for local JSON/YAML pricing overrides.
-- Add `with_cost`, `without_cost`, and `unknown_pricing` ActiveRecord scopes.
-- Add `latency_ms` tracking for Faraday calls, manual tracking, notifications, and ActiveRecord storage.
-- Add `with_latency`, `average_latency_ms`, `latency_by_model`, and `latency_by_provider`.
-- Use PostgreSQL `jsonb` storage for tags in newly generated migrations.
-- Add a GIN index on `llm_api_calls.tags` for PostgreSQL installs.
-- Add adapter-aware `by_tag` querying with JSONB containment on PostgreSQL and text fallback elsewhere.
-- Add `by_tags`, `by_user`, and `by_feature` scopes for common attribution queries.
-- Add `llm_cost_tracker:upgrade_tags_to_jsonb` generator for existing PostgreSQL installs.
-- Add `llm_cost_tracker:upgrade_cost_precision` generator for widening stored cost columns.
-- Add `llm_cost_tracker:add_latency_ms` generator for existing installs.
+- Auto-detect OpenRouter and DeepSeek as OpenAI-compatible.
+- `openai_compatible_providers` config for private gateways.
+- `BudgetExceededError` + `budget_exceeded_behavior` (`:notify`, `:raise`, `:block_requests`). `:block_requests` is best-effort under concurrency.
+- `StorageError` + `storage_error_behavior`; `UnknownPricingError` + `unknown_pricing_behavior`.
+- Built-in `prices.json` registry with metadata and source URLs; `prices_file` for local JSON/YAML overrides.
+- `with_cost`, `without_cost`, `unknown_pricing` scopes.
+- `latency_ms` tracking end-to-end; `with_latency`, `average_latency_ms`, `latency_by_model`, `latency_by_provider`.
+- `jsonb` tags + GIN index on PostgreSQL in new migrations; adapter-aware `by_tag` (JSONB containment on PG, text fallback elsewhere); `by_tags` / `by_user` / `by_feature`.
+- Generators: `upgrade_tags_to_jsonb`, `upgrade_cost_precision`, `add_latency_ms`.
 
 ### Changed
 
-- Store tags as a Hash for JSON-backed columns and as JSON text for fallback columns.
-- Keep internal usage metadata such as cache token counts out of stored attribution tags.
-- Normalize provider-prefixed model IDs like `openai/gpt-4o-mini` for built-in price lookup.
-- Normalize configured OpenAI-compatible host keys to lowercase after configuration.
-- Avoid double fuzzy-match passes during price lookup.
-- Widen generated cost decimal columns to `precision: 20, scale: 8`.
-- Count Gemini `thoughtsTokenCount` as output tokens for better thinking-mode cost estimates.
-- Warn when Faraday exposes an unreadable streaming/SSE response body.
-- Document tag storage behavior, budget guardrail limits, known limitations, common tag scopes, and upgrade flows.
-- Clarify that budget errors raised after a response occur after the event has been recorded.
-- Route custom storage exceptions that inherit from `LlmCostTracker::Error` through `storage_error_behavior`.
+- Tags stored as Hash for JSON-backed columns, JSON text for fallback.
+- Normalize provider-prefixed model IDs (e.g. `openai/gpt-4o-mini`) for price lookup.
+- Widen generated cost columns to `precision: 20, scale: 8`.
+- Count Gemini `thoughtsTokenCount` as output tokens.
+- Warn on unreadable streaming/SSE response bodies.
+- Route storage exceptions inheriting from `LlmCostTracker::Error` through `storage_error_behavior`.
 
 ## [0.1.1] - 2026-04-17
 
 ### Fixed
 
-- Lazy-load ActiveRecord storage so `storage_backend = :active_record` persists events reliably.
-- Avoid double-counting the latest ActiveRecord event in monthly budget callbacks.
-- Track OpenAI Responses API usage via `/v1/responses`.
-- Parse OpenAI cached input token details for cache-aware cost estimates.
-- Parse Anthropic cache read and cache creation token usage under canonical metadata keys.
-- Parse Gemini cached content token usage when present.
-- Store ActiveRecord tag values as strings so `by_tag("user_id", "42")` works for numeric IDs.
+- Lazy-load ActiveRecord storage so `:active_record` persists events reliably.
+- Stop double-counting the latest event in monthly budget callbacks.
+- Track OpenAI Responses API (`/v1/responses`).
+- Parse cached/cache-read/cache-creation token details across OpenAI, Anthropic, Gemini.
+- Store tag values as strings so `by_tag("user_id", "42")` matches numeric IDs.
 
 ### Changed
 
-- Refresh built-in pricing for current OpenAI, Anthropic, and Gemini models.
-- Add cache-aware cost calculation fields for cached input, cache reads, and cache creation.
-- Tighten OpenAI URL matching to supported endpoint families only.
-- Reposition README around self-hosted Rails/Ruby cost tracking for Faraday-based clients.
+- Refresh built-in pricing for current OpenAI, Anthropic, Gemini models.
+- Cache-aware cost fields (cached input, cache reads, cache creation).
+- Tighten OpenAI URL matching to supported endpoint families.
 
 ### Added
 
-- Add ActiveRecord integration specs for persistence, tag querying, and budget callbacks.
-- Add RuboCop configuration, rake task, and CI lint step.
-- Require MFA metadata for RubyGems publishing.
+- ActiveRecord integration specs; RuboCop config + CI lint step; RubyGems MFA metadata.
 
 ## [0.1.0] - 2026-04-16
 
-### Added
-
-- Faraday middleware for automatic LLM API call interception
-- Provider parsers: OpenAI, Anthropic, Google Gemini
-- Built-in pricing table for 20+ models
-- Fuzzy model name matching (e.g. `gpt-4o-2024-08-06` → `gpt-4o`)
-- ActiveSupport::Notifications integration
-- ActiveRecord storage backend with scopes and aggregations
-- Manual `LlmCostTracker.track()` for non-Faraday clients
-- Per-user / per-feature tagging
-- Monthly budget alerts with configurable callbacks
-- Rails generator: `rails generate llm_cost_tracker:install`
-- Custom storage backend support
-- Pricing overrides via configuration
+- Faraday middleware for LLM call interception.
+- Parsers: OpenAI, Anthropic, Gemini. Built-in pricing for 20+ models with fuzzy matching.
+- `ActiveSupport::Notifications` integration; ActiveRecord backend with scopes and aggregations.
+- Manual `LlmCostTracker.track(...)` for non-Faraday clients.
+- Per-user / per-feature tagging; monthly budget alerts with configurable callbacks.
+- `rails generate llm_cost_tracker:install`; custom storage backend; pricing overrides.

data/PLAN_0.2.md

@@ -0,0 +1,488 @@
+# llm_cost_tracker v0.2.0 Plan
+
+## Goal
+
+Ship an opt-in Rails dashboard engine:
+
+```ruby
+require "llm_cost_tracker/engine"
+
+mount LlmCostTracker::Engine => "/llm-costs"
+```
+
+The dashboard is read-only and shows where a Rails app spends money on LLM APIs:
+
+- spend over time
+- top models
+- recent calls
+- call details
+- tag breakdowns such as `feature`
+- optional monthly budget status
+
+The first milestone is a useful Overview page that can be used as the README screenshot.
+
+## Non-Goals
+
+These are intentionally out of scope for v0.2.0:
+
+- built-in authorization
+- CSV or JSON export
+- alerts, webhooks, or Slack notifications
+- JavaScript charts or live updates
+- editing settings from the dashboard
+- persistent budget models
+- `/budgets`
+- `/tags` index or automatic tag-key discovery
+- timezone-aware SQL bucketing
+- hourly period grouping
+- SaaS or remote sync
+
+## Compatibility Decisions
+
+### Core Gem
+
+The core gem remains lightweight and usable outside Rails:
+
+- keep `activesupport >= 7.0, < 9.0`
+- do not add `railties` as a runtime dependency
+- keep middleware-only usage working for plain Faraday, Sinatra, Hanami, and service objects
+
+### Dashboard Engine
+
+The Engine is Rails-only and opt-in:
+
+- users must `require "llm_cost_tracker/engine"`
+- Engine requires Rails 7.1+
+- the Rails version guard must run at top level in `engine.rb`, before defining `class Engine < ::Rails::Engine`
+- `railties` is a development/test dependency only
+
+Example guard:
+
+```ruby
+unless Gem::Version.new(Rails.version) >= Gem::Version.new("7.1.0")
+  raise LlmCostTracker::Error, "LlmCostTracker::Engine requires Rails 7.1+"
+end
+```
+
+## Phase 1: Public Query Primitive
+
+Add SQL-side period grouping to `LlmCostTracker::LlmApiCall`.
+
+### API
+
+```ruby
+LlmCostTracker::LlmApiCall.group_by_period(:day).sum(:total_cost)
+LlmCostTracker::LlmApiCall.group_by_period(:month).count
+LlmCostTracker::LlmApiCall.group_by_period(:day, column: :created_at)
+```
+
+Default column: `:tracked_at`.
+
+### Supported Periods
+
+Only:
+
+- `:day`
+- `:month`
+
+Do not add `:hour` or `:week` in v0.2.0.
+
+### Return Keys
+
+Return string keys across all adapters:
+
+```ruby
+:day   # "2026-04-18"
+:month # "2026-04"
+```
+
+### SQL Strategy
+
+- PostgreSQL: `TO_CHAR(DATE_TRUNC(...), ...)`
+- MySQL: `DATE_FORMAT(...)`
+- SQLite: `strftime(...)`
+
+### Validation
+
+- period must be whitelisted
+- column must exist in `column_names`
+- invalid period or column raises `ArgumentError`
+- no `time_zone:` parameter in v0.2.0
+
+### Tests
+
+- real SQLite grouping specs
+- generated SQL expression specs for PostgreSQL/MySQL if those adapters are not in CI
+- injection tests for period and column
+- composition test:
+
+```ruby
+LlmCostTracker::LlmApiCall
+  .this_month
+  .where(provider: "openai")
+  .group_by_period(:day)
+  .sum(:total_cost)
+```
+
+## Phase 2: Engine Skeleton
+
+Add the minimal Rails Engine structure:
+
+```text
+lib/llm_cost_tracker/engine.rb
+app/controllers/llm_cost_tracker/application_controller.rb
+app/controllers/llm_cost_tracker/dashboard_controller.rb
+app/views/layouts/llm_cost_tracker/application.html.erb
+config/routes.rb
+spec/dummy/
+```
+
+### Requirements
+
+- isolated namespace: `isolate_namespace LlmCostTracker`
+- no automatic loading for non-Rails users
+- no asset pipeline dependency
+- no JavaScript
+- inline CSS in the Engine layout
+- all CSS classes prefixed with `.lct-`
+- minimal `spec/dummy` Rails app for Engine request specs
+
+### Acceptance
+
+- dummy app mounts the Engine at `/llm-costs`
+- `GET /llm-costs` returns 200
+- empty database shows an intentional empty state
+- missing `llm_api_calls` table shows a friendly setup error
+
+## Phase 3: Dashboard Data Layer
+
+Use plain Ruby objects under:
+
+```text
+app/services/llm_cost_tracker/dashboard/
+```
+
+### Filter
+
+Parses dashboard params and returns an ActiveRecord relation.
+
+Supported params:
+
+- `from`
+- `to`
+- `provider`
+- `model`
+- `tag[key]=value`
+
+Rules:
+
+- parse `from` and `to` with `Date.iso8601`
+- ignore invalid dates
+- use AR placeholders for provider/model
+- parse all `params[:tag]` keys as a hash
+- pass multi-key tag filters to `by_tags`
+- validate tag keys with the same whitelist as `group_by_tag`
+
+Example:
+
+```text
+?tag[feature]=chat&tag[user_id]=42
+```
+
+becomes:
+
+```ruby
+scope.by_tags("feature" => "chat", "user_id" => "42")
+```
+
+### Page
+
+Use a small immutable object, not a large service:
+
+```ruby
+Dashboard::Page = Data.define(:page, :per)
+```
+
+Rules:
+
+- `page` minimum: 1
+- `per` default: 50
+- `per` maximum: 200
+- expose `limit`, `offset`, `prev_page?`, and `next_page?`
+
+### OverviewStats
+
+Compute:
+
+- total spend
+- total calls
+- average cost per call
+- average latency only if `latency_ms` exists
+- monthly budget status only if `LlmCostTracker.configuration.monthly_budget` is set
+
+Do not compute `known_pricing_rate` in v0.2.0.
+
+### TimeSeries
+
+Uses `group_by_period(:day).sum(:total_cost)`.
+
+Rules:
+
+- default range: last 30 days
+- fill missing days with zero
+- output array:
+
+```ruby
+[{ label: "2026-04-01", cost: 0.0 }]
+```
+
+### TopModels
+
+Compute:
+
+- provider
+- model
+- calls
+- total cost
+- average cost per call
+- input tokens
+- output tokens
+- average latency if available
+
+### TopTags
+
+Only for configured keys.
+
+Default keys:
+
+```ruby
+["feature"]
+```
+
+No automatic tag-key discovery in v0.2.0.
+
+## Phase 4: Dashboard Pages
+
+### Overview: `GET /`
+
+The main screenshot-worthy page.
+
+Show:
+
+- total spend
+- total calls
+- average cost per call
+- average latency if available
+- monthly budget status if configured
+- daily spend table with CSS bars
+- top 5 models
+- cost by `feature` tag if data exists
+
+Budget wording:
+
+> Soft monthly limit. Blocking is not atomic under concurrency.
+
+### Calls Index: `GET /calls`
+
+Filters:
+
+- `from`
+- `to`
+- `provider`
+- `model`
+- `tag[key]=value`
+- `page`
+- `per`
+
+Columns:
+
+- created_at
+- provider
+- model
+- input tokens
+- output tokens
+- cache tokens if present
+- total cost
+- latency if available
+- tags summary
+- details link
+
+Rules:
+
+- newest first
+- max `per=200`
+- one count query and one paginated query
+- no N+1 behavior
+
+### Call Details: `GET /calls/:id`
+
+Show:
+
+- all stored columns
+- token breakdown
+- cost breakdown
+- latency if available
+- tags as pretty JSON
+- metadata if present
+
+Missing records render a friendly 404 inside the Engine layout.
+
+### Models: `GET /models`
+
+Show rows grouped by provider/model:
+
+- provider
+- model
+- calls
+- total cost
+- average cost per call
+- input tokens
+- output tokens
+- average latency if available
+
+Default sort: total cost descending.
+
+### Tag Breakdown: `GET /tags/:key`
+
+Validate `key` using the same tag-key whitelist as `group_by_tag`.
+
+Show:
+
+- tag value
+- calls
+- total cost
+- average cost per call
+
+Invalid keys render a friendly 400.
+
+Do not add `/tags` index in v0.2.0.
+
+## Graceful Degradation
+
+The dashboard must not explode when optional pieces are missing.
+
+Handle:
+
+- empty database
+- missing `llm_api_calls` table
+- missing `latency_ms`
+- text `tags` fallback instead of JSONB
+- malformed legacy tag JSON
+- unknown-pricing rows with `total_cost = nil`
+- no configured monthly budget
+
+## Security
+
+- dashboard is read-only
+- routes are GET-only
+- keep `protect_from_forgery with: :exception`
+- no built-in auth
+- README must show Basic Auth and Devise examples
+- validate every param through `Dashboard::Filter`
+- do not log full tags or request details from the Engine
+
+README warning:
+
+> Do not expose this dashboard publicly. Tags may contain internal user, tenant, or feature identifiers.
+
+## Styling
+
+- ERB templates
+- no JS
+- no external fonts
+- no external CSS
+- no Chart.js
+- no Tailwind dependency
+- inline `<style>` in layout
+- `.lct-` class prefix
+- CSS bar charts through inline custom properties
+
+Example:
+
+```html
+<div class="lct-bar" style="--lct-width: 73%"></div>
+```
+
+## Testing Plan
+
+### Core Specs
+
+- `group_by_period(:day)`
+- `group_by_period(:month)`
+- invalid period
+- invalid column
+- composition with existing scopes
+
+### Engine Request Specs
+
+- `/` empty DB
+- `/` seeded DB
+- `/calls`
+- `/calls` filters narrow results
+- `/calls/:id`
+- `/calls/:missing`
+- `/models`
+- `/tags/feature`
+- invalid tag key returns 400
+- missing table renders setup error
+
+### Service Specs
+
+- `Dashboard::Filter`
+- `Dashboard::Page`
+- `Dashboard::TimeSeries`
+- `Dashboard::OverviewStats`
+- `Dashboard::TopModels`
+- `Dashboard::TopTags`
+
+### CI
+
+- Ruby 3.3, 3.4
+- Rails Engine specs on Rails 7.1, 7.2, 8.0
+- SQLite default
+- PostgreSQL job for period grouping and tag grouping
+- MySQL best-effort only; not required for v0.2.0 CI
+
+## Documentation
+
+README additions:
+
+- Dashboard quick start
+- mount snippet
+- Basic Auth snippet
+- Devise snippet
+- warning not to expose dashboard publicly
+- note that Engine requires Rails 7.1+
+- note that core middleware remains usable without Rails
+
+## Release Strategy
+
+1. Work on `codex/engine-dashboard`.
+2. Implement `group_by_period`.
+3. Add Engine skeleton.
+4. Build Overview first.
+5. Build Calls index.
+6. Build Call details.
+7. Build Models.
+8. Build `/tags/:key`.
+9. Dogfood in a real Rails app.
+10. Release `0.2.0.alpha1`.
+11. Fix issues from real usage.
+12. Release `0.2.0.rc1`.
+13. Release final `0.2.0`.
+
+## v0.2.0 Acceptance Criteria
+
+The release is ready when:
+
+- `group_by_period(:day/:month)` is tested and documented
+- Engine is opt-in and requires Rails 7.1+
+- non-Rails core usage does not gain Rails runtime dependencies
+- `/llm-costs` renders without JS or asset pipeline dependencies
+- empty DB and missing table states are friendly
+- seeded dashboard shows useful spend data
+- filters cannot SQL-inject
+- Overview is good enough for README screenshot
+- README includes auth snippets
+- full test suite and RuboCop pass
+- alpha has been tested in one real Rails app