robot_lab 0.2.6 → 0.2.8

data/lib/robot_lab/names.rb

@@ -0,0 +1,400 @@
+# lib/robot_lab/names.rb
+
+# 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-next Metrics/ModuleLength
+module RobotLab
+  # Fictional robot names
+  # rubocop:disable-next Metrics/CollectionLiteralLength
+  NAMES = %w[
+    R_7723
+    R_790
+    AXL
+    Adam
+    Adam_Link
+    Alfie
+    Alojzy_Kukuryk
+    Alpha_5
+    Alpha_6
+    Alsatia_Zevo
+    AMEE
+    Ancient_Ore_Crusher
+    Andrew
+    Andrew_Martin
+    Andromon
+    Aniel
+    Aqua
+    Arbeitsmaschine
+    Arthur
+    Artificial_Friend
+    Ash
+    Astor
+    Astro_Boy
+    Athena
+    Atmophytes
+    AUTO
+    Ava
+    B_4
+    BATs
+    BEN
+    BOB
+    B166ER
+    Baymax
+    BB
+    BB_8
+    Becker
+    Bender
+    Bénédict_Masson
+    Bennie
+    Beta
+    Beta_Machine
+    Billybot
+    Bishop
+    Black_Beauty
+    Blue_Senturion
+    Boilerplate
+    Boppers
+    Bors
+    Box
+    Brackenridge
+    Brainbots
+    BRL_A
+    Bruno
+    Bubo
+    Buffybot
+    BURN_E
+    Byron
+    C_3PO
+    CHOMPS
+    Calculon
+    Caliban
+    Call
+    Cambot
+    Candy_Droober
+    Carl
+    Casandra_Kresnov
+    CASE
+    Cassandra_One
+    Chani
+    CHAPPiE
+    Charlie
+    Cherry_2000
+    Chip
+    CHIP
+    Chitti
+    Chuck_the_Robot
+    Chucky
+    Chumblies
+    Claire
+    Clamps
+    Clunk
+    Coconuts
+    Coldfire
+    Coldstone
+    Colossus
+    Conky_2000
+    Coppélia
+    Coyote
+    Crimson
+    Crow_T_Robot
+    Cutie
+    Cybots
+    Cylons
+    D_FIB
+    DARYL
+    Damon
+    Data
+    David
+    David_8
+    Dee_Model
+    Dewey
+    DOR_15
+    Dorfl
+    Dot_Matrix
+    DV_8
+    ED_209
+    EDI
+    Elio
+    Elle
+    Emma_2
+    Enforcer_Drone
+    Engimals
+    EVAs
+    Eve
+    EVE
+    Evolver
+    Ez_27
+    false_Maria
+    Fembots
+    Flexo
+    Frank_Saunders
+    Franklin_Droober
+    Freya
+    Freysa
+    Frost
+    G2
+    Galaxina
+    GERTY_3000
+    Giant_Robot
+    Giddy
+    Gigantor
+    Gnut
+    GO_4
+    Goddard
+    Gog
+    Gort
+    Gort
+    Gris
+    Grounder
+    Guardromon
+    Gypsy
+    Hadaly
+    HAN_S
+    Haro
+    HCR_328
+    Hector
+    Helen_OLoy
+    Helena
+    Hermes
+    Huey
+    Hymie
+    Ilia
+    Intergalactic_Advocate_Bob
+    Jaegers
+    Janice_Em
+    Jay_Score
+    Jay_Dub
+    Jenkins
+    Jenny_Wakeman
+    Jessica
+    Jet
+    Jet_Jaguar
+    Jinx
+    Johnny_5
+    Johnny_Cab
+    Juliana_Tainer
+    K
+    K_2SO
+    K9
+    Kampfmaschin
+    KARR
+    Kay_Em_14
+    Kei
+    Kikaider
+    Killbots
+    Kirby
+    Kit
+    KITT
+    Klapaucius
+    Kronos
+    Kryten
+    Kwanzaa_Bot
+    Kyoko
+    L_76
+    L3_37
+    Lal
+    Lenny
+    Leon_Kowalski
+    Lomax
+    Lore
+    Louie
+    Luv
+    M_O
+    M3GAN
+    Mac
+    Magog
+    Mami
+    Manders
+    Mandroid
+    Marcus_Wright
+    Maria
+    Mariette
+    Marius
+    Mark_1
+    MARK13
+    Marvin
+    Mary_25
+    Maschinenmensch
+    Mata_Nui
+    Maureen_Droober
+    MAX
+    Max_404
+    Maximillian
+    May
+    MD_63
+    Mech_Eagles
+    Mecha_King_Ghidorah
+    Mechagodzilla
+    Mechagodzilla
+    Mechani_Kong
+    Mechano
+    Mechonoids
+    Mec_Willy
+    Melfina
+    Merlin_Athrawes
+    Micro_Managers
+    MM7
+    Moguera
+    MOOSE
+    Moravecs
+    Mordel
+    Morgan
+    Mr_Split
+    Mr_Static
+    Muranian
+    Necron_99
+    Neotnia
+    Newman
+    Nimani
+    Nimue_Alban
+    Norby
+    NS4
+    Okra
+    Olimpia
+    Oliver
+    Olympia
+    Omega
+    Omnidroid
+    Otis
+    POPS
+    Paws
+    Peace
+    Phatasaur
+    Phil
+    Pino_Petto
+    PR_T
+    Primus
+    Pris
+    Project_2501
+    Proteus_IV
+    Quinn
+    R_Daneel_Olivaw
+    R_Giskard_Reventlov
+    RALF
+    ROTOR
+    R2_D2
+    R4_P17
+    Rabbot
+    Rachael
+    Radius
+    Rena
+    Replicators
+    Rex
+    RIA
+    Richard_Daniel
+    Rick_Deckard
+    Ro_Man_Extension_XJ_2
+    Rob_Monkey
+    Robbie
+    Robby
+    Robo
+    Robo_Clowns
+    RoboDoc
+    RoboGadget
+    Robot_7
+    Robot_B_9
+    Robot_Devil
+    Robot_Santa
+    Robot_ZX29B
+    Robotoid
+    Roderick
+    Rosie
+    Roy_Batty
+    Roz
+    ROZZUM_unit_7134
+    SAR_003
+    S1MONE
+    Samantha
+    Sapper_Morton
+    Sara
+    Scratch
+    Sentinels
+    Setaur
+    Sheen
+    Sheriff_Not_a_Robot
+    SHROUD
+    SI_9
+    Sico
+    SID_67
+    SIMON
+    Skutters
+    Solo
+    Sonny
+    Sox
+    Sparks
+    Speedy
+    Spofforth
+    Spot
+    Stitchpunks
+    Sulla
+    T_1000
+    T_600
+    T_800
+    T_850
+    T_Bob
+    T_X
+    Talkie_Toaster
+    TARS
+    Terminus
+    Tet
+    The_Automaton
+    The_Cast_Iron_Man
+    The_Electric_Grandmother
+    The_Fury
+    The_Golden_Army
+    The_Gunslinger
+    The_Hangman
+    The_Iron_Giant
+    The_Iron_Man
+    The_Juggernaut
+    The_Mechanical_Cow
+    The_Mechanical_Dummy
+    The_Mechanical_Horse
+    The_Mechanical_Hound
+    The_One_Who_Waits
+    Tin_Man
+    Tik_Tok
+    Tilk
+    Tilly
+    Tima
+    Toaster
+    Tobor
+    Tom
+    Tom_Servo
+    Tony
+    Torg
+    Trace_Mayter
+    Trurl
+    Twonky
+    Ultron
+    Ulyssses
+    UniBlab
+    US_47
+    VINCENT
+    Vahki
+    Val
+    Valerie_23
+    Vanessa_Kensington
+    VAQ_M
+    Victor
+    Vision
+    VN_GO
+    Voltron
+    WALL_E
+    Walter_One
+    Weebo
+    Wilmer
+    XJ_9
+    Yod
+    Z_1
+    Z_2
+    Z_3
+    Zane_Gort
+    Zat
+    Zhora
+    Zoromes
+  ].freeze
+
+  def self.name = names.first
+  def self.names(how_many = 1) = NAMES.sample(how_many).sort
+end

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?
 
@@ -90,9 +92,7 @@ module RobotLab
       #
       # @return [String, nil]
       def current_agent_skill_instructions
-        messages = @chat.instance_variable_get(:@messages)
-        sys = messages&.find { |m| m.role.to_s == "system" }
-        sys&.content
+        current_system_instructions
       end
     end
   end

data/lib/robot_lab/robot/bus_messaging.rb

@@ -12,9 +12,15 @@ module RobotLab
     # == Delivery Serialization
     #
     # TypedBus delivers messages in concurrent Async fibers. Robots
-    # enqueue deliveries into a BusPoller rather than handling them
-    # inline. The BusPoller drains each group's queue sequentially on
-    # a dedicated OS thread, so robot.run() calls never interleave.
+    # enqueue deliveries into a shared BusPoller rather than dispatching
+    # them straight to the handler. Despite the name, BusPoller runs no
+    # background thread: `enqueue` processes the delivery inline in the
+    # caller's own execution context (Async fiber or OS thread) when the
+    # robot is idle, and otherwise queues it behind the delivery already
+    # in flight and drains it once that one returns. A mutex therefore
+    # serializes deliveries per robot, so a robot's run() calls never
+    # interleave — but nothing makes progress while the calling fiber is
+    # parked.
     #
     # Owns:    @bus, @bus_poller, @private_bus_poller, @bus_poller_group, @bus_subscriber_id, @message_counter, @outbox, @message_handler
     # Reads:   @name
@@ -78,12 +84,14 @@ module RobotLab
       # counterpart to how a Cyborg answers its human — one call makes any bus
       # member a first-class responder instead of hand-wiring {#on_message}.
       #
-      # The responder runs on the poller drain thread, so deliveries to this member
-      # are handled one at a time (a long turn delays the next inbound message).
+      # The responder runs inline in the caller's execution context (BusPoller has
+      # no drain thread), and deliveries to this member are serialized, so a long
+      # turn blocks both the sender and the next inbound message.
       #
       # @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?
@@ -100,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
@@ -154,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
 
@@ -165,8 +175,9 @@ module RobotLab
 
       # Assign a shared BusPoller from a Network.
       #
-      # Stops any private poller this robot auto-created, then adopts
-      # the network's shared poller for the given group.
+      # Drops any private poller this robot auto-created, then adopts
+      # the network's shared poller for the given group. Called by
+      # Network#task; groups are informational labels only.
       #
       # @param poller [BusPoller] the network's shared poller
       # @param group  [Symbol]    poller group for this robot (default: :default)
@@ -223,7 +234,7 @@ module RobotLab
         @bus_poller.enqueue(robot: self, delivery: delivery, group: @bus_poller_group)
       end
 
-      # Process a single delivery (called by BusPoller drain thread).
+      # Process a single delivery (called by BusPoller during its inline drain).
       def process_delivery(delivery)
         message = delivery.message
         correlate_reply(message) if message.reply?

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