ruby_llm-resilience 0.6.0

data/lib/ruby_llm/resilience/shorthand.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Opt-in top-level alias:
+#
+#   require "ruby_llm/resilience/shorthand"
+#   Resilience.run("api:openai:embeddings") { ... }
+#
+# Kept out of the default require deliberately — claiming a top-level
+# ::Resilience constant is namespace pollution unless you ask for it.
+Resilience = RubyLLM::Resilience unless defined?(::Resilience)

data/lib/ruby_llm/resilience/tier_namer.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Resilience
+    # Default service_namer: maps a model name to a per-provider, per-TIER
+    # breaker name ("api:anthropic:sonnet").
+    #
+    # Tier-level (not per-model) breakers are deliberate: provider capacity
+    # incidents are tier-correlated (when Sonnet is overloaded, every Sonnet
+    # version typically is), and a version rollover (sonnet-4-5 → sonnet-4-6)
+    # shouldn't fragment health state across two breakers.
+    #
+    # Custom naming is one lambda away:
+    #   config.service_namer = ->(model) { "api:#{model}" }  # per-model
+    module TierNamer
+      module_function
+
+      def call(model_name)
+        provider = Resilience.config.provider_resolver.call(model_name).to_s
+
+        case provider
+        when "anthropic"         then anthropic(model_name)
+        when "gemini", "google"  then google(model_name)
+        when "openai"            then openai(model_name)
+        else "api:unknown:other"
+        end
+      end
+
+      def anthropic(model_name)
+        case model_name.to_s
+        when /haiku/  then "api:anthropic:haiku"
+        when /sonnet/ then "api:anthropic:sonnet"
+        when /opus/   then "api:anthropic:opus"
+        else "api:anthropic:other"
+        end
+      end
+
+      # Order matters — flash-lite must be tested before flash, since
+      # "gemini-3.1-flash-lite" matches both /flash/ and /flash-lite/.
+      def google(model_name)
+        case model_name.to_s
+        when /flash-lite/ then "api:google:flash-lite"
+        when /flash/      then "api:google:flash"
+        when /pro/        then "api:google:pro"
+        else "api:google:other"
+        end
+      end
+
+      # Order matters — `-nano` / `-mini` / `-pro` must be tested before the
+      # bare `^gpt` match (gpt-5.5-pro matches both `-pro` and `^gpt`).
+      def openai(model_name)
+        case model_name.to_s
+        when /-nano/ then "api:openai:gpt-nano"
+        when /-mini/ then "api:openai:gpt-mini"
+        when /-pro/  then "api:openai:gpt-pro"
+        when /^gpt/  then "api:openai:gpt"
+        else "api:openai:other"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/resilience/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Resilience
+    VERSION = "0.6.0"
+  end
+end

data/lib/ruby_llm/resilience.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "resilience/version"
+require_relative "resilience/errors"
+require_relative "resilience/memory_store"
+require_relative "resilience/tier_namer"
+require_relative "resilience/configuration"
+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.
+  #
+  #   RubyLLM::Resilience.configure do |c|
+  #     c.cache_store = ActiveSupport::Cache::RedisCacheStore.new(...)
+  #     c.fallback_models = { "claude-haiku-4-5" => "claude-sonnet-4-6" }
+  #     c.on_error  = ->(error, ctx) { Rails.error.report(error, context: ctx) }
+  #     c.on_status = ->(service, state) { Appsignal.set_gauge("circuit_breaker.state", state == :open ? 1 : 0, service:) }
+  #   end
+  #
+  #   RubyLLM::Resilience.run("api:openai:embeddings") { RubyLLM.embed(text) }
+  module Resilience
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      # Configure once at boot; the configuration freezes afterwards so
+      # fiber/thread safety comes from immutability. Use
+      # reset_configuration! in tests.
+      def configure
+        @config ||= Configuration.new
+        yield @config
+        @config.freeze
+        @config
+      end
+
+      def reset_configuration!
+        @config = Configuration.new
+        Breaker.reset_registry!
+        @config
+      end
+
+      def run(service, &block)
+        Chain.run(service, &block)
+      end
+
+      def run_with_model_fallback(primary_model, fallback: :map, &block)
+        Chain.run_with_model_fallback(primary_model, fallback: fallback, &block)
+      end
+
+      def run_with_fallback(*steps)
+        Chain.run_with_fallback(*steps)
+      end
+
+      def trippable?(error)
+        config.resolved_trippable_errors.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Convenience: the breaker name the configured service_namer would
+      # assign to a model.
+      def service_for(model_name)
+        config.service_namer.call(model_name)
+      end
+
+      # Fallback routing grouped by breaker service, for dashboards:
+      #   { "api:anthropic:haiku" => ["claude-haiku-4-5 → claude-sonnet-4-6"], ... }
+      # A service can carry several routes when multiple models map into the
+      # same tier breaker.
+      def fallback_routes
+        config.fallback_models.keys.each_with_object(Hash.new { |h, k| h[k] = [] }) do |model, routes|
+          service = service_for(model)
+          chain = [ model, *config.fallbacks_for(model) ]
+          routes[service] << chain.join(" → ")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm-resilience.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ruby_llm/resilience"

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-resilience
+version: !ruby/object:Gem::Version
+  version: 0.6.0
+platform: ruby
+authors:
+- Daniel St Paul
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: 'RubyLLM gives you every provider. This gives you what happens when one
+  of them goes down: tier-aware circuit breakers, cross-provider fallback chains,
+  and fail-open store semantics — battle-tested behind 450k+ production LLM calls.'
+email:
+- danielstpaul@hotmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- app/controllers/ruby_llm/resilience/breakers_controller.rb
+- app/views/layouts/ruby_llm/resilience/application.html.erb
+- app/views/ruby_llm/resilience/breakers/index.html.erb
+- config/routes.rb
+- lib/generators/resilience/install_generator.rb
+- lib/generators/resilience/templates/initializer.rb
+- lib/ruby_llm-resilience.rb
+- lib/ruby_llm/resilience.rb
+- lib/ruby_llm/resilience/breaker.rb
+- lib/ruby_llm/resilience/chain.rb
+- lib/ruby_llm/resilience/configuration.rb
+- lib/ruby_llm/resilience/engine.rb
+- lib/ruby_llm/resilience/errors.rb
+- lib/ruby_llm/resilience/memory_store.rb
+- lib/ruby_llm/resilience/shorthand.rb
+- lib/ruby_llm/resilience/tier_namer.rb
+- lib/ruby_llm/resilience/version.rb
+homepage: https://github.com/danielstpaul/ruby_llm-resilience
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/danielstpaul/ruby_llm-resilience
+  source_code_uri: https://github.com/danielstpaul/ruby_llm-resilience
+  changelog_uri: https://github.com/danielstpaul/ruby_llm-resilience/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Circuit breakers and fallback chains for LLM apps.
+test_files: []