aireview 0.3.0 → 2.0.0

data/lib/aireview/review_pipeline.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 require 'json'
 require_relative 'errors'
+require_relative 'stages'
 require_relative 'context_builder'
 require_relative 'candidate_checker'
-require_relative 'result_validation'
+require_relative 'result_parser'
 require_relative 'review_renderer'
 require_relative 'review_schemas'
 require_relative 'reviewer'
 
 module Aireview
+  # A review run: context → Generate → anchoring check against the diff →
+  # Critique → report. Invalid JSON is repaired once by the same model; when
+  # the repair is invalid too, the stage restarts on another model with the
+  # original request.
   class ReviewPipeline
-    include ResultValidation
-
-    SchemaError = ResultValidation::SchemaError
+    SchemaError = ResultParser::SchemaError
 
     REPAIR_SYSTEM_PROMPT = <<~PROMPT.strip.freeze
       You fix invalid JSON produced by another LLM call.
@@ -26,6 +29,7 @@ module Aireview
 
     def initialize(config:, reviewer: nil, context_builder: nil, logger: Logger.new($stderr))
       @config = config
+      @parser = ResultParser.new
       @reviewer = reviewer || Reviewer.new(config: config, logger: logger)
       @context_builder = context_builder || ContextBuilder.new(config: config, logger: logger)
       @logger = logger
@@ -40,16 +44,18 @@ module Aireview
       )
       generate_prompt = @context_builder.build_generate_prompt(context)
       @logger.info("Pipeline generate pass started (model=#{@config.generate_model})")
-      candidates_raw = @reviewer.generate(**generate_prompt)
-      generate_result = parse_with_repair(
-        raw: candidates_raw,
-        kind: 'generate result',
-        expected: :generate,
-        repair_stage: :generate
-      )
+      generate_result = run_stage('generate') do
+        parse_with_repair(
+          raw: @reviewer.generate(**generate_prompt),
+          kind: 'generate result',
+          expected: 'generate',
+          repair_stage: 'generate'
+        )
+      end
       summary = generate_result['summary']
       candidates = Array(generate_result['candidates'])
-      @logger.info("Pipeline generate pass completed with #{candidates.size} candidate(s)")
+      @logger.info("Pipeline generate pass completed with #{candidates.size} candidate(s) " \
+                   "(model=#{@reviewer.answered_model('generate')})")
       candidates = check_candidates(context: context, changes: changes, candidates: candidates)
 
       accepted = critique ? maybe_critique(context: context, candidates: candidates) : skip_critique(candidates)
@@ -60,7 +66,8 @@ module Aireview
         accepted,
         summary: summary,
         coverage: context.coverage,
-        fallback_models: @reviewer.fallback_models
+        fallback_models: @reviewer.fallback_models,
+        critique_weaker: critique && @reviewer.critique_weaker?
       )
     end
 
@@ -85,10 +92,15 @@ module Aireview
         generate_temperature: @config.generate_temperature,
         critique_model: @config.critique_model,
         critique_temperature: @config.critique_temperature,
-        generate_fallbacks: @config.fallback_names(:generate),
-        critique_fallbacks: critique ? @config.fallback_names(:critique) : [],
-        api_keys: @config.api_key_counts(critique ? %i[generate critique] : [:generate]),
+        generate_fallbacks: @config.fallback_names('generate'),
+        critique_fallbacks: critique ? @config.fallback_names('critique') : [],
+        sources: setting_sources(critique),
+        config_paths: @config.layer_paths,
+        warnings: @config.warnings,
+        critique_rule: critique ? @config.routing.rule : nil,
+        api_keys: @config.api_key_counts(critique ? STAGES : ['generate']),
         time_budget: @config.llm_time_budget,
+        overloaded_quarantine: @config.overloaded_quarantine,
         coverage: context.coverage,
         sizes: context.sizes
       }
@@ -96,8 +108,37 @@ module Aireview
 
     private
 
-    # Привязка к коду проверяется по диффу, который видела модель, до критика:
-    # ему уходят пометки, в отчёт — сброшенная строка и знак ненайденной цитаты.
+    # Where the model, provider and reserves of a stage came from, for --dry-run.
+    def setting_sources(critique)
+      (critique ? %w[generate critique] : %w[generate]).to_h do |stage|
+        [stage.to_sym, {
+          model: @config.stage_model_source(stage),
+          provider: @config.stage_provider_source(stage),
+          fallbacks: @config.stage_fallbacks_source(stage)
+        }]
+      end
+    end
+
+    # A stage is a request, parsing and one repair by the same model. An
+    # invalid result after the repair, like a repair with no requests left,
+    # excludes the model for the stage, and the stage starts over on the next
+    # one — with the original request. API errors pass through: the router
+    # handles them with reserves, and exhausted routes are exhausted for a
+    # restart too.
+    def run_stage(stage)
+      loop do
+        return yield
+      rescue ParseError => e
+        reason = "#{e.is_a?(RepairImpossibleError) ? 'repair impossible' : 'invalid result'}: #{e.message}"
+        excluded = @reviewer.exclude_answered_model(stage: stage, reason: reason)
+        raise unless excluded
+
+        @logger.warn("Pipeline #{stage}: restarting on the next model after #{excluded} (#{e.message})")
+      end
+    end
+
+    # Anchoring is checked against the diff the model saw, before Critique:
+    # it gets the notes, the report gets the reset line and the missing-quote mark.
     def check_candidates(context:, changes:, candidates:)
       CandidateChecker.new(
         changes: changes,
@@ -112,8 +153,8 @@ module Aireview
       candidates
     end
 
-    # Критику нечего фильтровать без кандидатов: запрос к LLM был бы пустой
-    # тратой квоты и времени.
+    # Critique has nothing to filter without candidates: the LLM request
+    # would waste quota and time.
     def maybe_critique(context:, candidates:)
       return skip_critique(candidates, 'no candidates') if candidates.empty?
 
@@ -125,16 +166,18 @@ module Aireview
       candidates_json = JSON.pretty_generate(candidates)
       candidates_by_id = index_candidates_by_id(candidates)
       critique_prompt = @context_builder.build_critique_prompt(context, candidates_json: candidates_json)
-      critique_raw = @reviewer.critique(**critique_prompt)
-      critique_result = parse_with_repair(
-        raw: critique_raw,
-        kind: 'critique result',
-        expected: :critique,
-        repair_stage: :critique,
-        critique_candidate_ids: candidates_by_id.keys
-      )
+      critique_result = run_stage('critique') do
+        parse_with_repair(
+          raw: @reviewer.critique(**critique_prompt),
+          kind: 'critique result',
+          expected: 'critique',
+          repair_stage: 'critique',
+          critique_candidate_ids: candidates_by_id.keys
+        )
+      end
       verdicts = Array(critique_result['verdicts'])
-      @logger.info("Pipeline critique pass completed with #{verdicts.size} verdict(s)")
+      @logger.info("Pipeline critique pass completed with #{verdicts.size} verdict(s) " \
+                   "(model=#{@reviewer.answered_model('critique')})")
       apply_critique_verdicts(
         verdicts: verdicts,
         candidates_by_id: candidates_by_id
@@ -187,61 +230,11 @@ module Aireview
     end
 
     def parse_expected_result(raw, expected, critique_candidate_ids: nil)
-      parsed = raw.is_a?(Hash) ? raw : JSON.parse(strip_code_fences(raw.to_s))
-
-      case expected
-      when :generate
-        parsed = normalize_generate_result(parsed)
-      when :critique
-        parsed = normalize_critique_result(parsed, critique_candidate_ids: critique_candidate_ids)
-      else
-        raise ArgumentError, "Unknown expected JSON schema: #{expected.inspect}"
-      end
-
-      parsed
-    end
-
-    def strip_code_fences(text)
-      stripped = text.to_s.strip
-      return stripped unless stripped.start_with?('```')
-
-      stripped
-        .sub(/\A```[[:alnum:]_-]*[ \t]*\r?\n?/, '')
-        .sub(/\r?\n?```[ \t]*\z/, '')
-        .strip
-    end
-
-    def normalize_generate_result(parsed)
-      parsed = {'summary' => nil, 'candidates' => parsed} if parsed.is_a?(Array)
-      validate_generate_result_shape!(parsed)
-      parsed['summary'] = nil unless parsed.key?('summary')
-      candidate_ids = parsed['candidates'].map { |candidate| normalize_id(value(candidate, 'id')) }
-      validate_identifiers!(
-        candidate_ids,
-        missing_message: 'each generate candidate must include a non-empty id',
-        duplicate_prefix: 'duplicate generate candidate ids'
-      )
-
-      parsed
-    end
-
-    def normalize_critique_result(parsed, critique_candidate_ids:)
-      validate_critique_result_shape!(parsed)
-      verdicts = parsed['verdicts']
-      verdict_ids = verdicts.map { |verdict| normalize_id(value(verdict, 'id')) }
-      validate_identifiers!(
-        verdict_ids,
-        missing_message: 'each verdict must include a non-empty id',
-        duplicate_prefix: 'duplicate verdict ids'
-      )
-      validate_expected_verdict_ids!(verdict_ids, critique_candidate_ids)
-      verdicts.each { |verdict| validate_verdict!(verdict) }
-
-      parsed
+      @parser.parse(raw, expected: expected, critique_candidate_ids: critique_candidate_ids)
     end
 
     def repair_json(raw:, kind:, expected:, stage:, critique_candidate_ids: nil)
-      schema = expected == :critique ? ReviewSchemas.critique : ReviewSchemas.generate
+      schema = expected == 'critique' ? ReviewSchemas.critique : ReviewSchemas.generate
       user_prompt = <<~PROMPT
         The previous #{kind} response was invalid.
 
@@ -254,19 +247,28 @@ module Aireview
         Invalid response:
         #{raw}
       PROMPT
-      if stage == :critique && critique_candidate_ids
+      if stage == 'critique' && critique_candidate_ids
         user_prompt << "\nExpected candidate ids: #{critique_candidate_ids.join(', ')}\n"
       end
 
       @logger.info("Pipeline #{stage} repair started for #{kind}")
-      prompt = @context_builder.check_stage_size!(stage, REPAIR_SYSTEM_PROMPT, user_prompt)
-      if stage == :critique
-        @reviewer.critique(**prompt)
+      prompt = repair_prompt(stage, user_prompt)
+      if stage == 'critique'
+        @reviewer.critique(**prompt, pinned: true)
       else
-        @reviewer.generate(**prompt)
+        @reviewer.generate(**prompt, pinned: true)
       end
     end
 
+    # A repair that does not fit the stage limit is an invalid result of this
+    # model, not a size error of the original request: the stage moves to
+    # the next model with the original prompt.
+    def repair_prompt(stage, user_prompt)
+      @context_builder.check_stage_size!(stage, REPAIR_SYSTEM_PROMPT, user_prompt)
+    rescue ContextBudgetError => e
+      raise ParseError, "repair request does not fit the stage limit: #{e.message}"
+    end
+
     def index_candidates_by_id(candidates)
       candidates.each_with_object({}) do |candidate, result|
         next unless candidate.is_a?(Hash)

data/lib/aireview/review_renderer.rb

@@ -46,6 +46,7 @@ module Aireview
         diff_unavailable: 'diff not available',
         section_list: 'Truncated sections',
         fallback_used: 'Fallback model used',
+        critique_weaker: 'Critique ran on a model weaker than Generate: the findings were checked less strictly.',
         quote_missing: 'quote not found in the diff'
       },
       'ru' => {
@@ -72,6 +73,7 @@ module Aireview
         diff_unavailable: 'дифф недоступен',
         section_list: 'Усечённые секции',
         fallback_used: 'Использована резервная модель',
+        critique_weaker: 'Критика выполнена моделью слабее generate: замечания проверены менее строго.',
         quote_missing: 'цитата не найдена в диффе'
       }
     }.freeze
@@ -80,11 +82,11 @@ module Aireview
       @labels = LABELS.fetch(language.to_s) { LABELS.fetch(DEFAULT_LANGUAGE) }
     end
 
-    # coverage: факты усечения контекста от пайплайна, не текст модели.
-    # result по-прежнему про найденные проблемы; неполнота покрытия
-    # дописывается рядом с ним, чтобы строка результата не читалась как
-    # «проверено всё».
-    def render(accepted, summary:, coverage: nil, fallback_models: {})
+    # coverage: the truncation facts from the pipeline, not the model's text.
+    # result is still about the findings; incomplete coverage is written
+    # next to it so that the result line does not read as "everything was
+    # checked".
+    def render(accepted, summary:, coverage: nil, fallback_models: {}, critique_weaker: false)
       mismatches, important = select_findings(Array(accepted))
       result = mismatches.empty? && important.empty? ? 'ok' : 'needs attention'
 
@@ -104,16 +106,16 @@ module Aireview
         ## #{label(:result)}
 
         #{result}#{partial_note(coverage)}
-        #{coverage_block(coverage)}#{fallback_note(fallback_models)}
+        #{coverage_block(coverage)}#{fallback_note(fallback_models)}#{weaker_note(critique_weaker)}
         #{label(:disclaimer)}
       MARKDOWN
     end
 
     private
 
-    # Сначала отбор того, что вообще показывается, потом лимиты разделов и
-    # только затем общий лимит: находка, которую не показать из-за категории
-    # или лимита раздела, не должна занимать общий слот.
+    # First select what is shown at all, then the section limits and only
+    # then the total limit: a finding that cannot be shown because of its
+    # category or a section limit must not take a slot in the total.
     def select_findings(accepted)
       sorted = sorted_findings(accepted)
       mismatches = sorted.select { |finding| category(finding) == 'task_mismatch' }.first(MISMATCH_LIMIT)
@@ -181,8 +183,14 @@ module Aireview
       "\n## #{label(:not_reviewed)}\n\n#{lines.join("\n")}\n"
     end
 
-    # Смена ключа остаётся в логах; смена модели видна читателю, потому что
-    # запасная модель может ревьюить слабее основной.
+    # A key switch stays in the logs; a model switch is visible to the
+    # reader, because a fallback model may review less well than the primary.
+    def weaker_note(critique_weaker)
+      return '' unless critique_weaker
+
+      "\n#{label(:critique_weaker)}\n"
+    end
+
     def fallback_note(fallback_models)
       return '' if fallback_models.nil? || fallback_models.empty?
 

data/lib/aireview/reviewer.rb

@@ -1,142 +1,70 @@
 # frozen_string_literal: true
 require_relative 'errors'
 require_relative 'output_schemas'
-require_relative 'utils'
 require_relative 'llm_router'
-require 'timeout'
+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
     attr_reader :router
 
-    def initialize(config:, logger: Logger.new($stderr), router: nil)
+    def initialize(config:, logger: Logger.new($stderr), router: nil, client: nil)
       @config = config
       @logger = logger
       @router = router || LlmRouter.new(config: config, logger: logger)
-      @llm_contexts = {}
+      @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: {temperature: @config.generate_temperature, 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: {temperature: @config.critique_temperature, 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
 
-    # Стадии, ответившие запасной моделью, для строки в отчёте.
+    # Stages answered by a fallback model, for the report line.
     def fallback_models
       @router.fallback_models
     end
 
-    private
-
-    def call_llm(stage:, system:, user:, options:)
-      require 'ruby_llm'
-
-      @config.require_llm_configuration!
-      response = @router.call(stage: stage, request_chars: system.length + user.length) do |route, timeout|
-        perform_llm_request(
-          context: llm_context(stage, route),
-          stage: stage,
-          system: system,
-          user: user,
-          options: options.merge(model: route.candidate.model, provider: route.candidate.provider, timeout: timeout)
-        )
-      end
-      response.content
-    rescue LoadError => e
-      @logger.error("LLM #{stage} setup failed: #{e.message}")
-      raise ConfigError, "Missing dependency: #{e.message}"
-    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(options[:timeout]) { chat.ask(user) }
-      @logger.info("LLM #{stage} request completed (model=#{model})")
-      response
-    rescue Timeout::Error
-      @logger.warn("LLM #{stage} request timed out after #{options[:timeout].round} seconds (model=#{model})")
-      raise
-    end
-
-    def configure_reasoning(chat:, model:, provider:)
-      return chat unless provider == 'ollama' && model.start_with?('gpt-oss:')
-
-      chat.with_thinking(effort: :low)
+    # 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 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)
+    # Critique ran on a model below Generate in the pool (allow_weaker).
+    def critique_weaker?
+      @router.critique_weaker?
     end
 
-    # Контекст RubyLLM на стадию, провайдера и номер ключа: смена ключа —
-    # это другой контекст, а не правка глобального конфига.
-    def llm_context(stage, route)
-      cache_key = [stage, route.candidate.provider, route.key_index]
-      @llm_contexts[cache_key] ||= build_llm_context(route.candidate.provider.to_s, route.key)
+    # 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
 
-    # Повторами занимается роутер: встроенные ретраи RubyLLM/Faraday (по
-    # умолчанию 3) превратили бы каждую нашу попытку в четыре HTTP-запроса и
-    # жгли бы квоту до того, как ошибка дойдёт до классификатора.
-    def build_llm_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
+    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