robot_lab 0.2.7 → 0.3.0

data/lib/robot_lab/names.rb

@@ -2,10 +2,10 @@
 
 # A large curated word list, not application logic — kept as one inline
 # module for lookup speed, so the size/length cops below are false positives.
-# rubocop:disable Metrics/ModuleLength
+# rubocop:disable-next Metrics/ModuleLength
 module RobotLab
   # Fictional robot names
-  # rubocop:disable Metrics/CollectionLiteralLength
+  # rubocop:disable-next Metrics/CollectionLiteralLength
   NAMES = %w[
     R_7723
     R_790
@@ -394,9 +394,7 @@ module RobotLab
     Zhora
     Zoromes
   ].freeze
-  # rubocop:enable Metrics/CollectionLiteralLength
 
   def self.name = names.first
   def self.names(how_many = 1) = NAMES.sample(how_many).sort
 end
-# rubocop:enable Metrics/ModuleLength

data/lib/robot_lab/network.rb

@@ -87,6 +87,7 @@ module RobotLab
     #     task :billing, billing_robot, context: { dept: "billing" }, depends_on: :optional
     #   end
     #
+    # :reek:ControlParameter -- `memory || ...` and `config || ...` are nil-safe defaults, not behavior selection.
     def initialize(name:, concurrency: :auto, memory: nil, config: nil, parallel_mode: :async, &)
       @name = name.to_s
       @robots = {}
@@ -125,6 +126,7 @@ module RobotLab
     # @example Task with dependencies
     #   task :writer, writer_robot, depends_on: [:analyst]
     #
+    # :reek:LongParameterList -- one keyword per documented per-task option.
     def task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, depends_on: :none,
              poller_group: :default)
       task_wrapper = Task.new(
@@ -180,6 +182,7 @@ module RobotLab
     #   result.value  # => RobotResult from last robot
     #   result.context[:classifier]  # => RobotResult from classifier
     #
+    # :reek:TooManyStatements -- linear assembly of run params and hook context before dispatch.
     def run(message = nil, **run_context)
       # Runnable protocol: accept a positional message like Robot#run does, so
       # callers can `run(msg, ...)` uniformly. `run(message: msg)` still works.
@@ -200,12 +203,13 @@ module RobotLab
       )
 
       RobotLab::Hooks.run(:network_run, context, registries: [RobotLab.hooks, @hooks]) do
+        run_params = context.context
         if @parallel_mode == :ractor
-          run_with_ractor_scheduler(context.context)
+          run_with_ractor_scheduler(run_params)
         else
           initial_result = SimpleFlow::Result.new(
-            context.context,
-            context: { run_params: context.context }
+            run_params,
+            context: { run_params: run_params }
           )
           @pipeline.call_parallel(initial_result, max_concurrent: @config.max_concurrent_robots)
         end
@@ -329,11 +333,12 @@ module RobotLab
     # @raise [ArgumentError] if a robot with the same name already exists
     #
     def add_robot(robot)
-      if @robots.key?(robot.name)
-        raise ArgumentError, "Robot '#{robot.name}' already exists in network '#{@name}'"
+      name = robot.name
+      if @robots.key?(name)
+        raise ArgumentError, "Robot '#{name}' already exists in network '#{@name}'"
       end
 
-      @robots[robot.name] = robot
+      @robots[name] = robot
       self
     end
 
@@ -398,6 +403,7 @@ module RobotLab
 
     private
 
+    # :reek:TooManyStatements -- linear build-specs/run/shutdown sequence for the ractor scheduler.
     def run_with_ractor_scheduler(run_context)
       unless RobotLab.extension_loaded?(:ractor)
         raise RobotLab::DependencyError,
@@ -419,6 +425,7 @@ module RobotLab
       results
     end
 
+    # :reek:FeatureEnvy -- snapshotting a robot's identity fields into a Ractor-shareable spec is this method's job.
     def build_robot_spec(task_wrapper)
       robot = task_wrapper.robot
       RobotSpec.new(

data/lib/robot_lab/robot/agent_skill_matching.rb

@@ -40,6 +40,8 @@ module RobotLab
       # @param message [String]
       # @param threshold [Float] cosine similarity cutoff (default SIMILARITY_THRESHOLD)
       # @return [Array<AgentSkill>]
+      # :reek:TooManyStatements -- linear search/filter with a best-effort rescue fallback.
+      # :reek:NestedIterators -- 2-deep filter_map/find joining search hits back to pending skills.
       def match_agent_skills(message, threshold: SIMILARITY_THRESHOLD)
         return [] if @pending_agent_skills.nil? || @pending_agent_skills.empty?
 

data/lib/robot_lab/robot/bus_messaging.rb

@@ -91,6 +91,7 @@ module RobotLab
       # @param auto_reply [Boolean] send the responder's result back to the sender
       # @yield [message] the inbound task; return the reply content (nil => no reply)
       # @return [self]
+      # :reek:BooleanParameter :reek:ControlParameter -- auto_reply is a documented public API toggle for reply behavior.
       def respond_to_tasks(auto_reply: true, &responder)
         on_message do |message|
           next if message.reply?
@@ -107,6 +108,7 @@ module RobotLab
       #
       # @param auto_reply [Boolean]
       # @return [self]
+      # :reek:BooleanParameter -- auto_reply is a documented public API toggle, forwarded to respond_to_tasks.
       def serve(auto_reply: true)
         respond_to_tasks(auto_reply: auto_reply) { |message| run(bus_task_content(message)).reply }
       end
@@ -161,6 +163,7 @@ module RobotLab
       # @param bus [TypedBus::MessageBus, nil] bus to join (creates one if nil)
       # @return [self]
       #
+      # :reek:ControlParameter -- `bus || @bus || new` implements the documented join-or-create semantics.
       def with_bus(bus = nil)
         return self if bus && @bus == bus
 

data/lib/robot_lab/robot/history_search.rb

@@ -32,6 +32,8 @@ module RobotLab
       # @param limit [Integer] maximum number of results to return (default 5)
       # @return [Array<HistoryResult>] results sorted by score descending
       # @raise [RobotLab::DependencyError] if the 'classifier' gem is not installed
+      # :reek:TooManyStatements -- linear vectorize/score/collect scan over the chat history.
+      # :reek:FeatureEnvy -- scoring each message's extracted text against the query is the search itself.
       def search_history(query, limit: 5)
         TextAnalysis.require_classifier!
 

data/lib/robot_lab/robot/hooking.rb

@@ -3,6 +3,9 @@
 module RobotLab
   class Robot < RubyLLM::Agent
     module Hooking
+      # :reek:LongParameterList -- the documented Robot#run public API: each keyword is a distinct run-scoped override.
+      # :reek:TooManyStatements -- the run lifecycle (memory writer swap, hook wrap, budget, cleanup) is one
+      #   deliberate orchestrator; flog gates its complexity.
       def run(message = nil, network: nil, task: nil, network_memory: nil, network_config: nil,
               memory: nil, mcp: :none, tools: :none, hooks: nil, **kwargs, &block)
         run_memory = resolve_run_memory(memory, network: network, network_memory: network_memory)
@@ -51,6 +54,32 @@ module RobotLab
       def hook_registries(network = nil)
         [RobotLab.hooks, network&.hooks, @hooks]
       end
+
+      # Arm the per-run circuit breaker checked by the chat's before_tool_call
+      # dispatcher (see Robot#register_chat_callbacks). Raises ToolLoopError
+      # once tool calls exceed @config.max_tool_rounds. ruby_llm 2.0 callbacks
+      # are additive and cannot be removed, so the breaker toggles a flag the
+      # permanent dispatcher consults instead of swapping callbacks per run.
+      def install_circuit_breaker
+        @circuit_breaker_call_count = 0
+        @circuit_breaker_armed = true
+      end
+
+      # Disarm the circuit breaker after a run.
+      def restore_tool_call_callback
+        @circuit_breaker_armed = false
+      end
+
+      # Count a tool call against max_tool_rounds and raise once exceeded.
+      def enforce_circuit_breaker!
+        max = @config.max_tool_rounds
+        @circuit_breaker_call_count += 1
+        return if @circuit_breaker_call_count <= max
+
+        raise ToolLoopError,
+              "Circuit breaker triggered: #{@circuit_breaker_call_count} tool calls exceeded " \
+              "max_tool_rounds (#{max})"
+      end
     end
   end
 end

data/lib/robot_lab/robot/mcp_management.rb

@@ -11,6 +11,7 @@ module RobotLab
       private
 
       # Resolve MCP hierarchy: runtime -> robot build -> network -> config
+      # :reek:ControlParameter -- `network_config&.mcp || ...` is the documented fallback cascade, not a mode switch.
       def resolve_mcp_hierarchy(runtime_value, network: nil, network_config: nil)
         parent_value = network_config&.mcp || network_parent_config(network)&.mcp || RobotLab.config.mcp
         build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
@@ -18,6 +19,7 @@ module RobotLab
       end
 
       # Resolve tools hierarchy: runtime -> robot build -> network -> config
+      # :reek:ControlParameter -- `network_config&.tools || ...` is the documented fallback cascade, not a mode switch.
       def resolve_tools_hierarchy(runtime_value, network: nil, network_config: nil)
         parent_value = network_config&.tools || network_parent_config(network)&.tools || RobotLab.config.tools
         build_resolved = ToolConfig.resolve_tools(@tools_config, parent_value: parent_value)
@@ -32,6 +34,7 @@ module RobotLab
 
       # Ensure MCP clients are initialized for the given server configs.
       # On subsequent calls, retries any servers that previously failed to connect.
+      # :reek:TooManyStatements -- first-run init vs retry paths share the needed-server list; linear either way.
       def ensure_mcp_clients(mcp_servers)
         return if mcp_servers.empty?
 
@@ -54,6 +57,7 @@ module RobotLab
         @mcp_initialized = true
       end
 
+      # :reek:TooManyStatements -- connect success/failure bookkeeping plus the rescue path for one server.
       def init_mcp_client(server_config)
         client = MCP::Client.new(server_config)
         client.connect
@@ -78,6 +82,7 @@ module RobotLab
       end
 
       # Retry connecting to servers that previously failed
+      # :reek:TooManyStatements -- per-server retry with success bookkeeping and a best-effort rescue.
       def retry_failed_servers(_mcp_servers, needed_servers)
         return if @failed_mcp_configs.nil? || @failed_mcp_configs.empty?
 
@@ -85,8 +90,9 @@ module RobotLab
         to_retry = @failed_mcp_configs.slice(*needed_servers)
         return if to_retry.empty?
 
+        logger = RobotLab.config.logger
         to_retry.each do |name, server_config|
-          RobotLab.config.logger.info(
+          logger.info(
             "Robot '#{@name}' retrying MCP server: #{name}"
           )
 
@@ -97,17 +103,19 @@ module RobotLab
             @mcp_clients[name] = client
             @failed_mcp_configs.delete(name)
             discover_mcp_tools(client, name)
-            RobotLab.config.logger.info(
+            logger.info(
               "Robot '#{@name}' successfully connected to MCP server '#{name}' on retry"
             )
           end
         rescue StandardError => e
-          RobotLab.config.logger.warn(
+          logger.warn(
             "Robot '#{@name}' retry failed for MCP server '#{name}': #{e.message}"
           )
         end
       end
 
+      # :reek:FeatureEnvy -- adapting each MCP tool definition into a local Tool is exactly this method's purpose.
+      # :reek:NestedIterators -- the inner block is the tool's execution closure, not an iteration.
       def discover_mcp_tools(client, server_name)
         tools = client.list_tools
 

data/lib/robot_lab/robot/result_building.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Adapts a ruby_llm response into a RobotResult, including token
+    # accounting, stop-reason normalization, and message coercion helpers.
+    #
+    # Owns:    nothing (pure adapters over the response and @chat)
+    # Reads:   @chat, @name; Writes: @total_input_tokens, @total_output_tokens
+    module ResultBuilding
+      private
+
+      # :reek:TooManyStatements :reek:FeatureEnvy -- adapting a provider response's many optional fields into
+      #   a RobotResult is inherently response-centric.
+      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 || []) : []
+
+        input_toks, output_toks = extract_token_counts(response)
+        @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: extract_stop_reason(response),
+          raw: response,
+          input_tokens: input_toks,
+          output_tokens: output_toks
+        )
+      end
+
+      # Token usage from the response. ruby_llm 2.0 nests counts under
+      # response.tokens; duck-typed responses may still answer input_tokens.
+      # :reek:FeatureEnvy -- reading the response's optional token fields is the extraction itself.
+      def extract_token_counts(response)
+        if response.respond_to?(:tokens) && (tokens = response.tokens)
+          [tokens.input.to_i, tokens.output.to_i]
+        elsif response.respond_to?(:input_tokens)
+          [response.input_tokens.to_i,
+           response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0]
+        else
+          [0, 0]
+        end
+      end
+
+      # ruby_llm 2.0's add_message accepts a Message, an attribute Hash, or a
+      # record responding to to_llm. Compression summaries (and tests) hand us
+      # plain role/content value objects; convert those to attribute hashes so
+      # the chat can coerce them.
+      def coerce_replacement_message(message)
+        if message.is_a?(RubyLLM::Message) || message.is_a?(Hash) || message.respond_to?(:to_llm)
+          message
+        else
+          { role: message.role, content: message.content }
+        end
+      end
+
+      # The response's normalized stop reason. ruby_llm 2.0 exposes it as
+      # finish_reason (a Symbol such as :stop or :tool_calls); older or
+      # duck-typed responses may still answer stop_reason.
+      def extract_stop_reason(response)
+        return response.finish_reason if response.respond_to?(:finish_reason)
+
+        response.respond_to?(:stop_reason) ? response.stop_reason : nil
+      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.
+      # :reek:TooManyStatements :reek:FeatureEnvy -- documented fallback chain over the response's optional content/thinking/history fields.
+      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
+    end
+  end
+end

data/lib/robot_lab/robot/template_rendering.rb

@@ -35,6 +35,7 @@ module RobotLab
       # Apply a prompt_manager template to the persistent chat.
       # If required parameters are missing, applies front matter config but
       # defers rendering until run time when all values are available.
+      # :reek:TooManyStatements -- linear parse/merge/apply/render sequence with a documented deferred-render rescue.
       def apply_template_to_chat(context)
         parsed = PM.parse(@template)
 
@@ -68,6 +69,7 @@ module RobotLab
       # Re-rendering replaces the system message, so the inline system_prompt must be
       # re-appended here exactly as apply_system_prompt does at construction --
       # otherwise it would be silently dropped on any run that supplies context.
+      # :reek:TooManyStatements -- must rebuild skills + template + inline prompt in one pass (see comment above).
       def rerender_template(run_context)
         merged = (@build_context || {}).merge(run_context)
         resolved_ctx = resolve_context(merged, network: nil)
@@ -116,6 +118,7 @@ module RobotLab
       # Pure computation — reads ivars but does not mutate @chat.
       #
       # @return [Array(Array<String>, RunConfig, Hash)] bodies, merged config, extras hash
+      # :reek:TooManyStatements -- accumulates bodies/config/extras across skills then the main template in one pure pass.
       def collect_prompt_content(skill_ids, context)
         visited = Set.new
         visited.add(@template) if @template
@@ -128,16 +131,18 @@ module RobotLab
 
         @expanded_skills.each do |skill_id|
           parsed = PM.parse(skill_id)
-          accumulate_extras(parsed.metadata, extras)
-          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
+          metadata = parsed.metadata
+          accumulate_extras(metadata, extras)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
 
         if @template
           parsed = PM.parse(@template)
-          accumulate_extras(parsed.metadata, extras)
-          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(parsed.metadata))
+          metadata = parsed.metadata
+          accumulate_extras(metadata, extras)
+          accumulated_config = accumulated_config.merge(RunConfig.from_front_matter(metadata))
           body = render_body(parsed, resolved_ctx)
           bodies << body if body
         end
@@ -181,6 +186,7 @@ module RobotLab
       # @param visited [Set<Symbol>] already-visited IDs for cycle detection
       # @param catalog [AgentSkillCatalog] catalog to check first
       # @return [Array<Symbol>] flat ordered list of PM-based skill IDs
+      # :reek:TooManyStatements -- depth-first skill expansion with cycle guard and catalog-vs-PM branching.
       def expand_skills_with_catalog(skill_ids, visited, catalog)
         result = []
 
@@ -226,6 +232,7 @@ module RobotLab
       #
       # @param metadata [PM::Metadata] front matter metadata
       # @return [Array<Symbol>]
+      # :reek:FeatureEnvy -- reading the metadata argument's skills list is the extraction itself.
       def extract_skills_from_metadata(metadata)
         return [] unless metadata.respond_to?(:skills) && metadata.skills
 
@@ -276,6 +283,7 @@ module RobotLab
 
       # Extract identity and capability keys from front matter metadata.
       # Constructor-provided values take precedence over frontmatter.
+      # :reek:FeatureEnvy -- copying front-matter metadata fields into this robot's ivars is the method's purpose.
       def apply_front_matter_extras(metadata)
         if metadata.respond_to?(:robot_name) && metadata.robot_name && !@name_from_constructor
           @name = metadata.robot_name.to_s
@@ -309,6 +317,7 @@ module RobotLab
       # Resolve string tool names from frontmatter to Ruby constants.
       # Tool subclasses are instantiated; instances are used as-is.
       # Unresolvable names are skipped with a warning.
+      # :reek:FeatureEnvy -- inspecting each resolved constant to decide instantiate-vs-use-as-is.
       def resolve_frontmatter_tools(tool_names)
         tool_names.filter_map do |name|
           case name