v0.6.0: install generator, auto-loading engine under Rails, release workflow

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: danielstpaul

.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+# Publishes to RubyGems via Trusted Publishing (OIDC — no API key stored).
+# One-time setup on rubygems.org (gem owner, in the browser):
+#   Profile → Trusted publishers → add publisher for gem "ruby_llm-resilience"
+#   with repository danielstpaul/ruby_llm-resilience and workflow release.yml.
+# Then: create a GitHub Release (or run this manually) and it ships.
+
+on:
+  release:
+    types: [ published ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  push:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - run: bundle exec rspec
+      - uses: rubygems/release-gem@v1

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-14
+
+Rails DX:
+
+- `rails g resilience:install` — writes a fully-commented initializer
+  covering every configuration seam
+- The dashboard engine now loads automatically under Rails (no Gemfile
+  `require:` needed; mounting stays opt-in). Non-Rails usage unchanged —
+  the core still has zero dependencies
+- RubyGems Trusted Publishing release workflow (.github/workflows/release.yml)
+
 ## [0.5.0] - 2026-07-14
 
 - Dashboard table: click-to-sort columns (text/numeric aware) and a

README.md

@@ -35,6 +35,12 @@ outage.
 gem "ruby_llm-resilience"
 ```
 
+```bash
+rails g resilience:install   # writes a fully-commented initializer
+```
+
+Outside Rails, or by hand:
+
 ```ruby
 # config/initializers/resilience.rb
 RubyLLM::Resilience.configure do |c|

lib/generators/resilience/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RubyLLM
+  module Resilience
+    # rails g resilience:install
+    #
+    # Writes a fully-commented initializer covering every configuration seam.
+    # (Namespaced inside RubyLLM::Resilience — the top-level ::Resilience
+    # constant is reserved for the opt-in shorthand alias.)
+    class InstallGenerator < Rails::Generators::Base
+      namespace "resilience:install"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/resilience.rb with a commented example configuration"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/resilience.rb"
+      end
+
+      def show_next_steps
+        say <<~NEXT, :green
+
+          ruby_llm-resilience installed.
+
+          Next steps:
+            1. Review config/initializers/resilience.rb — the defaults work,
+               but multi-process apps should configure a shared cache_store.
+            2. Optional dashboard: mount it behind YOUR auth in config/routes.rb:
+                 mount RubyLLM::Resilience::Engine => "/resilience"
+               (it 404s everything until dashboard_auth is configured — see the
+               initializer.)
+            3. Guard a call:
+                 RubyLLM::Resilience.run("api:openai:embeddings") { RubyLLM.embed(text) }
+        NEXT
+      end
+    end
+  end
+end

lib/generators/resilience/templates/initializer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# ruby_llm-resilience — circuit breakers and fallback chains for LLM calls.
+# Docs: https://github.com/danielstpaul/ruby_llm-resilience
+#
+# Everything below is optional; the gem works with defaults out of the box
+# (per-process memory store, threshold 5, cooldown 120s). The two settings
+# most apps DO want are cache_store (multi-process correctness) and
+# fallback_models (the actual routing).
+RubyLLM::Resilience.configure do |config|
+  # --- Store -----------------------------------------------------------
+  # REQUIRED for multi-process apps: the default MemoryStore is per-process,
+  # so a breaker tripped in one worker stays closed in the others. Any store
+  # with read / write(expires_in:, unless_exist:) / increment(expires_in:) /
+  # delete / delete_multi works — Redis is the usual choice:
+  #
+  # config.cache_store = ActiveSupport::Cache::RedisCacheStore.new(
+  #   url: ENV["REDIS_URL"], namespace: "circuit_breaker"
+  # )
+
+  # --- Breaker knobs ----------------------------------------------------
+  # config.failure_threshold       = 5    # consecutive failures before trip
+  # config.cooldown_seconds        = 120  # open duration before a probe
+  # config.failures_window_seconds = 3600 # failure-counter window
+  #
+  # Per-service overrides (a fast-recovery moderation endpoint shouldn't
+  # share a cooldown with an expensive batch endpoint):
+  # config.services = {
+  #   "api:openai:moderation" => { failure_threshold: 2, cooldown_seconds: 30 }
+  # }
+
+  # --- Fallback routing -------------------------------------------------
+  # One deliberate tier-hop per model is the recommended shape. Values may
+  # be a single model or an array of hops.
+  # config.fallback_models = {
+  #   "claude-haiku-4-5"  => "claude-sonnet-4-6",
+  #   "claude-sonnet-4-6" => "claude-opus-4-7",
+  #   "gemini-3.5-flash"  => "claude-sonnet-4-6"   # cross-provider safety net
+  # }
+
+  # --- Telemetry (alert on the error, graph the gauge, trend the counter) —
+  # config.on_error = ->(error, context) {
+  #   Rails.error.report(error, handled: true, context: context)
+  # }
+  # config.on_status = ->(service, state) {
+  #   Appsignal.set_gauge("circuit_breaker.state", state == :open ? 1 : 0, service: service)
+  # }
+  # config.on_fallback = ->(from:, to:, error:) {
+  #   Appsignal.increment_counter("llm.fallback", 1,
+  #     from: from[:service], to: to[:service], error: error.class.name)
+  # }
+
+  # --- Dashboard (mount RubyLLM::Resilience::Engine in routes.rb) --------
+  # DENY-BY-DEFAULT: every dashboard request 404s until you configure this.
+  # config.dashboard_auth = ->(controller) {
+  #   controller.head :not_found unless controller.respond_to?(:current_user) &&
+  #                                     controller.current_user&.admin?
+  # }
+  #
+  # Show a static fleet (instead of only breakers seen since boot), with
+  # descriptions for the About column:
+  # config.dashboard_services = %w[api:anthropic:sonnet api:openai:moderation]
+  # config.service_metadata = {
+  #   "api:anthropic:sonnet" => { description: "Coaching", consumers: "Chat" }
+  # }
+end

lib/ruby_llm/resilience.rb

@@ -8,6 +8,10 @@
 require_relative "resilience/breaker"
 require_relative "resilience/chain"
 
+# Under Rails the dashboard engine loads automatically (mounting it stays
+# opt-in via routes). Outside Rails the core works alone — zero dependencies.
+require_relative "resilience/engine" if defined?(::Rails::Engine)
+
 module RubyLLM
   # Circuit breakers and fallback chains for LLM apps.
   #

lib/ruby_llm/resilience/version.rb

@@ -2,6 +2,6 @@
 
 module RubyLLM
   module Resilience
-    VERSION = "0.5.0"
+    VERSION = "0.6.0"
   end
 end

spec/generators/install_generator_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "generators/resilience/install_generator"
+require "tmpdir"
+
+RSpec.describe RubyLLM::Resilience::InstallGenerator do
+  it "writes the commented initializer into the destination root" do
+    dest = File.join(Dir.mktmpdir, "app")
+    described_class.start([], destination_root: dest)
+
+    initializer = File.join(dest, "config/initializers/resilience.rb")
+    expect(File).to exist(initializer)
+    content = File.read(initializer)
+    expect(content).to include("RubyLLM::Resilience.configure")
+    expect(content).to include("fallback_models")
+    expect(content).to include("dashboard_auth")
+  end
+end