prompt_canary 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 792f396d1e355446cdc4855cf306d531b04f1dc4638414a7a7ac11cc51f8dde0
+  data.tar.gz: 7066dc3b189eb3ca99965b49893cc540ae55ede627b8110020ae10abc4dbaa82
+SHA512:
+  metadata.gz: 5cb8a51f28ae5666f2e1bf3f6f0213905cf736fc56612ff465d0dadd57df8596292579452e843cef7de5e8e1db8c5bfbd02c9b0ad40a88379c99c885bb084eec
+  data.tar.gz: c0a37b35f57769a453d479ffc4aab381339b50c641ccd906312c760409826131798afe8aefa75cd66a3fc8a4595645849aeea358cfad8d08ffd5cf2607947e88

data/CHANGELOG.md

@@ -0,0 +1,86 @@
+## [Unreleased]
+
+## [0.3.0] - 2026-06-03
+
+### Added
+
+- `PromptCanary.promote` — marks a version as primary at runtime; the previous primary becomes a candidate. Writes `PrimaryOverride` to DB so the designation survives restarts. Does not change traffic percentages.
+- `PromptCanary.set_canary` — adjusts a version's canary traffic percentage at runtime without a deploy. Independent of status. Raises `ArgumentError` if percent is zero — use `demote` to stop traffic.
+- `PromptCanary::PromptEvent` AR model — persists a full audit trail to `prompt_canary_events` with event type, previous/new status, previous/new percent, reason, triggered-by, and monitor metric fields.
+- All deployment operations (`promote`, `demote`, `restore`, `set_canary`) write audit events to `prompt_canary_events`.
+- `promote` writes two events: one for the promoted version and a `superseded` event for the displaced primary.
+- Monitor passes `triggered_by: "monitor"` and metric metadata (`triggering_metric`, `triggering_value`, `triggering_threshold`) through `demote` so auto-rollbacks are distinguishable from manual ones in the audit trail.
+- `CannotDemotePrimaryError` — raised when attempting to demote the primary version with no other viable candidate, preventing the system from being left without a route target.
+- `DemotedVersionError` — raised when `set_canary` targets a demoted version. Call `restore` first.
+- `Version#demoted?` — tracks demoted state in memory for non-AR storage paths.
+- `Deployment` module — extracted from `PromptCanary` to group the four runtime operations (`promote`, `demote`, `restore`, `set_canary`) with a clear SRP boundary.
+- CLI `promote` subcommand — `prompt_canary promote PromptClass version [--reason "..."]`
+- CLI `history` subcommand — `prompt_canary history PromptClass [--since 7d]`; validates period format.
+- CLI `status` subcommand — `prompt_canary status PromptClass`; shows current status and traffic for each version.
+- Dashboard Promote button — appears on the show page for candidate versions; absent for primary and demoted versions.
+- Dashboard deployment history — show page surfaces the last 10 `PromptEvent` rows so operators can see what happened to a prompt without leaving the dashboard.
+- Generator now creates all four tables in a single migration: `prompt_canary_calls`, `prompt_canary_rollout_overrides`, `prompt_canary_primary_overrides`, `prompt_canary_events`.
+
+### Changed
+
+- `demote` is now idempotent via `find_or_initialize_by` — demoting an already-demoted version does not error or create duplicate rows.
+- `restore` restores the pre-demotion traffic percentage (stored at demotion time) rather than defaulting to zero.
+- Router reads `PrimaryOverride` before falling back to first-declared default — DB-promoted versions survive restarts.
+- `--since` validation in `history` command — invalid formats (e.g. `abc`, `0d`) exit with a clear error instead of silently querying all records.
+
+### Breaking Changes
+
+| Change | Migration |
+|---|---|
+| `stable: true` removed from version DSL | Delete `stable: true` from all version declarations. The first declared version is primary automatically. |
+| `set_canary(prompt, version, 0)` raises `ArgumentError` | Use `PromptCanary.demote` to stop traffic to a version. |
+
+## [0.2.0] - 2026-05-30
+
+### Added
+
+- `PromptCanary::Promptable` module — compose prompt behavior via `include` without consuming the host class's superclass slot
+- `PromptCanary::AdapterFactory` and `StorageFactory` — registry pattern replacing case statements; raises `ConfigurationError` immediately for unknown values
+- `PromptCanary::PromptExecutor` — extracts router → adapter → recorder → result orchestration out of `Promptable#call`
+- `Configuration#validate!` — centralizes configuration validation; called at end of `configure` block
+- Dynamic system prompts — `system` DSL field accepts a block receiving call-time args, enabling runtime data in prompt text
+- `RollbackRule` value object — replaces plain hashes; owns comparison logic via `violated_by?`
+- `Recorder#stats` — returns `{ call_count:, error_rate:, latency_p95:, last_called_at: }` over a configurable window
+- `PromptCanary.stats` — convenience method for Rails console access; no setup required
+- `PromptCanary.register_prompt` / `registered_prompts` — prompt class registry populated automatically when `Promptable` is included
+- `PromptCanary::Railtie` — loads prompt classes from `app/prompts/` at boot; warns when `:sqlite` is configured in a Rails context
+- `PromptCanary::MonitorJob` — `ActiveJob::Base` subclass that iterates registered prompts and runs the monitor; host app only schedules it
+- `Storage::ActiveRecord` — AR-backed storage using the host app's existing database connection and migration system
+- `PromptCanary::RolloutOverride` — AR model persisting demotions to `prompt_canary_rollout_overrides`; survives restarts and redeploys
+- `PromptCanary.restore` — clears a demotion override and emits `prompt_canary.restored`; router immediately resumes class-defined rollout
+- `rails generate prompt_canary:install` — creates both `prompt_canary_calls` and `prompt_canary_rollout_overrides` migrations and mounts the engine
+- `PromptCanary::Engine` — mountable Rails engine with read-only dashboard; index and show views display per-version stats, active/inactive row styling, and demoted badge
+- Router reads `prompt_canary_rollout_overrides` on every request when AR is available — demoted versions receive zero traffic without a redeploy
+- Dashboard active/inactive styling — inactive versions (zero rollout or demoted) rendered at reduced opacity; order is stable so a status change is visible without reordering
+
+### Changed
+
+- `PromptCanary::Prompt` is deprecated — `include PromptCanary::Promptable` is the correct pattern; `Prompt` emits a deprecation warning from `inherited`
+- `PromptCanary.demote` writes a `RolloutOverride` record when using AR storage instead of mutating in-memory version state — class-defined rollout is preserved so restore requires no knowledge of the original value
+- Adapter gems (`anthropic`, etc.) are the caller's dependency — not declared in gemspec to avoid forcing unused adapters on callers using custom implementations
+
+### Fixed
+
+- `frozen_string_literal` consistency across all files
+
+## [0.1.0] - 2026-05-27
+
+### Added
+
+- `Prompt` DSL — declare versioned LLM prompts as Ruby classes with `version`, `stable`, `model`, `system`, `rollout`, `rollout_to`, and `rollback_if`
+- `Router` — deterministic CRC32-based percentage routing and predicate routing; falls back to stable on missing `call_id` or predicate exception
+- `Adapters::Anthropic` — Anthropic SDK v1.43.0 adapter; captures latency, token usage, and errors in a uniform telemetry hash
+- `Recorder` — writes call telemetry to storage; computes `error_rate` and `latency_p95` (nearest-rank) over configurable request windows
+- `Storage::Memory` — in-process storage for tests and development
+- `Storage::SQLite` — persistent SQLite storage for production use
+- `Monitor` — evaluates `rollback_if` rules against recorded metrics; calls `PromptCanary.demote` when a rule fires
+- `PromptCanary.demote` — zeros a version's rollout percent and emits a `prompt_canary.demoted` notification
+- `PromptCanary.subscribe` — simple pub/sub for demotion notifications; no ActiveSupport dependency
+- `Result` — immutable value object returned by `Prompt.call`: `text`, `version_used`, `model`, `latency_ms`, `tokens`, `error`, `recorded_at`
+- `CLI` — `prompt_canary demote PromptClass version --reason "..."` for manual rollbacks from scripts and cron jobs
+- Configuration validation at `configure` time — raises `ConfigurationError` immediately if `adapter` or `storage` is not set

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to PromptCanary
+
+Bug reports and pull requests are welcome on GitHub. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Getting started
+
+```bash
+git clone https://github.com/[USERNAME]/prompt_canary
+cd prompt_canary
+bin/setup
+bundle exec rake   # runs tests + lint; everything should be green before you start
+```
+
+## Commit message format
+
+This project uses a consistent commit message format. Copy and paste the template below for each commit — fill in the plain values, no labels:
+
+```
+FIX: Add router fallback for zero-percent rollout
+
+(G)
+
+Ensure the router returns the primary version when rollout percent is
+explicitly set to 0, not just when omitted.
+```
+
+Fields in order:
+1. **Subject** — `TYPE: Short summary of the change`. Type is one of: `FEATURE`, `FIX`, `DOCUMENTATION`, `STYLE`, `REFACTOR`, `CHORE`
+2. **Status** — almost always `(G)`. Only commit when all tests are passing. `(R)` exists but should be used only in rare exceptional circumstances.
+3. **Description** — fuller explanation of what changed and why
+
+**We only commit green.** Run `bundle exec rake` before every commit and confirm the suite passes. A red commit should be the exception, not the norm.
+
+## Development workflow
+
+This project is built test-first. Before writing any production code, write a failing test that requires it. See [claude/PLAN.md](claude/PLAN.md) §4 for the full TDD methodology this project follows.
+
+## Running tests
+
+```bash
+bundle exec rake spec                              # full suite
+bundle exec rspec spec/path/to/foo_spec.rb        # single file
+bundle exec rspec spec/path/to/foo_spec.rb:42     # single example
+bundle exec rubocop                               # lint
+```

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Rockwell Windsor Rice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,338 @@
+# PromptCanary
+
+[![CI](https://github.com/rockwellwindsor/prompt_canary/actions/workflows/main.yml/badge.svg)](https://github.com/rockwellwindsor/prompt_canary/actions/workflows/main.yml)
+[![Gem Version](https://badge.fury.io/rb/prompt_canary.svg)](https://badge.fury.io/rb/prompt_canary)
+
+Canary deployments for LLM prompts in Ruby. Declare prompts as versioned Ruby classes, route traffic by percentage or predicate, record telemetry, and automatically roll back misbehaving versions when error rate or latency exceeds a configured threshold.
+
+## Design philosophy
+
+PromptCanary's value is in routing, telemetry, and rollback — not in where your prompt text lives. You can declare versions directly in Ruby classes, load them from database records at boot, or both. Either way the gem handles traffic splitting, call recording, and automatic demotion identically.
+
+## Installation
+
+```bash
+bundle add prompt_canary
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "prompt_canary"
+```
+
+## Rails Setup
+
+Run the install generator:
+
+```bash
+rails generate prompt_canary:install
+```
+
+This creates a single migration that sets up all four tables (`prompt_canary_calls`, `prompt_canary_rollout_overrides`, `prompt_canary_primary_overrides`, `prompt_canary_events`) and mounts the engine in `config/routes.rb`. Then run:
+
+```bash
+rails db:migrate
+```
+
+Add the adapter gem to your Gemfile — PromptCanary does not pull it in automatically:
+
+```ruby
+gem "anthropic"  # required when using adapter: :anthropic
+```
+
+Configure in `config/initializers/prompt_canary.rb`:
+
+```ruby
+PromptCanary.configure do |c|
+  c.adapter = :anthropic      # required
+  c.api_key = ENV["ANTHROPIC_API_KEY"]
+  c.storage = :active_record  # recommended for Rails
+end
+```
+
+## Configuration
+
+```ruby
+PromptCanary.configure do |c|
+  c.adapter = :anthropic  # required
+  c.storage = :sqlite     # :sqlite, :active_record, or :memory (tests)
+end
+```
+
+Both `adapter` and `storage` are required. `ConfigurationError` is raised immediately if either is missing or unknown — not at first call.
+
+Use `:active_record` in Rails apps, `:sqlite` for standalone scripts, and `:memory` in tests.
+
+## Defining a Prompt
+
+Include `PromptCanary::Promptable` in any class and declare versions using the DSL:
+
+```ruby
+class InvoiceExtractor
+  include PromptCanary::Promptable
+
+  version "v1" do
+    model  "claude-opus-4-7"
+    system "Extract structured data from this invoice."
+  end
+end
+```
+
+The first declared version is automatically treated as primary — no flag needed. Place prompt classes in `app/prompts/` — the Railtie loads them automatically on boot.
+
+## Loading Prompts from the Database
+
+Declaring versions in the class body and loading them from database records are equally supported patterns. The DSL works the same either way — it is registering `Version` objects regardless of where the data comes from.
+
+To load from the DB, call the DSL in an initializer after the connection is established:
+
+```ruby
+# config/initializers/prompt_canary.rb
+PromptCanary.configure do |c|
+  c.adapter = :anthropic
+  c.storage = :active_record
+end
+
+PromptRecord.all.each do |record|
+  klass = record.prompt_class.constantize
+  klass.version(record.version_name) do
+    model  record.model
+    system record.system_prompt
+  end
+end
+```
+
+Choose whichever approach fits your team's operational needs. The gem has no opinion on where prompt text lives.
+
+## Calling a Prompt
+
+```ruby
+result = InvoiceExtractor.call(user_message: "Invoice #123")
+
+result.text          # => "Here is the extracted data..."
+result.version_used  # => "v1"
+result.model         # => "claude-opus-4-7"
+result.latency_ms    # => 312
+result.tokens        # => { input: 50, output: 120 }
+result.error         # => nil (or the exception if the adapter failed)
+```
+
+`call` always returns a `Result` — errors are captured in `result.error`, not raised.
+
+## Routing Traffic
+
+### Percentage rollout
+
+```ruby
+class InvoiceExtractor
+  include PromptCanary::Promptable
+
+  version "v1" do
+    model  "claude-opus-4-7"
+    system "Extract structured data from this invoice."
+  end
+
+  version "v2" do
+    model  "claude-opus-4-7"
+    system "Extract structured data. Return JSON."
+    rollout percent: 10
+  end
+end
+```
+
+Pass a `call_id` in context for deterministic routing — the same `call_id` always produces the same version:
+
+```ruby
+InvoiceExtractor.call(user_message: "Invoice #123", context: { call_id: current_user.id })
+```
+
+### Predicate rollout
+
+Route to a version based on any condition:
+
+```ruby
+version "v2" do
+  model  "claude-opus-4-7"
+  system "Extract structured data. Return JSON."
+  rollout_to { |ctx| ctx[:user]&.fetch(:beta, false) }
+end
+```
+
+```ruby
+InvoiceExtractor.call(
+  user_message: "Invoice #123",
+  context: { user: { id: 42, beta: true } }
+)
+# => routes to v2 for beta users
+```
+
+If the predicate raises, the router falls back to the primary version — always safe.
+
+## Canary Traffic
+
+Traffic percentage and version status are independent controls. `rollout percent:` sets the initial split at declaration time. `set_canary` adjusts it at runtime without a deploy:
+
+```ruby
+PromptCanary.set_canary(InvoiceExtractor, "v2", 20)  # send 20% to v2
+PromptCanary.set_canary(InvoiceExtractor, "v2", 50)  # ramp up to 50%
+PromptCanary.set_canary(InvoiceExtractor, "v2", 80)  # almost there
+```
+
+Passing `0` to `set_canary` is not allowed — use `demote` to stop traffic. This keeps the audit trail unambiguous.
+
+### Typical canary ramp
+
+```
+v1: primary,   100% traffic
+v2: candidate,  20% traffic  ← set_canary(InvoiceExtractor, "v2", 20)
+                              ← watch telemetry
+v2: candidate,  50% traffic  ← set_canary(InvoiceExtractor, "v2", 50)
+                              ← looks good
+v2: primary,    50% traffic  ← promote(InvoiceExtractor, "v2")
+v2: primary,   100% traffic  ← demote(InvoiceExtractor, "v1")
+```
+
+Promoting v2 changes its status only — it does not flip traffic to 100%. The traffic ramp is a separate deliberate step.
+
+## Promote and Demote
+
+**Status** (primary / candidate / demoted) and **traffic percentage** are separate, independent concepts.
+
+- **promote** — marks a version as primary. The previous primary becomes a candidate. Traffic percentages are not changed.
+- **demote** — sets status to demoted and zeros traffic immediately. This is the emergency brake.
+- **restore** — returns a demoted version to candidate status and restores its pre-demotion traffic percentage.
+
+```ruby
+PromptCanary.promote(InvoiceExtractor, "v2")
+PromptCanary.promote(InvoiceExtractor, "v2", reason: "canary passed")
+
+PromptCanary.demote(InvoiceExtractor, "v2")
+PromptCanary.demote(InvoiceExtractor, "v2", reason: "error rate spike")
+
+PromptCanary.restore(InvoiceExtractor, "v2")
+```
+
+Attempting to demote the primary version when no other viable candidate exists raises `CannotDemotePrimaryError` — the system is never left without a route target.
+
+All status operations write an audit event to `prompt_canary_events`.
+
+## Auto-Rollback
+
+Define rollback rules on a version:
+
+```ruby
+version "v2" do
+  model  "claude-opus-4-7"
+  system "Extract structured data. Return JSON."
+  rollout percent: 10
+  rollback_if :error_rate,  greater_than: 0.05, over: 100
+  rollback_if :latency_p95, greater_than: 2000, over: 100
+end
+```
+
+### In Rails
+
+`PromptCanary::MonitorJob` is included and ready to queue:
+
+```ruby
+# config/initializers/prompt_canary.rb or a scheduler
+PromptCanary::MonitorJob.set(wait: 5.minutes).perform_later
+```
+
+Schedule it with any background job backend (Sidekiq, GoodJob, Solid Queue, etc.).
+
+### Standalone
+
+```ruby
+recorder = PromptCanary::Recorder.new(storage: PromptCanary::Storage::SQLite.new)
+PromptCanary::Monitor.new(recorder: recorder).evaluate(InvoiceExtractor)
+```
+
+When a rule fires, `PromptCanary.demote` is called automatically — the version's rollout is zeroed, a `prompt_canary.demoted` notification is emitted, and a monitor-triggered audit event is written.
+
+## CLI
+
+```bash
+# Promote a version to primary
+prompt_canary promote InvoiceExtractor v2
+prompt_canary promote InvoiceExtractor v2 --reason "canary passed"
+
+# Demote a version (emergency stop)
+prompt_canary demote InvoiceExtractor v2 --reason "error rate spike"
+
+# Show current status and traffic for all versions
+prompt_canary status InvoiceExtractor
+
+# Show deployment history
+prompt_canary history InvoiceExtractor
+prompt_canary history InvoiceExtractor --since 7d
+```
+
+## Dashboard
+
+The engine mounts a web dashboard at the path configured in your routes (default `/prompt_canary`):
+
+- **Index** — all registered prompt classes with per-version call counts, error rates, P95 latency, and last-called timestamps
+- **Show** — version breakdown with a Promote button for candidate versions, deployment history from the audit trail, and the 50 most recent calls with per-call latency, token counts, and error detail
+
+No authentication is wired in by default. Protect the mount point with your app's existing auth if needed:
+
+```ruby
+authenticate :user, ->(u) { u.admin? } do
+  mount PromptCanary::Engine, at: "/prompt_canary"
+end
+```
+
+## Notifications
+
+Subscribe to deployment events:
+
+```ruby
+PromptCanary.subscribe("prompt_canary.promoted") do |payload|
+  puts "#{payload[:prompt]} #{payload[:version]} promoted"
+end
+
+PromptCanary.subscribe("prompt_canary.demoted") do |payload|
+  puts "#{payload[:prompt]} #{payload[:version]} demoted — #{payload[:reason]}"
+end
+
+PromptCanary.subscribe("prompt_canary.restored") do |payload|
+  puts "#{payload[:prompt]} #{payload[:version]} restored"
+end
+```
+
+## Examples
+
+Two runnable scripts are included in `examples/`. Both use a stubbed adapter and require no API key:
+
+```bash
+# Full call flow — routing, result structure, version distribution
+bundle exec ruby examples/demo.rb
+
+# Auto-rollback demo — seeds synthetic errors, runs monitor, watches demotion fire
+bundle exec ruby examples/auto_rollback.rb
+```
+
+Pass `--real` to `demo.rb` to hit the Anthropic API directly (requires `ANTHROPIC_API_KEY`):
+
+```bash
+ANTHROPIC_API_KEY=sk-... bundle exec ruby examples/demo.rb --real
+```
+
+## Development
+
+```bash
+bin/setup                                    # install dependencies
+bundle exec rake                             # run tests + lint
+bundle exec rspec spec/foo_spec.rb:42        # run a single example
+bin/console                                  # interactive prompt with gem loaded
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/controllers/prompt_canary/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module PromptCanary
+  class ApplicationController < ActionController::Base
+  end
+end