robot_lab 0.2.7 → 0.2.8

data/lib/robot_lab/memory.rb

@@ -58,6 +58,9 @@ module RobotLab
   #   memory.results  # => []
   #   memory.cache  # => RubyLLM::SemanticCache instance
   #
+  # :reek:TooManyMethods -- Memory is the deliberately broad shared-state facade
+  #   (reserved keys, reactive get/subscribe, history); see CLAUDE.md.
+  # :reek:RepeatedConditional -- `@backend.key?(key)` is the check-under-mutex idiom; each site is a separate critical section.
   class Memory
     include Utils
 
@@ -89,6 +92,7 @@ module RobotLab
     #
     # @example Network-owned memory
     #   Memory.new(network_name: "support_pipeline")
+    # :reek:BooleanParameter -- enable_cache is a documented feature toggle in the public API.
     def initialize(data: {}, results: [], messages: [], session_id: nil, backend: :auto, enable_cache: true,
                    network_name: nil)
       @backend = select_backend(backend)
@@ -144,6 +148,7 @@ module RobotLab
     #
     # @see #set
     #
+    # :reek:TooManyStatements -- one case branch per reserved key; dispatch reads best as a single table.
     def []=(key, value)
       key = key.to_sym
 
@@ -292,6 +297,8 @@ module RobotLab
     #   memory.get(:sentiment, :entities, :keywords, wait: 60)
     #   # => { sentiment: {...}, entities: [...], keywords: [...] }
     #
+    # :reek:BooleanParameter -- `wait` is public API: false, true (block forever) or a numeric timeout.
+    # :reek:FeatureEnvy -- normalizing this method's own varargs before dispatching on arity.
     def get(*keys, wait: false)
       keys = keys.flatten.map(&:to_sym)
 
@@ -370,6 +377,8 @@ module RobotLab
     # @param subscription_id [Object] the subscription identifier from subscribe
     # @return [Boolean] true if subscription was found and removed
     #
+    # :reek:ControlParameter -- subscription_id is matched against stored ids, not used to select behavior.
+    # :reek:NestedIterators -- 2-deep scan of the per-key subscription lists is the natural shape.
     def unsubscribe(subscription_id)
       removed = false
 
@@ -576,6 +585,7 @@ module RobotLab
     #
     # @return [self]
     #
+    # :reek:TooManyStatements -- reserved keys are re-seeded one by one inside a single mutex block.
     def reset
       cached = get_internal(:cache)  # Preserve cache instance
       @mutex.synchronize do
@@ -695,6 +705,7 @@ module RobotLab
       RubyLLM::SemanticCache
     end
 
+    # :reek:ControlParameter -- factory method; the preference symbol is exactly what selects the backend.
     def select_backend(preference)
       case preference
       when :hash
@@ -716,11 +727,11 @@ module RobotLab
       {}
     end
 
-    def redis_available?
+    def redis_available?(config = RobotLab.config)
       return false unless defined?(Redis)
 
       # Check if Redis is configured in RobotLab
-      redis_config = RobotLab.config.respond_to?(:redis) ? RobotLab.config.redis : nil
+      redis_config = config.respond_to?(:redis) ? config.redis : nil
       redis_config || ENV.fetch("REDIS_URL", nil)
     end
 
@@ -766,6 +777,7 @@ module RobotLab
       wait_for_key(key, timeout: timeout)
     end
 
+    # :reek:TooManyStatements -- read-under-mutex then wait-for-missing; splitting would separate lock from wait logic.
     def get_multiple(keys, wait:)
       results = {}
       missing = []
@@ -791,6 +803,7 @@ module RobotLab
       results
     end
 
+    # :reek:TooManyStatements -- double-check locking plus timeout cleanup must stay together for correctness.
     def wait_for_key(key, timeout:)
       waiter = Waiter.new
 
@@ -813,11 +826,13 @@ module RobotLab
       result
     end
 
+    # :reek:UncommunicativeVariableName -- single-char block vars are accepted style here (RuboCop allows them).
     def wake_waiters(key, value)
       waiters = @waiter_mutex.synchronize { @waiters.delete(key) || [] }
       waiters.each { |w| w.signal(value) }
     end
 
+    # :reek:TooManyStatements -- collect/build/coalesce steps share the change object and the scheduling flag.
     def notify_subscribers_async(key, value, old_value)
       # Collect all matching subscribers
       callbacks = []
@@ -860,6 +875,8 @@ module RobotLab
     # Drain all pending notification batches in a single fiber.
     # Loops until the queue is empty, then resets the drainer flag.
     # If new items arrive just before the flag resets, reschedules itself.
+    # :reek:TooManyStatements :reek:NestedIterators -- the drain loop and its ensure-reschedule race guard are one
+    #   atomic unit; batch-of-callbacks iteration is inherently 2-deep.
     def drain_notification_queue
       loop do
         batch = @notification_queue_mutex.synchronize do
@@ -908,8 +925,8 @@ module RobotLab
   #
   # @api private
   class RedisBackend
-    def initialize
-      @redis = create_redis_connection
+    def initialize(config = RobotLab.config)
+      @redis = create_redis_connection(config)
       @namespace = "robot_lab:memory:#{SecureRandom.uuid}"
     end
 
@@ -945,8 +962,8 @@ module RobotLab
 
     private
 
-    def create_redis_connection
-      redis_config = RobotLab.config.respond_to?(:redis) ? RobotLab.config.redis : nil
+    def create_redis_connection(config = RobotLab.config)
+      redis_config = config.respond_to?(:redis) ? config.redis : nil
 
       if redis_config.is_a?(Hash)
         Redis.new(**redis_config)

data/lib/robot_lab/memory_change.rb

@@ -43,6 +43,7 @@ module RobotLab
     # @param timestamp [Time] when the change occurred (defaults to now)
     # @param correlation_id [String, nil] optional correlation ID
     #
+    # :reek:ControlParameter -- `timestamp || Time.now` is a nil-safe default, not behavior selection.
     def initialize(key:, value:, previous: nil, writer: nil, network_name: nil, timestamp: nil, correlation_id: nil)
       @key = key.to_sym
       @value = value

data/lib/robot_lab/message.rb

@@ -178,6 +178,7 @@ module RobotLab
     # @param id [String] the unique identifier for this tool call
     # @param name [String] the name of the tool
     # @param input [Hash, nil] the input arguments
+    # :reek:ControlParameter -- `input || {}` is a nil-safe default, not behavior selection.
     def initialize(id:, name:, input:)
       @id = id
       @name = name
@@ -238,6 +239,7 @@ module RobotLab
     # @param role [String, Symbol] the message role (usually assistant)
     # @param tools [Array<ToolMessage, Hash>] the tool calls
     # @param stop_reason [String, Symbol, nil] the stop reason (defaults to "tool")
+    # :reek:ControlParameter -- `stop_reason || "tool"` is a nil-safe default, not behavior selection.
     def initialize(role:, tools:, stop_reason: nil)
       @tools = normalize_tools(tools)
       super(type: "tool_call", role: role, content: nil, stop_reason: stop_reason || "tool")
@@ -295,6 +297,7 @@ module RobotLab
     # @param tool [ToolMessage, Hash] the tool call that was executed
     # @param content [Hash] the result content (with :data or :error key)
     # @param stop_reason [String, Symbol, nil] the stop reason (defaults to "tool")
+    # :reek:ControlParameter -- `stop_reason || "tool"` is a nil-safe default, not behavior selection.
     def initialize(tool:, content:, stop_reason: nil)
       @tool = normalize_tool(tool)
       super(type: "tool_result", role: "tool_result", content: content, stop_reason: stop_reason || "tool")

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)

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/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