aireview 0.2.1 → 2.0.0

data/lib/aireview/reviewer.rb

@@ -1,295 +1,70 @@
 # frozen_string_literal: true
 require_relative 'errors'
 require_relative 'output_schemas'
-require_relative 'utils'
-require 'timeout'
+require_relative 'llm_router'
+require_relative 'llm_client'
 
 module Aireview
+  # The review stages on top of the router: Generate and Critique with their
+  # own schemas and temperatures. LlmClient makes the request, LlmRouter
+  # walks the models.
   class Reviewer
-    MAX_TRANSIENT_RETRIES = 3
-    TRANSIENT_RETRY_BASE_DELAY = 2.0
-    TRANSIENT_RETRY_JITTER_RANGE = 2.0..5.0
-    PROVIDER_RETRY_DELAY_MULTIPLIER_RANGE = 2.0..2.4
-    OVERLOADED_RETRY_DELAYS = [120.0, 300.0, 300.0, 300.0].freeze
-    OVERLOADED_RETRY_JITTER_RANGE = 0.85..1.15
-    RETRY_WAIT_LOG_FORMAT = 'LLM %<stage>s request will sleep %<delay>.1fs before retry%<source>s ' \
-                            '(attempt %<next_attempt>d/%<max_attempts>d, model=%<model>s)'
+    attr_reader :router
 
-    def initialize(config:, logger: Logger.new($stderr))
+    def initialize(config:, logger: Logger.new($stderr), router: nil, client: nil)
       @config = config
       @logger = logger
-      @llm_contexts = {}
+      @router = router || LlmRouter.new(config: config, logger: logger)
+      @client = client || LlmClient.new(config: config, logger: logger)
     end
 
-    def generate(system_prompt:, user_prompt:)
-      call_llm(
-        stage: 'generate',
-        system: system_prompt,
-        user: user_prompt,
-        options: {
-          model: @config.generate_model,
-          temperature: @config.generate_temperature,
-          provider: @config.generate_provider,
-          schema: GenerateOutputSchema
-        }
-      )
+    # pinned — a request only to the model that answered last in the stage
+    # (the repair of its own JSON): its failure is RepairImpossibleError.
+    def generate(system_prompt:, user_prompt:, pinned: false)
+      prompt = LlmClient::Prompt.new(stage: 'generate', system: system_prompt, user: user_prompt,
+                                     temperature: @config.generate_temperature, schema: GenerateOutputSchema)
+      call_llm(prompt, pinned: pinned)
     end
 
-    def critique(system_prompt:, user_prompt:)
-      call_llm(
-        stage: 'critique',
-        system: system_prompt,
-        user: user_prompt,
-        options: {
-          model: @config.critique_model,
-          temperature: @config.critique_temperature,
-          provider: @config.critique_provider,
-          schema: CritiqueOutputSchema
-        }
-      )
+    def critique(system_prompt:, user_prompt:, pinned: false)
+      prompt = LlmClient::Prompt.new(stage: 'critique', system: system_prompt, user: user_prompt,
+                                     temperature: @config.critique_temperature, schema: CritiqueOutputSchema)
+      call_llm(prompt, pinned: pinned)
     end
 
-    private
-
-    def call_llm(stage:, system:, user:, options:)
-      require 'ruby_llm'
-
-      @config.require_llm_configuration!
-      context = llm_context(stage, options[:provider])
-      response = request_with_retries(stage: stage, model: options[:model]) do
-        perform_llm_request(
-          context: context,
-          stage: stage,
-          system: system,
-          user: user,
-          options: options
-        )
-      end
-      response.content
-    rescue LoadError => e
-      @logger.error("LLM #{stage} setup failed: #{e.message}")
-      raise ConfigError, "Missing dependency: #{e.message}"
-    rescue Timeout::Error
-      @logger.warn(
-        "LLM #{stage} request timed out after #{@config.llm_timeout} seconds (model=#{options[:model]})"
-      )
-      raise ApiError, "LLM request timed out after #{@config.llm_timeout} seconds. " \
-                      "Try again later or switch model via --generate-model/--critique-model."
-    end
-
-    def perform_llm_request(context:, stage:, system:, user:, options:)
-      model = options[:model]
-      temperature = options[:temperature]
-      @logger.info("LLM #{stage} request started (model=#{model}, temperature=#{temperature})")
-      chat = build_chat(context: context, stage: stage, model: model, provider: options[:provider])
-      chat = configure_reasoning(chat: chat, model: model, provider: options[:provider])
-        .with_temperature(temperature.to_f)
-        .with_schema(options[:schema])
-      chat.with_instructions(system)
-      response = Timeout.timeout(@config.llm_timeout.to_f) { chat.ask(user) }
-      @logger.info("LLM #{stage} request completed (model=#{model})")
-      response
-    end
-
-    def configure_reasoning(chat:, model:, provider:)
-      return chat unless provider == 'ollama' && model.start_with?('gpt-oss:')
-
-      chat.with_thinking(effort: :low)
-    end
-
-    def build_chat(context:, stage:, model:, provider:)
-      context.chat(model: model, provider: provider.to_sym)
-    rescue RubyLLM::ModelNotFoundError
-      @logger.warn(
-        "LLM #{stage}: model not found in RubyLLM registry; " \
-        "using fallback with incomplete model metadata " \
-        "(model=#{model}, provider=#{provider})"
-      )
-      context.chat(model: model, provider: provider.to_sym, assume_model_exists: true)
-    end
-
-    def request_with_retries(stage:, model:)
-      attempt = 0
-
-      begin
-        attempt += 1
-        yield
-      rescue StandardError => e
-        raise unless ruby_llm_api_error?(e)
-
-        @logger.warn("LLM #{stage} request failed (model=#{model}): #{e.class}: #{e.message}")
-        raise ApiError, llm_error_message(e) unless retry_llm_request?(e, attempt)
-
-        wait_before_retry(error: e, attempt: attempt, stage: stage, model: model)
-        retry
-      end
-    end
-
-    def retry_llm_request?(error, attempt)
-      transient_llm_error?(error) && attempt <= max_retries(error)
-    end
-
-    # Перегруженному провайдеру даётся на один повтор больше: 503 у Gemini
-    # держится дольше, чем rate limit или сетевой сбой.
-    def max_retries(error)
-      overloaded_llm_error?(error) ? OVERLOADED_RETRY_DELAYS.size : MAX_TRANSIENT_RETRIES
-    end
-
-    def wait_before_retry(error:, attempt:, stage:, model:)
-      retry_delay = transient_retry_delay(error: error, attempt: attempt)
-      @logger.warn(
-        format(
-          RETRY_WAIT_LOG_FORMAT,
-          stage: stage,
-          delay: retry_delay[:delay],
-          source: retry_delay_source(retry_delay),
-          next_attempt: attempt + 1,
-          max_attempts: max_retries(error) + 1,
-          model: model
-        )
-      )
-      sleep_started_at = monotonic_time
-      sleep(retry_delay[:delay])
-      log_retry_wait_completed(stage, model, monotonic_time - sleep_started_at)
-    end
-
-    def log_retry_wait_completed(stage, model, waited)
-      @logger.info(
-        format(
-          'LLM %<stage>s retry wait completed after %<waited>.1fs (model=%<model>s)',
-          stage: stage,
-          waited: waited,
-          model: model
-        )
-      )
-    end
-
-    def ruby_llm_api_error?(error)
-      defined?(RubyLLM::Error) && error.is_a?(RubyLLM::Error)
+    # Stages answered by a fallback model, for the report line.
+    def fallback_models
+      @router.fallback_models
     end
 
-    def transient_llm_error?(error)
-      error.is_a?(RubyLLM::RateLimitError) ||
-        error.is_a?(RubyLLM::ServiceUnavailableError) ||
-        error.is_a?(RubyLLM::OverloadedError)
+    # The model that answered last in the stage with its place in the chain, for the log.
+    def answered_model(stage)
+      @router.answered(stage)
     end
 
-    def monotonic_time
-      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    # Critique ran on a model below Generate in the pool (allow_weaker).
+    def critique_weaker?
+      @router.critique_weaker?
     end
 
-    def transient_retry_delay(error:, attempt:)
-      provider_delay = retry_after_seconds(error.message)
-      if provider_delay
-        multiplier = rand(PROVIDER_RETRY_DELAY_MULTIPLIER_RANGE)
-        return {
-          delay: provider_delay * multiplier,
-          provider_delay: provider_delay,
-          multiplier: multiplier,
-          strategy: :provider_hint
-        }
-      end
-
-      if overloaded_llm_error?(error)
-        base_delay = OVERLOADED_RETRY_DELAYS.fetch(attempt - 1, OVERLOADED_RETRY_DELAYS.last)
-        multiplier = rand(OVERLOADED_RETRY_JITTER_RANGE)
-        return {
-          delay: base_delay * multiplier,
-          base_delay: base_delay,
-          multiplier: multiplier,
-          strategy: :overloaded
-        }
-      end
-
-      base_delay = TRANSIENT_RETRY_BASE_DELAY * (2**(attempt - 1))
-      {
-        delay: base_delay + rand(TRANSIENT_RETRY_JITTER_RANGE),
-        provider_delay: nil,
-        multiplier: nil,
-        strategy: :fallback
-      }
-    end
-
-    def retry_delay_source(retry_delay)
-      if retry_delay[:strategy] == :overloaded
-        return format(
-          ' (overloaded backoff %<base_delay>.0fs, multiplier %<multiplier>.2fx)',
-          base_delay: retry_delay[:base_delay],
-          multiplier: retry_delay[:multiplier]
-        )
-      end
-      return '' unless retry_delay[:provider_delay]
-
-      format(
-        ' (provider retry hint %<provider_delay>.1fs, multiplier %<multiplier>.2fx)',
-        provider_delay: retry_delay[:provider_delay],
-        multiplier: retry_delay[:multiplier]
-      )
-    end
-
-    def overloaded_llm_error?(error)
-      error.is_a?(RubyLLM::ServiceUnavailableError) ||
-        error.is_a?(RubyLLM::OverloadedError)
-    end
-
-    def retry_after_seconds(message)
-      match = message.to_s.match(/retry\s+(?:in|after)\s+(\d+(?:\.\d+)?)\s*(?:s|sec|secs|second|seconds)\b/i)
-      match[1].to_f if match
-    end
-
-    def llm_error_message(error)
-      case error
-      when RubyLLM::ServiceUnavailableError, RubyLLM::OverloadedError
-        "LLM service is temporarily unavailable or overloaded: #{error.message}. " \
-        "Try again later or switch model via --generate-model/--critique-model."
-      when RubyLLM::RateLimitError
-        "LLM rate limit exceeded: #{error.message}. " \
-        "Try again later or switch model via --generate-model/--critique-model."
-      when RubyLLM::ContextLengthExceededError
-        "LLM context limit exceeded: #{error.message}. Try reducing the MR diff or ignore more paths."
-      else
-        "LLM API request failed: #{error.message}"
-      end
-    end
-
-    def llm_context(stage, provider)
-      @llm_contexts[stage] ||= build_llm_context(provider.to_s)
-    end
-
-    def build_llm_context(provider)
-      api_key = @config.provider_api_key(provider) unless provider == 'ollama'
-
-      RubyLLM.context do |ruby_config|
-        configure_http_proxy(ruby_config)
-        ruby_config.request_timeout = @config.llm_timeout.to_f
-        configure_provider(ruby_config, provider, api_key)
-      end
+    # An invalid result: the model is excluded for the stage, the next
+    # request of the stage goes to another. Returns the excluded model or nil.
+    def exclude_answered_model(stage:, reason:)
+      @router.exclude_answered(stage: stage, reason: reason)
     end
 
-    def configure_http_proxy(ruby_config)
-      return unless Aireview::Utils.present?(@config.llm_http_proxy)
-
-      ruby_config.http_proxy = @config.llm_http_proxy
-    end
+    private
 
-    def configure_provider(ruby_config, provider, api_key)
-      case provider
-      when 'gemini', 'openai', 'openrouter'
-        configure_remote_provider(ruby_config, provider, api_key)
-      when 'anthropic'
-        ruby_config.anthropic_api_key = api_key
-      when 'ollama'
-        ruby_config.ollama_api_base = @config.ollama_api_base
-      else
-        raise ConfigError, "Unsupported LLM provider: #{provider.inspect}"
+    # A pinned route giving up is not an API error for the pipeline but
+    # "repair impossible": the same fate as an invalid result.
+    def call_llm(prompt, pinned:)
+      response = @router.call(stage: prompt.stage, request_chars: prompt.chars, pinned: pinned) do |route, timeout|
+        @client.request(prompt, candidate: route.candidate, key: route.key, key_index: route.key_index,
+                                timeout: timeout)
       end
-    end
-
-    def configure_remote_provider(ruby_config, provider, api_key)
-      ruby_config.public_send("#{provider}_api_key=", api_key)
-      return unless Aireview::Utils.present?(@config.llm_api_base)
-
-      ruby_config.public_send("#{provider}_api_base=", @config.llm_api_base)
+      response.content
+    rescue RouteExhaustedError => e
+      raise RepairImpossibleError, e.message
     end
   end
 end

data/lib/aireview/stage_chains.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+require_relative 'errors'
+require_relative 'utils'
+require_relative 'model_candidate'
+require_relative 'stages'
+
+module Aireview
+  # A routing plan of independent chains: every stage has its own primary
+  # model and reserves in walking order. Critique does not depend on which
+  # model answered in Generate.
+  #
+  # The plan interface (ModelPool implements it too): chain(stage),
+  # critique_chain(after:), primary(stage), weaker?, signature, rule,
+  # pool?, pool_stage?, pool_member?, start_used?, warnings.
+  class StageChains
+    # settings — per stage: provider, model, fallbacks (the raw list from the
+    # config), max_prompt_chars. only_primary keeps one model.
+    def self.build(settings, only_primary: false)
+      chains = settings.to_h do |stage, stage_settings|
+        [stage.to_s, stage_chain(stage.to_s, stage_settings, only_primary: only_primary)]
+      end
+      new(chains)
+    end
+
+    def self.stage_chain(stage, settings, only_primary:)
+      primary = ModelCandidate.new(
+        provider: settings.fetch(:provider).to_s,
+        model: settings[:model],
+        max_prompt_chars: settings.fetch(:max_prompt_chars)
+      )
+      return [primary] if only_primary
+
+      [primary, *fallbacks(stage, Array(settings[:fallbacks]), primary)]
+    end
+
+    # A reserve without a provider inherits the stage provider, without a
+    # limit its limit.
+    def self.fallbacks(stage, items, primary)
+      items.each_with_index.map do |item, index|
+        item = ModelCandidate.parse_item(item)
+        name = "llm.#{stage}.fallbacks[#{index}]"
+        raise ConfigError, "#{name} must be a model name or a hash with model" unless item.is_a?(Hash)
+        raise ConfigError, "#{name}.model is required" if Aireview::Utils.blank?(item['model'])
+
+        limit = item['max_prompt_chars']
+        ModelCandidate.new(
+          provider: (item['provider'] || primary.provider).to_s,
+          model: item['model'].to_s,
+          max_prompt_chars: limit.nil? ? primary.max_prompt_chars : positive_limit(limit, name)
+        )
+      end
+    end
+
+    def self.positive_limit(value, name)
+      integer = Integer(value, exception: false)
+      return integer if integer&.positive?
+
+      raise ConfigError, "#{name}.max_prompt_chars must be a positive integer, got #{value.inspect}"
+    end
+
+    def initialize(chains)
+      @chains = chains
+    end
+
+    def chain(stage)
+      @chains.fetch(stage.to_s) { raise ArgumentError, "unknown LLM stage #{stage.inspect}" }
+    end
+
+    def stage?(stage)
+      @chains.key?(stage.to_s)
+    end
+
+    def critique_chain(after:)
+      chain('critique')
+    end
+
+    def primary(stage)
+      chain(stage).first
+    end
+
+    def weaker?(_critique_candidate, _generate_candidate)
+      false
+    end
+
+    def signature
+      nil
+    end
+
+    def rule
+      nil
+    end
+
+    def pool?
+      false
+    end
+
+    def pool_stage?(_stage)
+      false
+    end
+
+    def pool_member?(_model)
+      false
+    end
+
+    def start_used?(_stage)
+      false
+    end
+
+    def warnings
+      []
+    end
+  end
+end

data/lib/aireview/stages.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Aireview
+  # The two review stages: Generate finds the findings, Critique checks them.
+  # The single definition; inside the code a stage is a string.
+  STAGES = %w[generate critique].freeze
+end

data/lib/aireview/utils.rb

@@ -14,5 +14,34 @@ module Aireview
     def presence(value)
       present?(value) ? value.to_s.strip : nil
     end
+
+    # Merges settings by key: nested hashes merge, everything else (arrays
+    # included) is replaced by the right side as a whole.
+    def deep_merge(left, right)
+      left.merge(right) do |_, old_value, new_value|
+        if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+          deep_merge(old_value, new_value)
+        else
+          new_value
+        end
+      end
+    end
+
+    # Hash keys are strings at any depth: YAML, env and LLM answers arrive in
+    # different shapes, everything downstream works with one.
+    def normalize_hash(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, inner), result| result[key.to_s] = normalize_hash(inner) }
+      when Array
+        value.map { |item| normalize_hash(item) }
+      else
+        value
+      end
+    end
+
+    def dig(data, *keys)
+      keys.reduce(data) { |accumulator, key| accumulator.is_a?(Hash) ? accumulator[key] : nil }
+    end
   end
 end

data/lib/aireview/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Aireview
-  VERSION = '0.2.1'
+  VERSION = '2.0.0'
 end

data/lib/aireview.rb

@@ -16,6 +16,7 @@ require_relative 'aireview/secret_scrubber'
 require_relative 'aireview/context_builder'
 require_relative 'aireview/reviewer'
 require_relative 'aireview/review_pipeline'
+require_relative 'aireview/model_checker'
 require_relative 'aireview/gitlab_client'
 require_relative 'aireview/jira_client'
 require_relative 'aireview/review_marker'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aireview
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 2.0.0
 platform: ruby
 authors:
 - Denis Levenko
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-14 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dotenv
@@ -31,6 +31,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +41,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.14.4
 - !ruby/object:Gem::Dependency
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
@@ -68,10 +74,15 @@ files:
 - README.md
 - bin/aireview
 - config/.aireview.yml.example
+- config/defaults.yml
 - lib/aireview.rb
+- lib/aireview/candidate_checker.rb
 - lib/aireview/cli.rb
 - lib/aireview/config.rb
+- lib/aireview/config_fallbacks.rb
+- lib/aireview/config_layers.rb
 - lib/aireview/config_limits.rb
+- lib/aireview/config_loader.rb
 - lib/aireview/context_budget.rb
 - lib/aireview/context_builder.rb
 - lib/aireview/diff_fetcher.rb
@@ -79,17 +90,27 @@ files:
 - lib/aireview/errors.rb
 - lib/aireview/gitlab_client.rb
 - lib/aireview/jira_client.rb
+- lib/aireview/llm_client.rb
+- lib/aireview/llm_failure.rb
+- lib/aireview/llm_router.rb
+- lib/aireview/model_candidate.rb
+- lib/aireview/model_checker.rb
+- lib/aireview/model_pool.rb
+- lib/aireview/model_state.rb
 - lib/aireview/mr_parser.rb
 - lib/aireview/output_schemas.rb
 - lib/aireview/prompts/critique.txt
 - lib/aireview/prompts/generate.txt
 - lib/aireview/publisher.rb
+- lib/aireview/result_parser.rb
 - lib/aireview/review_marker.rb
 - lib/aireview/review_pipeline.rb
 - lib/aireview/review_renderer.rb
 - lib/aireview/review_schemas.rb
 - lib/aireview/reviewer.rb
 - lib/aireview/secret_scrubber.rb
+- lib/aireview/stage_chains.rb
+- lib/aireview/stages.rb
 - lib/aireview/utils.rb
 - lib/aireview/version.rb
 homepage: https://github.com/DenisDenis9331/aireview