aireview 0.3.0 → 2.0.0

data/lib/aireview/dry_run_report.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Aireview
-  # Вывод --dry-run: настройки, сводка контекста и промпты обеих стадий.
+  # The --dry-run output: settings, the context summary and the prompts of both stages.
   class DryRunReport
     def initialize(out)
       @out = out
@@ -33,15 +33,37 @@ module Aireview
 
     def render_settings(dry_run)
       @out.puts('=== LLM SETTINGS ===')
-      @out.puts("Generate: #{dry_run[:generate_model]} temperature=#{dry_run[:generate_temperature]}")
-      list('fallbacks', dry_run[:generate_fallbacks], separator: ' -> ')
+      render_config_paths(dry_run[:config_paths])
+      render_stage(dry_run, :generate)
       if dry_run[:critique_prompt]
-        @out.puts("Critique: #{dry_run[:critique_model]} temperature=#{dry_run[:critique_temperature]}")
-        list('fallbacks', dry_run[:critique_fallbacks], separator: ' -> ')
+        render_stage(dry_run, :critique)
       else
         @out.puts('Critique: disabled')
       end
+      @out.puts("Critique rule: #{dry_run[:critique_rule]}") if dry_run[:critique_rule]
       render_reserves(dry_run)
+      list('warnings', dry_run[:warnings], separator: "\n  ")
+    end
+
+    def render_config_paths(paths)
+      return if paths.nil? || paths.empty?
+
+      @out.puts("Config: #{paths.map { |name, path| "#{name} #{path}" }.join(', ')}")
+    end
+
+    # The source of every setting is the layer it came from: built-in, image
+    # defaults, .aireview.yml, env or cli.
+    def render_stage(dry_run, stage)
+      sources = dry_run.dig(:sources, stage) || {}
+      @out.puts("#{stage.capitalize}: #{dry_run[:"#{stage}_model"]} " \
+                "temperature=#{dry_run[:"#{stage}_temperature"]}#{origin(sources, :model, :provider)}")
+      fallbacks = dry_run[:"#{stage}_fallbacks"]
+      list('fallbacks', fallbacks, separator: ' -> ', suffix: origin(sources, :fallbacks))
+    end
+
+    def origin(sources, *keys)
+      parts = keys.filter_map { |key| "#{key} from #{sources[key]}" if sources[key] }
+      parts.empty? ? '' : " (#{parts.join(', ')})"
     end
 
     def render_context_sizes(sizes)
@@ -67,12 +89,15 @@ module Aireview
     def render_reserves(dry_run)
       keys = Array(dry_run[:api_keys]).map { |provider, count| "#{provider} #{count}" }
       @out.puts("API keys: #{keys.join(', ')}") unless keys.empty?
-      @out.puts("Time budget: #{dry_run[:time_budget]}s") if dry_run[:time_budget]
+      return unless dry_run[:time_budget]
+
+      quarantine = dry_run[:overloaded_quarantine]
+      @out.puts("Time budget: #{dry_run[:time_budget]}s#{", overloaded quarantine: #{quarantine}s" if quarantine}")
     end
 
-    def list(title, items, separator: ', ')
+    def list(title, items, separator: ', ', suffix: '')
       items = Array(items)
-      @out.puts("  #{title}: #{items.join(separator)}") unless items.empty?
+      @out.puts("  #{title}: #{items.join(separator)}#{suffix}") unless items.empty?
     end
   end
 end

data/lib/aireview/errors.rb

@@ -3,7 +3,15 @@ module Aireview
   class Error < StandardError; end
   class ConfigError < Error; end
   class ParseError < Error; end
+  # Repairing invalid JSON is impossible: the model that answered is out of
+  # attempts or quarantined with no budget to wait. For the pipeline it is
+  # the same as an invalid result — the stage restarts on another model.
+  class RepairImpossibleError < ParseError; end
   class ApiError < Error; end
+  # A pinned route (the JSON repair by the same model) could not answer: out
+  # of attempts, excluded, or quarantined with no budget to wait. Not fatal
+  # for the run — the stage restarts on another model.
+  class RouteExhaustedError < ApiError; end
   class ContextBudgetError < Error; end
   class HelpRequested < Error; end
 end

data/lib/aireview/gitlab_client.rb

@@ -35,8 +35,9 @@ module Aireview
       get_json('user')
     end
 
-    # Retry создаёт новый job в том же pipeline. Старые попытки видны только
-    # с include_retried; один лишь новый CI_JOB_ID бывает и после обычного push.
+    # A Retry creates a new job in the same pipeline. Earlier attempts are
+    # visible only with include_retried; a new CI_JOB_ID alone happens after an
+    # ordinary push too.
     def retried_job?(project_id, job_id)
       current = get_json("projects/#{project_id}/jobs/#{job_id}")
       validate_retry_job!(current, pipeline: true)
@@ -54,13 +55,13 @@ module Aireview
       raise ApiError, 'Too many pipeline jobs to determine whether this job is a retry'
     end
 
-    # Заметки отдаются страницами и сортируются по времени создания, а
-    # обновление комментария в этом порядке его не поднимает: на длинном MR
-    # своё ревью оказывается далеко не на первой странице. Обрывать обход молча
-    # нельзя — по неполному списку ревью решит, что заметки нет, и создаст
-    # вторую, поэтому упираемся в предел с ошибкой. Порядок задаётся явно: от
-    # него зависит, какую из старых заметок без метки подхватит ревью, и
-    # полагаться тут на дефолт API не стоит.
+    # Notes come in pages sorted by creation time, and updating a comment
+    # does not move it up in that order: on a long MR our review is far from
+    # the first page. Stopping the walk silently is not an option — with an
+    # incomplete list the review would decide the note is missing and create
+    # a second one, so the limit fails with an error. The order is explicit:
+    # it decides which old unmarked note the review picks up, and the API
+    # default is not to be relied on here.
     def fetch_merge_request_notes(project_id, iid)
       notes = []
       page = 1

data/lib/aireview/llm_client.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+require 'timeout'
+require_relative 'errors'
+require_relative 'utils'
+
+module Aireview
+  # One request to one model with one key through RubyLLM. Retries, keys and
+  # reserves belong to LlmRouter: the built-in RubyLLM/Faraday retries (3 by
+  # default) are off, otherwise every router attempt would turn into four
+  # HTTP requests and burn quota before the error reaches the classifier.
+  class LlmClient
+    # What a stage sends to the model; the same for every route of the stage.
+    Prompt = Struct.new(:stage, :system, :user, :temperature, :schema, keyword_init: true) do
+      def chars
+        system.length + user.length
+      end
+    end
+
+    def initialize(config:, logger: Logger.new($stderr))
+      @config = config
+      @logger = logger
+      @contexts = {}
+    end
+
+    # Returns the RubyLLM answer (content is text or a structure by the
+    # schema). A request error is re-raised as is — LlmFailure classifies it.
+    def request(prompt, candidate:, key:, timeout:, key_index: 0)
+      load_ruby_llm
+      stage = prompt.stage.to_s
+      model = candidate.model
+      @logger.info("LLM #{stage} request started (model=#{model}, temperature=#{prompt.temperature})")
+      chat = build_chat(context: context(stage, candidate.provider, key, key_index), stage: stage,
+                        model: model, provider: candidate.provider)
+      chat = configure_reasoning(chat: chat, model: model, provider: candidate.provider)
+        .with_temperature(prompt.temperature.to_f)
+        .with_schema(prompt.schema)
+      chat.with_instructions(prompt.system)
+      response = Timeout.timeout(timeout) { chat.ask(prompt.user) }
+      @logger.info("LLM #{stage} request completed (model=#{model})")
+      response
+    rescue Timeout::Error
+      @logger.warn("LLM #{stage} request timed out after #{timeout.round} seconds (model=#{model})")
+      raise
+    end
+
+    private
+
+    def load_ruby_llm
+      require 'ruby_llm'
+    rescue LoadError => e
+      @logger.error("LLM setup failed: #{e.message}")
+      raise ConfigError, "Missing dependency: #{e.message}"
+    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
+
+    # A RubyLLM context per stage, provider and key index: switching the key
+    # is another context, not an edit of the global config.
+    def context(stage, provider, key, key_index)
+      @contexts[[stage, provider, key_index]] ||= build_context(provider.to_s, key)
+    end
+
+    def build_context(provider, api_key)
+      RubyLLM.context do |ruby_config|
+        configure_http_proxy(ruby_config)
+        ruby_config.request_timeout = @config.llm_timeout.to_f
+        ruby_config.max_retries = 0
+        configure_provider(ruby_config, provider, api_key)
+      end
+    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
+
+    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}"
+      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)
+    end
+  end
+end

data/lib/aireview/llm_failure.rb

@@ -3,17 +3,27 @@ require 'json'
 require 'timeout'
 
 module Aireview
-  # Классификация ошибки LLM-запроса. Отвечает только на вопрос «что это»,
-  # решение «повторить, сменить ключ или модель» принимает LlmRouter.
+  # Classifies an LLM request error. Answers only "what is it"; the decision
+  # to retry, switch the key or the model belongs to LlmRouter.
   #
-  # :daily_quota — суточная квота проекта на модель, повторы бесполезны;
-  # :rate_limit  — минутный лимит, пройдёт через подсказанное время;
-  # :overloaded  — 503/«high demand» у модели;
-  # :timeout     — ответа нет дольше LLM_TIMEOUT;
-  # :fatal       — ошибка API, которую резервы не лечат;
-  # :unhandled   — не ошибка провайдера, пробрасывается как есть.
+  # :daily_quota — the project's daily quota for the model, retries are useless;
+  # :rate_limit  — a per-minute limit, passes after the hinted time;
+  # :overloaded  — 503 / "high demand" on the model;
+  # :timeout     — no answer for longer than LLM_TIMEOUT;
+  # :unavailable — the provider has no such model: retired, a typo, not pulled into Ollama;
+  # :fatal       — an API error that reserves do not cure;
+  # :unhandled   — not a provider error, re-raised as is.
   module LlmFailure
-    KINDS = %i[daily_quota rate_limit overloaded timeout fatal unhandled].freeze
+    KINDS = %i[daily_quota rate_limit overloaded timeout unavailable fatal unhandled].freeze
+    # Only by the provider's text about the model: a bare 404 is also what a
+    # wrong LLM_API_BASE or proxy answers, and the next model will not help.
+    # Ollama: `model 'x' not found` (through /v1) and `model "x" not found,
+    # try pulling it first` (older versions and /api).
+    UNAVAILABLE_MODEL_TEXT = Regexp.union(
+      /\bmodels?\/[\w.:-]+ is not found\b/i,
+      /\bis not supported for generateContent\b/i,
+      /\bmodel ['"][^'"]+['"] not found\b/i
+    )
     QUOTA_FAILURE_TYPE = 'type.googleapis.com/google.rpc.QuotaFailure'
     DAILY_QUOTA_ID = /PerDay/i
     DAILY_QUOTA_TEXT = /\bper\s+day\b|\bdaily\b/i
@@ -21,18 +31,22 @@ module Aireview
 
     module_function
 
-    # Сведения о квоте смотрим раньше класса исключения: RubyLLM превращает
-    # 429 со словом input_token в ContextLengthExceededError, хотя это
-    # исчерпанная токенная квота, а не слишком длинный запрос.
+    # Quota details are checked before the exception class: RubyLLM turns a
+    # 429 mentioning input_token into ContextLengthExceededError, although
+    # it is an exhausted token quota, not an oversized request.
     def classify(error)
       return :timeout if transport_timeout?(error)
       return :unhandled unless ruby_llm_error?(error)
 
-      quota_kind(error) || (overloaded?(error) ? :overloaded : :fatal)
+      quota_kind(error) || model_kind(error) || (overloaded?(error) ? :overloaded : :fatal)
     end
 
-    # Внешний Timeout.timeout и таймауты транспорта Faraday: последние не
-    # наследуют ни Timeout::Error, ни RubyLLM::Error.
+    def model_kind(error)
+      :unavailable if error.message.to_s.match?(UNAVAILABLE_MODEL_TEXT)
+    end
+
+    # The outer Timeout.timeout and Faraday's transport timeouts: the latter
+    # inherit neither Timeout::Error nor RubyLLM::Error.
     def transport_timeout?(error)
       return true if error.is_a?(Timeout::Error) || error.is_a?(Errno::ETIMEDOUT)
 
@@ -47,10 +61,10 @@ module Aireview
       defined?(RubyLLM::Error) && error.is_a?(RubyLLM::Error)
     end
 
-    # Google кладёт вид квоты в QuotaFailure.violations[].quotaId
-    # (GenerateRequestsPerDay… / …PerMinute…). Метрика free_tier_requests
-    # одна и та же у обоих, по ней не различить. Текст сообщения — запасной
-    # признак, когда тела ответа нет.
+    # Google puts the kind of quota into QuotaFailure.violations[].quotaId
+    # (GenerateRequestsPerDay… / …PerMinute…). The free_tier_requests metric
+    # is the same for both, it cannot tell them apart. The message text is
+    # the fallback signal when there is no response body.
     def quota_kind(error)
       ids = quota_ids(error)
       return daily_quota_id?(ids) ? :daily_quota : :rate_limit unless ids.empty?
@@ -86,5 +100,8 @@ module Aireview
       match = message.to_s.match(RETRY_AFTER)
       match[1].to_f if match
     end
+
+    private_class_method :model_kind, :transport_timeout?, :overloaded?, :ruby_llm_error?, :quota_kind,
+                         :daily_quota_id?, :quota_ids, :response_body
   end
 end