aireview 0.2.1 → 2.0.0

data/lib/aireview/context_builder.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require_relative 'utils'
 require_relative 'errors'
+require_relative 'stages'
 require_relative 'secret_scrubber'
 require_relative 'diff_fetcher'
 require_relative 'context_budget'
@@ -15,15 +16,14 @@ module Aireview
     }.freeze
     CHANGES_HEADER = "Changes:\n"
     CANDIDATES_HEADER = "\n\nCandidates JSON from Generate:\n"
-    # Резерв под кандидатов в промпте критика: три кандидата по ~1 500
-    # символов. Оценка, не гарантия; фактический размер проверяется перед
-    # отправкой.
+    # Room for the candidates in the Critique prompt: three candidates of
+    # ~1,500 characters. An estimate, not a guarantee; the actual size is
+    # checked before sending.
     CANDIDATES_RESERVE_CHARS = 4_500
-    STAGES = %i[generate critique].freeze
 
-    # Контекст одного прогона: обе стадии получают одинаковые MR, Jira и дифф,
-    # усечённые один раз под самую тесную из стадий.
-    Context = Struct.new(:user_prompt, :coverage, :sizes, keyword_init: true)
+    # The context of one run: both stages get the same MR, Jira and diff,
+    # truncated once for the tightest of the stages.
+    Context = Struct.new(:user_prompt, :diff_text, :coverage, :sizes, keyword_init: true)
 
     def initialize(config:, logger: Logger.new($stderr))
       @config = config
@@ -49,20 +49,20 @@ module Aireview
 
       sizes = context_sizes(fixed: fixed, packed: packed, budget: budget, diff_budget: diff_budget, critique: critique)
       log_sizes(sizes)
-      Context.new(user_prompt: fixed + packed.text, coverage: coverage, sizes: sizes)
+      Context.new(user_prompt: fixed + packed.text, diff_text: packed.text, coverage: coverage, sizes: sizes)
     end
 
     def build_generate_prompt(context)
-      check_stage_size!(:generate, system_prompt(:generate), context.user_prompt)
+      check_stage_size!('generate', system_prompt('generate'), context.user_prompt)
     end
 
     def build_critique_prompt(context, candidates_json:)
       user = "#{context.user_prompt}#{CANDIDATES_HEADER}#{scrub_text(candidates_json)}"
-      check_stage_size!(:critique, system_prompt(:critique), user)
+      check_stage_size!('critique', system_prompt('critique'), user)
     end
 
     def system_prompt(stage)
-      template = stage.to_sym == :critique ? CRITIQUE_PROMPT_TEMPLATE : GENERATE_PROMPT_TEMPLATE
+      template = stage.to_s == 'critique' ? CRITIQUE_PROMPT_TEMPLATE : GENERATE_PROMPT_TEMPLATE
       extras = []
       if Aireview::Utils.present?(@config.review_instructions)
         extras << "Additional project instructions:\n#{scrub_text(@config.review_instructions.strip)}"
@@ -72,10 +72,11 @@ module Aireview
       [template, *extras].join("\n\n")
     end
 
-    # Проверка перед отправкой: если кандидаты вышли за резерв и запрос не
-    # помещается, это ошибка, а не повод молча резать контекст, который
-    # генератор уже видел.
+    # A check before sending: when the candidates exceed the reserve and the
+    # request does not fit, that is an error, not a reason to silently cut
+    # the context Generate has already seen.
     def check_stage_size!(stage, system, user)
+      stage = stage.to_s
       limit = @config.max_prompt_chars(stage)
       total = system.length + user.length
       if total > limit
@@ -89,10 +90,10 @@ module Aireview
 
     private
 
-    # Минимум по стадиям: контекст один на прогон, поэтому он должен
-    # помещаться в каждую из них вместе с её системным промптом и резервом.
+    # The minimum over the stages: the context is one per run, so it must fit
+    # into each of them together with its system prompt and reserve.
     def context_budget(critique:)
-      stages = critique ? STAGES : [:generate]
+      stages = critique ? STAGES : ['generate']
       budgets = stages.to_h { |stage| [stage, stage_budget(stage)] }
       stage, budget = budgets.min_by { |_, value| value }
       return budget if budget.positive?
@@ -104,7 +105,7 @@ module Aireview
     end
 
     def stage_budget(stage)
-      reserve = stage == :critique ? CANDIDATES_RESERVE_CHARS + CANDIDATES_HEADER.length : 0
+      reserve = stage == 'critique' ? CANDIDATES_RESERVE_CHARS + CANDIDATES_HEADER.length : 0
       @config.max_prompt_chars(stage) - system_prompt(stage).length - reserve
     end
 
@@ -152,7 +153,7 @@ module Aireview
     end
 
     def context_sizes(fixed:, packed:, budget:, diff_budget:, critique:)
-      stages = critique ? STAGES : [:generate]
+      stages = critique ? STAGES : ['generate']
       {
         context_budget: budget,
         diff_budget: diff_budget,

data/lib/aireview/diff_fetcher.rb

@@ -7,13 +7,14 @@ module Aireview
     DIFF_UNAVAILABLE = '[diff not available]'
     BINARY_DIFF = /\ABinary files .* differ/
 
-    # Один файл из ответа GitLab: заголовок, хунки и что с ним можно делать.
+    # One file from the GitLab answer: the header, the hunks and what can be done with it.
     # kind:
-    #   :text            есть хунки, код можно проверить;
-    #   :no_text_changes переименование, смена режима, пустой файл: проверять
-    #                    нечего;
-    #   :unavailable     GitLab не отдал дифф (too_large, бинарник, пустой
-    #                    дифф без причины): код есть, но проверить его не удалось.
+    #   :text            there are hunks, the code can be checked;
+    #   :no_text_changes a rename, a mode change, an empty file: nothing to
+    #                    check;
+    #   :unavailable     GitLab did not return the diff (too_large, a binary,
+    #                    an empty diff without a reason): the code exists,
+    #                    but could not be checked.
     class Entry
       attr_reader :path, :kind, :header, :hunks
 
@@ -49,9 +50,9 @@ module Aireview
 
       private
 
-      # Пустой дифф без объяснимой причины (переименование, смена режима,
-      # пустой новый или удалённый файл) считаем недоступным: код есть, но
-      # GitLab его не отдал.
+      # An empty diff without an explainable reason (a rename, a mode change,
+      # an empty new or deleted file) counts as unavailable: the code exists,
+      # but GitLab did not return it.
       def classify(change, diff)
         return :unavailable if change['too_large']
         return :unavailable if diff.match?(BINARY_DIFF)
@@ -67,8 +68,8 @@ module Aireview
         modes.none?(&:nil?) && modes.uniq.size == 2
       end
 
-      # Хунки режем по заголовкам @@; текст до первого @@ (или дифф без них,
-      # например заглушка про секретный файл) считается одним хунком.
+      # Hunks are split at the @@ headers; the text before the first @@ (or a
+      # diff without any, such as the secret-file placeholder) counts as one hunk.
       def split_hunks(diff)
         diff = "#{diff}\n" unless diff.end_with?("\n")
         pieces = diff.split(/^(?=@@ )/)

data/lib/aireview/dry_run_report.rb

@@ -1,20 +1,14 @@
 # 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
     end
 
     def render(dry_run)
-      @out.puts('=== LLM SETTINGS ===')
-      @out.puts("Generate: #{dry_run[:generate_model]} temperature=#{dry_run[:generate_temperature]}")
-      if dry_run[:critique_prompt]
-        @out.puts("Critique: #{dry_run[:critique_model]} temperature=#{dry_run[:critique_temperature]}")
-      else
-        @out.puts('Critique: disabled')
-      end
+      render_settings(dry_run)
       @out.puts
       @out.puts('=== CONTEXT ===')
       render_context_sizes(dry_run[:sizes])
@@ -37,6 +31,41 @@ module Aireview
 
     private
 
+    def render_settings(dry_run)
+      @out.puts('=== LLM SETTINGS ===')
+      render_config_paths(dry_run[:config_paths])
+      render_stage(dry_run, :generate)
+      if dry_run[:critique_prompt]
+        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)
       @out.puts("Sections: #{sizes[:sections]} chars, diff: #{sizes[:diff]} chars " \
                 "(budget #{sizes[:diff_budget]}, hunks #{sizes[:hunks_shown]}/#{sizes[:hunks_total]})")
@@ -57,8 +86,18 @@ module Aireview
       list('diff not available', coverage.files_unavailable)
     end
 
-    def list(title, items)
-      @out.puts("  #{title}: #{items.join(', ')}") unless items.empty?
+    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?
+      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: ', ', suffix: '')
+      items = Array(items)
+      @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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+require 'json'
+require 'timeout'
+
+module Aireview
+  # 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 — 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 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
+    RETRY_AFTER = /retry\s+(?:in|after)\s+(\d+(?:\.\d+)?)\s*(?:s|sec|secs|second|seconds)\b/i
+
+    module_function
+
+    # 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) || model_kind(error) || (overloaded?(error) ? :overloaded : :fatal)
+    end
+
+    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)
+
+      defined?(Faraday::TimeoutError) && error.is_a?(Faraday::TimeoutError)
+    end
+
+    def overloaded?(error)
+      error.is_a?(RubyLLM::ServiceUnavailableError) || error.is_a?(RubyLLM::OverloadedError)
+    end
+
+    def ruby_llm_error?(error)
+      defined?(RubyLLM::Error) && error.is_a?(RubyLLM::Error)
+    end
+
+    # 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?
+      return unless error.is_a?(RubyLLM::RateLimitError)
+
+      error.message.to_s.match?(DAILY_QUOTA_TEXT) ? :daily_quota : :rate_limit
+    end
+
+    def daily_quota_id?(ids)
+      ids.any? { |id| id.match?(DAILY_QUOTA_ID) }
+    end
+
+    def quota_ids(error)
+      body = response_body(error)
+      details = body.is_a?(Hash) ? Array(body.dig('error', 'details')) : []
+      details.flat_map do |detail|
+        next [] unless detail.is_a?(Hash) && detail['@type'] == QUOTA_FAILURE_TYPE
+
+        Array(detail['violations']).filter_map { |violation| violation['quotaId'] if violation.is_a?(Hash) }
+      end
+    end
+
+    def response_body(error)
+      body = error.respond_to?(:response) && error.response.respond_to?(:body) ? error.response.body : nil
+      return body unless body.is_a?(String)
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      nil
+    end
+
+    def retry_after_seconds(message)
+      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