robot_lab 0.2.7 → 0.3.0

data/lib/robot_lab/robot.rb

@@ -7,6 +7,7 @@ require_relative 'robot/history_search'
 require_relative 'robot/agent_skill_matching'
 require_relative 'robot/budget'
 require_relative 'robot/hooking'
+require_relative 'robot/result_building'
 
 module RobotLab
   # LLM-powered robot built on RubyLLM::Agent
@@ -41,6 +42,12 @@ module RobotLab
   #     local_tools: [OrderLookup, RefundProcessor]
   #   )
   #
+  # :reek:TooManyMethods :reek:TooManyInstanceVariables -- Robot is intentionally the central orchestrator
+  #   (see CLAUDE.md); behavior is split into the included modules below.
+  # :reek:InstanceVariableAssumption -- every ivar is assigned in #initialize via assign_identity_ivars/
+  #   extract_config_ivars/initialize_runtime_state/initialize_memory; reek does not trace those helpers.
+  # :reek:RepeatedConditional -- `@bus` presence gates optional bus wiring at each independent site.
+  # :reek:DataClump -- (context, system_prompt, template) travel together as the robot's identity triple across construction APIs.
   class Robot < RubyLLM::Agent
     include Robot::TemplateRendering
     include Robot::MCPManagement
@@ -48,6 +55,7 @@ module RobotLab
     include Robot::HistorySearch
     include Robot::Budget
     include Robot::Hooking
+    include Robot::ResultBuilding
     include Runnable
     prepend Robot::AgentSkillMatching
 
@@ -155,6 +163,8 @@ module RobotLab
     # @param stop [String, Array, nil] stop sequences
     # @param skills [Symbol, Array<Symbol>, nil] skill templates to prepend
     # @param config [RunConfig, nil] shared configuration (merged with explicit kwargs)
+    # :reek:LongParameterList -- the documented public constructor: one keyword per robot capability.
+    # :reek:BooleanParameter -- enable_cache and mcp_discovery are documented feature toggles.
     def initialize(
       name:,
       template: nil,
@@ -230,6 +240,7 @@ module RobotLab
     # Returns the model identifier
     #
     # @return [String, nil] the LLM model ID string
+    # :reek:FeatureEnvy -- duck-type unwrapping of the chat's model object into an id string.
     def model
       return nil unless @chat.respond_to?(:model)
 
@@ -245,6 +256,8 @@ module RobotLab
     # @param model [String, nil] new model
     # @param temperature [Float, nil] new temperature
     # @return [self]
+    # :reek:LongParameterList :reek:TooManyStatements -- public reconfiguration API; one guarded with_* application per option.
+    # :reek:ControlParameter -- `context || @build_context` is a fallback default, not behavior selection.
     def update(template: nil, context: nil, system_prompt: nil, model: nil, temperature: nil, **kwargs)
       if template
         @template = template
@@ -268,6 +281,8 @@ module RobotLab
     #
     # @param result [SimpleFlow::Result] incoming result from previous step
     # @return [SimpleFlow::Result] result with robot output
+    # :reek:TooManyStatements -- SimpleFlow step: timing, run, and error-shielding belong together.
+    # :reek:DuplicateMethodCall -- each clock_gettime samples a different instant (start/stop/rescue); a local would be wrong.
     def call(result)
       run_context = extract_run_context(result)
 
@@ -354,9 +369,7 @@ module RobotLab
     # access to conversation state.
     #
     # @return [RubyLLM::Chat]
-    def chat
-      @chat
-    end
+    attr_reader :chat
 
     # Return the conversation messages from the underlying chat.
     #
@@ -369,13 +382,14 @@ module RobotLab
     #
     # @param keep_system [Boolean] whether to preserve the system message
     # @return [self]
+    # :reek:BooleanParameter :reek:ControlParameter -- keep_system is a documented public API toggle.
     def clear_messages(keep_system: true)
       if keep_system
         system_msg = @chat.messages.find { |m| m.role == :system }
-        @chat.reset_messages!
+        @chat.messages = []
         @chat.add_message(system_msg) if system_msg
       else
-        @chat.reset_messages!
+        @chat.messages = []
       end
       self
     end
@@ -385,8 +399,8 @@ module RobotLab
     # @param messages [Array<RubyLLM::Message>] the messages to restore
     # @return [self]
     def replace_messages(messages)
-      @chat.reset_messages!
-      messages.each { |m| @chat.add_message(m) }
+      @chat.messages = []
+      messages.each { |m| @chat.add_message(coerce_replacement_message(m)) }
       self
     end
 
@@ -448,6 +462,10 @@ module RobotLab
     # @param kwargs [Hash] additional keyword args forwarded to Robot#run
     # @return [RobotResult] when async: false
     # @return [DelegationFuture] when async: true
+    # :reek:BooleanParameter :reek:ControlParameter -- async is the documented sync/future API switch.
+    # :reek:TooManyStatements -- the sync and async timing/annotation paths read best side by side.
+    # :reek:DuplicateMethodCall -- clock_gettime pairs sample distinct start/stop instants in each branch.
+    # :reek:FeatureEnvy -- annotating the delegatee's result with duration and delegator is the point of delegate.
     def delegate(to:, task:, async: false, **)
       if async
         future = DelegationFuture.new(robot_name: to.name, delegated_by: @name)
@@ -478,6 +496,7 @@ module RobotLab
     # into chat internals.
     #
     # @return [String, nil]
+    # :reek:FeatureEnvy -- duck-type unwrapping of the chat's model object.
     def chat_provider
       m = @chat.model
       m.respond_to?(:provider) ? m.provider : nil
@@ -504,6 +523,7 @@ module RobotLab
     #
     # @param text [String] the insight to record
     # @return [self]
+    # :reek:TooManyStatements -- dedupe/store/hook sequence shares the learnings state throughout.
     def learn(text)
       text = text.to_s.strip
       return self if text.empty?
@@ -561,6 +581,7 @@ module RobotLab
     # `tools:` is a NAME allowlist (a filter over available tools), not a place
     # to attach tool instances — passing instances there silently attaches
     # nothing. Catch the mistake with a clear, actionable error.
+    # :reek:FeatureEnvy -- inspecting each offending entry to build an actionable error message.
     def validate_tools_filter!(tools)
       return unless tools.is_a?(Array)
 
@@ -574,6 +595,8 @@ module RobotLab
             "(e.g. RobotLab.build(local_tools: [MyTool.new]))."
     end
 
+    # :reek:LongParameterList :reek:TooManyStatements -- one keyword and one assignment per identity ivar;
+    #   a hash would lose keyword checking.
     def assign_identity_ivars(name:, template:, system_prompt:, context:, description:,
                               local_tools:, skills:, mcp_discovery:)
       @name = name.to_s
@@ -592,6 +615,8 @@ module RobotLab
 
     # Build RunConfig from explicit kwargs, merged on top of any passed-in config.
     # Explicit constructor kwargs always win.
+    # :reek:LongParameterList -- mirrors the constructor's LLM kwargs one-to-one so explicit values win over config.
+    # :reek:FeatureEnvy -- assembling the explicit_fields hash it just built is the merge itself.
     def build_effective_config(model:, temperature:, top_p:, top_k:, max_tokens:,
                                presence_penalty:, frequency_penalty:, stop:,
                                on_tool_call:, on_tool_result:, on_content:,
@@ -640,6 +665,8 @@ module RobotLab
       @learnings           = []
       @hooks               = HookRegistry.new
       @budget_ledger       = build_budget_ledger
+      @circuit_breaker_armed      = false
+      @circuit_breaker_call_count = 0
     end
 
     def initialize_memory
@@ -691,25 +718,39 @@ module RobotLab
 
     def apply_chat_params
       @chat.with_temperature(@config.temperature) if @config.temperature
+      @chat.with_max_output_tokens(@config.max_tokens) if @config.max_tokens
 
+      # ruby_llm 2.0 has no with_params; provider-specific sampling knobs are
+      # merged into the request payload via with_provider_options instead.
+      # with_provider_options replaces prior options, so merge with whatever
+      # the chat already carries (e.g. from template front matter).
       extra_params = {
         top_p: @config.top_p, top_k: @config.top_k,
-        max_tokens: @config.max_tokens,
         presence_penalty: @config.presence_penalty,
         frequency_penalty: @config.frequency_penalty,
         stop: @config.stop
       }.compact
-      @chat.with_params(**extra_params) if extra_params.any?
+      @chat.with_provider_options(@chat.provider_options.to_h.merge(extra_params)) if extra_params.any?
     end
 
+    # ruby_llm 2.0 callbacks (before_tool_call/after_tool_result) are additive
+    # and cannot be removed, so register a single dispatcher per chat that
+    # consults the robot's current state. The per-run circuit breaker arms and
+    # disarms a flag instead of swapping callbacks.
     def register_chat_callbacks
-      @chat.on_tool_call(&@on_tool_call)     if @on_tool_call
-      @chat.on_tool_result(&@on_tool_result) if @on_tool_result
+      @chat.before_tool_call do |tool_call|
+        enforce_circuit_breaker! if @circuit_breaker_armed
+        @on_tool_call&.call(tool_call)
+      end
+      @chat.after_tool_result do |result|
+        @on_tool_result&.call(result)
+      end
       setup_bus_channel if @bus
     end
 
     # Dynamically delegate all with_* methods from @chat, returning self for chaining.
     # Discovered from the actual Chat class to avoid maintenance sync issues.
+    # :reek:NestedIterators -- the inner block is the delegator method body being defined, not an iteration.
     def define_chat_delegators
       @chat.class.public_instance_methods(false)
            .select { |m| m.start_with?('with_') }
@@ -721,6 +762,7 @@ module RobotLab
            end
     end
 
+    # :reek:ControlParameter -- `network_memory || network&.memory || @memory` is the documented memory cascade.
     def resolve_active_memory(network: nil, network_memory: nil)
       network_memory || network&.memory || @memory
     end
@@ -734,6 +776,7 @@ module RobotLab
       end
     end
 
+    # :reek:TooManyStatements -- resolve/discover/connect/filter/attach is one linear per-turn tool pipeline.
     def prepare_tools(message:, mcp:, tools:, network:, network_config:)
       resolved_mcp   = resolve_mcp_hierarchy(mcp, network: network, network_config: network_config)
       resolved_tools = resolve_tools_hierarchy(tools, network: network, network_config: network_config)
@@ -752,12 +795,16 @@ module RobotLab
       # runtime value before resolution to honor the zero-tools intent.
       filtered = explicit_none_tools?(tools) ? [] : cap_tools(filtered_tools(resolved_tools))
 
-      # replace: true so the chat holds EXACTLY this turn's resolved+capped set.
-      # RubyLLM's with_tools appends by default; on a persistent chat that lets
-      # tools accumulate across turns, so a capped per-turn addition could still
-      # push the chat's total past the provider limit. An explicit none clears
-      # the chat's tools to zero (with_tools(replace: true) with no tools).
-      @chat.with_tools(*filtered, replace: true) if filtered.any? || explicit_none_tools?(tools)
+      # Clear-then-add so the chat holds EXACTLY this turn's resolved+capped
+      # set. RubyLLM's with_tools appends; on a persistent chat that lets tools
+      # accumulate across turns, so a capped per-turn addition could still push
+      # the chat's total past the provider limit. with_tools(nil) is ruby_llm
+      # 2.0's "clear the tool set"; an explicit none stops there, sending zero
+      # tools this turn.
+      return unless filtered.any? || explicit_none_tools?(tools)
+
+      @chat.with_tools(nil)
+      @chat.with_tools(*filtered) if filtered.any?
     end
 
     # True when the runtime tools value explicitly requests zero tools — `:none`
@@ -782,13 +829,15 @@ module RobotLab
     #
     # @param tools [Array<Tool>] the resolved tools
     # @return [Array<Tool>] at most `max_tools` tools
+    # :reek:FeatureEnvy -- clamping the passed-in tool list against the provider limit is a pure filter.
     def cap_tools(tools)
-      max = effective_max_tools
-      return tools if max.nil? || tools.size <= max
+      max  = effective_max_tools
+      size = tools.size
+      return tools if max.nil? || size <= max
 
       RobotLab.config.logger.warn(
-        "[#{@name}] tool list (#{tools.size}) exceeds max_tools (#{max}); " \
-        "sending #{max}, dropping #{tools.size - max}"
+        "[#{@name}] tool list (#{size}) exceeds max_tools (#{max}); " \
+        "sending #{max}, dropping #{size - max}"
       )
       tools.first(max)
     end
@@ -802,10 +851,12 @@ module RobotLab
       configured&.positive? ? configured : DEFAULT_MAX_TOOLS
     end
 
+    # :reek:TooManyStatements -- builds the generation hook context then runs the pre-ask setup chain in order.
     def invoke_ask(context:, kwargs:, hooks:, block:)
+      network = context.network
       generation_context = LlmGenerationHookContext.new(
         robot: self,
-        network: context.network,
+        network: network,
         task: context.task,
         memory: context.memory,
         config: context.config,
@@ -814,9 +865,9 @@ module RobotLab
       )
 
       RobotLab::Hooks.run(:llm_generation, generation_context,
-                          registries: hook_registries(context.network), per_run_hooks: hooks) do
+                          registries: hook_registries(network), per_run_hooks: hooks) do
         effective_message = inject_learnings(generation_context.request)
-        maybe_compact(network: context.network)
+        maybe_compact(network: network)
         install_circuit_breaker if @config.max_tool_rounds
         install_doom_loop_detection
         ask_kwargs = kwargs.slice(:with)
@@ -830,6 +881,7 @@ module RobotLab
     end
 
     # Extract run context from SimpleFlow::Result
+    # :reek:TooManyStatements -- one delete/re-add per robot-specific run param; a loop would hide which keys are special.
     def extract_run_context(result)
       run_params = (result.context[:run_params] || {}).dup
 
@@ -846,15 +898,16 @@ module RobotLab
       base = run_params.dup
 
       # Merge current value into context
-      merged = case result.value
+      value  = result.value
+      merged = case value
                when Hash
-                 base.merge(result.value.transform_keys(&:to_sym))
+                 base.merge(value.transform_keys(&:to_sym))
                when RobotResult
-                 base.merge(message: result.value.last_text_content)
+                 base.merge(message: value.last_text_content)
                when String
-                 base.merge(message: result.value)
+                 base.merge(message: value)
                else
-                 base.merge(message: result.value.to_s)
+                 base.merge(message: value.to_s)
                end
 
       # Add back the special params
@@ -869,83 +922,6 @@ module RobotLab
       merged
     end
 
-    def build_result(response, _memory)
-      text = result_text(response)
-      output = text ? [TextMessage.new(role: 'assistant', content: text)] : []
-
-      tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
-
-      # Extract token usage from the response
-      input_toks = 0
-      output_toks = 0
-      if response.respond_to?(:tokens) && response.tokens
-        input_toks = response.tokens.input.to_i
-        output_toks = response.tokens.output.to_i
-      elsif response.respond_to?(:input_tokens)
-        input_toks = response.input_tokens.to_i
-        output_toks = response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0
-      end
-
-      @total_input_tokens += input_toks
-      @total_output_tokens += output_toks
-
-      RobotResult.new(
-        robot_name: @name,
-        output: output,
-        tool_calls: normalize_tool_calls(tool_calls),
-        stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil,
-        raw: response,
-        input_tokens: input_toks,
-        output_tokens: output_toks
-      )
-    end
-
-    # Text for the result's output. Prefers the final response's content, then
-    # falls back in order to: (1) thinking text for models that route all output
-    # through reasoning_content (e.g. qwen3 on Ollama), (2) the most recent
-    # assistant text within the current turn for models that end on a tool call
-    # with no trailing text.
-    #
-    # The chat-history fallback is scoped to messages AFTER the last user message
-    # (the current turn) to prevent a previous turn's response from being returned
-    # when a thinking-mode model emits nothing in response.content.
-    def result_text(response)
-      content = response.content if response.respond_to?(:content)
-      return content if content && !content.to_s.empty?
-
-      # Ollama routes qwen3's reasoning to reasoning_content, which ruby_llm
-      # surfaces as response.thinking (a RubyLLM::Thinking object). When content
-      # is nil and thinking is present, the thinking IS the response for that turn.
-      if response.respond_to?(:thinking) && (thinking = response.thinking)
-        thinking_text = thinking.respond_to?(:text) ? thinking.text.to_s : thinking.to_s
-        return thinking_text unless thinking_text.empty?
-      end
-
-      return nil unless @chat.respond_to?(:messages)
-
-      messages = @chat.messages
-      last_user_idx = messages.rindex { |m| m.role == :user } || -1
-      current_turn = messages[(last_user_idx + 1)..]
-
-      last = current_turn.rfind { |m| m.role == :assistant && m.content && !m.content.to_s.empty? }
-      last&.content
-    end
-
-    def normalize_tool_calls(tool_calls)
-      return [] unless tool_calls
-
-      tool_calls.map do |tc|
-        if tc.is_a?(Hash)
-          ToolResultMessage.new(
-            tool: tc,
-            content: tc[:result] || tc['result']
-          )
-        else
-          tc
-        end
-      end
-    end
-
     # Merge the stored on_content callback with a runtime streaming block.
     # If both exist, both fire (stored first, then runtime block).
     #
@@ -987,6 +963,8 @@ module RobotLab
     # Tracks tool call names; when a consecutive or cyclic repetition exceeds
     # the threshold, embeds a self-correction warning in the tool result so the
     # LLM can change strategy without requiring an external circuit breaker.
+    # :reek:TooManyStatements :reek:FeatureEnvy -- the singleton override closes over the detector;
+    #   tracking/checking it there is the design.
     def install_doom_loop_detection
       threshold = @config.doom_loop_threshold || DoomLoopDetector::DEFAULT_THRESHOLD
       detector = DoomLoopDetector.new(threshold: threshold)
@@ -1010,6 +988,7 @@ module RobotLab
     end
 
     # Remove the doom loop detection singleton method from @chat.
+    # :reek:FeatureEnvy -- checking-then-removing on the chat's singleton class is one atomic operation.
     def remove_doom_loop_detection
       sc = @chat.singleton_class
       sc.remove_method(:execute_tool) if sc.method_defined?(:execute_tool)
@@ -1025,6 +1004,9 @@ module RobotLab
     # Fires the :compaction hook family (before/around/after_compaction).
     # An on_compaction handler can replace the default strategy entirely by
     # setting ctx.compacted_messages; the core algorithm is skipped when handled.
+    # :reek:TooManyStatements -- guard chain plus hook-wrapped strategy dispatch; splitting would separate the hook from its guards.
+    # :reek:DuplicateMethodCall -- @chat.messages is read at different lifecycle points
+    #   (guard, before-snapshot, after-snapshot); it mutates in between.
     def maybe_compact(network: nil)
       return if @chat.messages.empty?
 
@@ -1083,29 +1065,5 @@ module RobotLab
         RobotLab.config.logger.warn("[#{@name}] auto_compact: #{e.message}; skipping compaction")
       end
     end
-
-    # Install a per-run circuit breaker on the chat's on_tool_call hook.
-    # Raises ToolLoopError if tool calls exceed @config.max_tool_rounds.
-    # Stores the previous callback so restore_tool_call_callback can undo it.
-    def install_circuit_breaker
-      @circuit_breaker_call_count = 0
-      max = @config.max_tool_rounds
-      original = @on_tool_call
-
-      @chat.on_tool_call do |tool_call|
-        @circuit_breaker_call_count += 1
-        if @circuit_breaker_call_count > max
-          raise ToolLoopError,
-                "Circuit breaker triggered: #{@circuit_breaker_call_count} tool calls exceeded " \
-                "max_tool_rounds (#{max})"
-        end
-        original&.call(tool_call)
-      end
-    end
-
-    # Restore the original on_tool_call callback after a circuit-breaker run.
-    def restore_tool_call_callback
-      @chat.on_tool_call(&@on_tool_call)
-    end
   end
 end

data/lib/robot_lab/robot_result.rb

@@ -60,6 +60,8 @@ module RobotLab
     # @param stop_reason [String, nil] reason for stopping
     # @param input_tokens [Integer] input tokens consumed (default 0)
     # @param output_tokens [Integer] output tokens generated (default 0)
+    # :reek:LongParameterList -- serializable value object: one keyword per persisted field.
+    # :reek:ControlParameter -- `created_at || Time.now` and `id || SecureRandom.uuid` are nil-safe defaults.
     def initialize(
       robot_name:,
       output:,
@@ -178,6 +180,7 @@ module RobotLab
     # @param hash [Hash] Serialized result data
     # @return [RobotResult]
     #
+    # :reek:DuplicateMethodCall -- Message.from_hash maps four distinct message collections; there is no shared receiver to hoist.
     def self.from_hash(hash)
       hash = hash.transform_keys(&:to_sym)
 

data/lib/robot_lab/run_config.rb

@@ -12,21 +12,22 @@ module RobotLab
   # config's non-nil values win over the less-specific config.
   #
   # @example Keyword construction
-  #   config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.7)
+  #   config = RunConfig.new(model: "claude-sonnet-4-6", temperature: 0.7)
   #
   # @example Block DSL
   #   config = RunConfig.new do |c|
-  #     c.model "claude-sonnet-4"
+  #     c.model "claude-sonnet-4-6"
   #     c.temperature 0.7
   #   end
   #
   # @example Merge (more-specific wins)
-  #   network_config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+  #   network_config = RunConfig.new(model: "claude-sonnet-4-6", temperature: 0.5)
   #   robot_config   = RunConfig.new(temperature: 0.9)
   #   effective       = network_config.merge(robot_config)
   #   effective.temperature  #=> 0.9
-  #   effective.model        #=> "claude-sonnet-4"
+  #   effective.model        #=> "claude-sonnet-4-6"
   #
+  # :reek:RepeatedConditional -- `if value` guards in independent field loops; each skips unset fields.
   class RunConfig
     # LLM configuration fields (applied to chat via with_* methods)
     LLM_FIELDS = %i[
@@ -105,6 +106,10 @@ module RobotLab
       self.class.new(**merged)
     end
 
+    # Fields that ruby_llm 2.0 accepts only through with_provider_options
+    # (merged into the request payload in the provider's own vocabulary).
+    PROVIDER_OPTION_FIELDS = %i[top_p top_k presence_penalty frequency_penalty stop].freeze
+
     # Applies LLM fields to a chat object via its with_* methods.
     #
     # +provider+/+assume_model_exists+ are threaded through to +with_model+
@@ -116,31 +121,33 @@ module RobotLab
     # raises ModelNotFoundError for any local-provider model (Ollama, etc.)
     # not in RubyLLM's bundled registry.
     #
+    # ruby_llm 2.0 mapping: +max_tokens+ applies via with_max_output_tokens,
+    # and the sampling knobs (top_p, top_k, penalties, stop) go through
+    # with_provider_options, merged with any options the chat already has.
+    #
     # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
     # @param provider [String, Symbol, nil] passed through to chat.with_model's provider: kwarg
-    # @param assume_model_exists [Boolean] passed through to chat.with_model's assume_exists: kwarg
+    # @param assume_model_exists [Boolean] passed through to chat.with_model's assume_model_exists: kwarg
+    # :reek:BooleanParameter -- assume_model_exists is a pass-through to RubyLLM's with_model kwarg.
+    # :reek:FeatureEnvy -- configuring the chat object handed in is exactly what apply_to is for.
+    # :reek:TooManyStatements -- one guarded application per LLM field group.
     def apply_to(chat, provider: nil, assume_model_exists: false)
-      LLM_FIELDS.each do |field|
-        value = @fields[field]
-        next unless value
-
-        if field == :model && provider
-          # Only take the provider-aware path when a provider was actually
-          # given -- preserves the original single-arg call (and thus
-          # compatibility with any chat-like object exposing only
-          # `with_model(value)`) for the common case.
-          chat.with_model(value, provider:, assume_exists: assume_model_exists) if chat.respond_to?(:with_model)
-        else
-          method = :"with_#{field}"
-          chat.public_send(method, value) if chat.respond_to?(method)
-        end
-      end
+      apply_model_to(chat, provider: provider, assume_model_exists: assume_model_exists)
+
+      temperature = @fields[:temperature]
+      chat.with_temperature(temperature) if temperature && chat.respond_to?(:with_temperature)
+
+      max_tokens = @fields[:max_tokens]
+      chat.with_max_output_tokens(max_tokens) if max_tokens && chat.respond_to?(:with_max_output_tokens)
+
+      apply_provider_options_to(chat)
     end
 
     # Build a RunConfig from prompt_manager front matter metadata.
     #
     # @param metadata [Object] a PM::Metadata object (responds to field names)
     # @return [RunConfig]
+    # :reek:TooManyStatements -- linear duck-typed extraction of LLM then tool fields from front matter.
     def self.from_front_matter(metadata)
       fields = {}
 
@@ -171,6 +178,7 @@ module RobotLab
 
     # @param other [RunConfig] the other RunConfig to compare
     # @return [Boolean]
+    # :reek:FeatureEnvy -- equality naturally reads the other operand.
     def ==(other)
       other.is_a?(RunConfig) && to_h == other.to_h
     end
@@ -182,6 +190,35 @@ module RobotLab
 
     private
 
+    # Apply the model field, threading provider/assume_model_exists through
+    # only when a provider was actually given -- preserves the original
+    # single-arg call (and thus compatibility with any chat-like object
+    # exposing only `with_model(value)`) for the common case.
+    # :reek:BooleanParameter -- pass-through to RubyLLM's with_model kwarg.
+    # :reek:FeatureEnvy -- configuring the chat handed in is exactly what apply_to delegates here.
+    def apply_model_to(chat, provider:, assume_model_exists:)
+      model = @fields[:model]
+      return unless model && chat.respond_to?(:with_model)
+
+      if provider
+        chat.with_model(model, provider: provider, assume_model_exists: assume_model_exists)
+      else
+        chat.with_model(model)
+      end
+    end
+
+    # Merge the sampling knobs into the chat's provider options.
+    # with_provider_options replaces prior options wholesale, so merge with
+    # the chat's current set to keep options applied earlier.
+    # :reek:FeatureEnvy -- configuring the chat handed in is exactly what apply_to delegates here.
+    def apply_provider_options_to(chat)
+      options = @fields.slice(*PROVIDER_OPTION_FIELDS)
+      return if options.empty? || !chat.respond_to?(:with_provider_options)
+
+      current = chat.respond_to?(:provider_options) ? chat.provider_options.to_h : {}
+      chat.with_provider_options(current.merge(options))
+    end
+
     # Validates and stores a field value. Nil removes the key.
     def set(field, value)
       field = field.to_sym