aireview 0.3.0 → 2.1.0

data/lib/aireview/context_budget.rb

@@ -2,12 +2,13 @@
 require_relative 'errors'
 
 module Aireview
-  # Укладывает контекст ревью в бюджет символов и запоминает, что при этом не
-  # вошло. Секции MR и Jira режутся до своих лимитов с сохранением начала,
-  # дифф по целым файлам, затем по целым хункам; внутри хунка не режем.
+  # Fits the review context into a character budget and remembers what was
+  # left out. The MR and Jira sections are cut to their limits keeping the
+  # beginning, the diff by whole files, then by whole hunks; a hunk is never
+  # cut inside.
   module ContextBudget
-    # Пути, которые не вошли, перечисляются в конце диффа; список ограничен,
-    # чтобы сам не съел бюджет.
+    # The paths that did not fit are listed at the end of the diff; the list
+    # is capped so that it does not eat the budget itself.
     NOT_SHOWN_LIST_LIMIT = 20
     TRAILER_RESERVE_CHARS = 400
 
@@ -26,7 +27,8 @@ module Aireview
 
     Packed = Struct.new(:text, :shown_hunks, :total_hunks, keyword_init: true)
 
-    # Начало важнее конца: требования и критерии приёмки обычно там.
+    # The beginning matters more than the end: requirements and acceptance
+    # criteria usually live there.
     def self.truncate_section(text, limit:, label:, coverage:)
       text = text.to_s
       return text if text.length <= limit
@@ -39,11 +41,11 @@ module Aireview
       Packer.new(entries, budget: budget, coverage: coverage).pack
     end
 
-    # Файлы без хунков идут первыми: они дёшевы и всегда полезны для картины
-    # MR. Текстовые файлы идут в порядке GitLab, пока влезают; первый файл,
-    # который не влезает, показывается частично, всё после него не показывается.
-    # Хунк, который не влез бы даже в пустой бюджет, пропускается с пометкой,
-    # а не останавливает раскладку.
+    # Files without hunks go first: they are cheap and always useful for the
+    # picture of the MR. Text files go in GitLab order while they fit; the
+    # first file that does not fit is shown partially, everything after it is
+    # not shown. A hunk that would not fit even into an empty budget is
+    # skipped with a mark instead of stopping the layout.
     class Packer
       def initialize(entries, budget:, coverage:)
         @non_text, @text = entries.partition { |entry| !entry.text? }
@@ -62,9 +64,9 @@ module Aireview
 
       private
 
-      # Что-то придётся опустить, значит нужен хвост со списком пропущенного.
-      # @used считает весь собранный текст, включая разделители между
-      # файлами: результат не должен выйти за бюджет ни на символ.
+      # Something has to be left out, so a trailer listing the skipped paths
+      # is needed. @used counts the whole assembled text, separators between
+      # files included: the result must not exceed the budget by a character.
       def pack_within_limit
         @parts = @non_text.map(&:render)
         @used = joined_length(@parts)
@@ -95,12 +97,12 @@ module Aireview
         shown_hunks
       end
 
-      # Место под следующий кусок с учётом разделителя перед ним.
+      # Room for the next piece, the separator before it included.
       def remaining
         @limit - @used - (@parts.empty? ? 0 : 1)
       end
 
-      # Возвращает [текст, число показанных хунков, остановлена ли раскладка].
+      # Returns [text, number of shown hunks, whether the layout stopped].
       def pack_entry(entry)
         full = entry.render
         return [full, entry.hunks.size, false] if full.length <= remaining
@@ -113,10 +115,10 @@ module Aireview
         [entry.header + body + partial_marker(entry, shown), shown, stopped]
       end
 
-      # Место сначала отдаётся хункам, которые можно показать, и только на
-      # остаток добавляются пометки о слишком больших: иначе пометки могли бы
-      # вытеснить единственный подходящий хунк. Факт пропуска в покрытие
-      # попадает независимо от того, есть ли для пометки место.
+      # Room goes first to the hunks that can be shown, and only the remainder
+      # to the marks about oversized ones: otherwise the marks could push out
+      # the only fitting hunk. The skip is recorded in the coverage whether
+      # or not there is room for the mark.
       def pack_hunks(entry)
         base = entry.header.length + partial_marker(entry, 0).length
         shown = []

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,14 +16,13 @@ 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 и дифф,
-    # усечённые один раз под самую тесную из стадий.
+    # 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))
@@ -53,16 +53,16 @@ module Aireview
     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,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,146 @@
+# frozen_string_literal: true
+require 'json'
+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; read it with LlmClient.content. 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}#{token_counts(response)})")
+      response
+    rescue Timeout::Error
+      @logger.warn("LLM #{stage} request timed out after #{timeout.round} seconds (model=#{model})")
+      raise
+    end
+
+    # The answer as RubyLLM 1.x gave it under a schema: the parsed JSON when
+    # the text is JSON, the text itself otherwise (the pipeline repairs it).
+    # RubyLLM 2 always returns the text, and a Hash that breaks the schema
+    # would go to a repair request instead of the next model. An empty
+    # answer stays an empty String (Message#parsed would turn it into nil);
+    # JSON null becomes nil, as in 1.x.
+    def self.content(response)
+      content = response.content
+      return content unless content.is_a?(String) && !content.empty?
+
+      response.parsed
+    rescue JSON::ParserError
+      content
+    end
+
+    private
+
+    # Token counts as the provider reported them, one line per attempt. They
+    # are not summed: Gemini already counts thinking into output. Input is
+    # what was not read from or written to a cache; the prompt size is
+    # input + cache_read + cache_write, and a retry of the same prompt on
+    # Gemini is often served from its implicit cache.
+    def token_counts(response)
+      tokens = response.tokens
+      cached = {cache_read: tokens.cache_read, cache_write: tokens.cache_write}.reject { |_, count| count.to_i.zero? }
+      counts = {input: tokens.input, output: tokens.output, thinking: tokens.thinking}.compact.merge(cached)
+      return '' if counts.empty?
+
+      ", tokens: #{counts.map { |name, count| "#{name}=#{count}" }.join(' ')}"
+    end
+
+    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
+
+    # RubyLLM 2 sends OpenAI requests to the Responses API; a compatible
+    # server behind LLM_API_BASE usually has Chat Completions only.
+    def configure_remote_provider(ruby_config, provider, api_key)
+      ruby_config.public_send("#{provider}_api_key=", api_key)
+      ruby_config.openai_protocol = :chat_completions if provider == 'openai'
+      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