robot_lab 0.2.6 → 0.2.7

data/lib/robot_lab/names.rb

@@ -0,0 +1,402 @@
+# 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 Metrics/ModuleLength
+module RobotLab
+  # Fictional robot names
+  # rubocop:disable 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
+  # 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/robot/agent_skill_matching.rb

@@ -90,9 +90,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,8 +84,9 @@ 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)
@@ -165,8 +172,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 +231,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/template_rendering.rb

@@ -64,6 +64,10 @@ module RobotLab
 
       # Re-render the template with run-time context merged into build-time context.
       # prompt_manager parameters may be required (null) and only available at run time.
+      #
+      # 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.
       def rerender_template(run_context)
         merged = (@build_context || {}).merge(run_context)
         resolved_ctx = resolve_context(merged, network: nil)
@@ -81,15 +85,24 @@ module RobotLab
             bodies << body if body
           end
 
-          combined = bodies.join("\n\n")
-          @chat.with_instructions(combined)
+          @chat.with_instructions(with_system_prompt_appended(bodies.join("\n\n")))
         else
           parsed = PM.parse(@template)
           rendered = parsed.to_s(**resolved_ctx)
-          @chat.with_instructions(rendered)
+          @chat.with_instructions(with_system_prompt_appended(rendered))
         end
       end
 
+      # Append the inline system_prompt to freshly rendered template text.
+      #
+      # @param rendered [String] newly rendered template body
+      # @return [String] rendered text with system_prompt appended, if one is set
+      def with_system_prompt_appended(rendered)
+        return rendered unless @system_prompt
+
+        [rendered, @system_prompt].reject { |s| s.to_s.empty? }.join("\n\n")
+      end
+
       # Orchestrate skill expansion and template application.
       #
       # @param skill_ids [Array<Symbol>] skill IDs from constructor + front matter

data/lib/robot_lab/robot.rb

@@ -666,8 +666,27 @@ module RobotLab
       end
     end
 
+    # Append the inline system prompt to whatever apply_template already set.
+    #
+    # The template renders first and establishes the base instructions; the
+    # inline system_prompt is appended so both survive. Combining into a single
+    # system message (rather than using with_instructions(append: true), which
+    # adds a second one) keeps readers that look at only the first system
+    # message -- notably AgentSkillMatching's snapshot/restore -- correct.
     def apply_system_prompt
-      @chat.with_instructions(@system_prompt) if @system_prompt
+      return unless @system_prompt
+
+      base     = current_system_instructions.to_s
+      combined = [base, @system_prompt].reject(&:empty?).join("\n\n")
+      @chat.with_instructions(combined)
+    end
+
+    # Content of the chat's system message, or nil when none is set.
+    #
+    # @return [String, nil]
+    def current_system_instructions
+      messages = @chat.instance_variable_get(:@messages)
+      messages&.find { |m| m.role.to_s == "system" }&.content
     end
 
     def apply_chat_params
@@ -757,7 +776,9 @@ module RobotLab
     # is the definitive choke point: tools are fully resolved (MCP connected)
     # and about to be handed to the chat, so the cap holds no matter how the
     # tools were configured, filtered, or connected. Cap value comes from
-    # RunConfig#max_tools, defaulting to DEFAULT_MAX_TOOLS; nil/<=0 disables it.
+    # RunConfig#max_tools, defaulting to DEFAULT_MAX_TOOLS; a nil, zero, or
+    # negative max_tools falls back to that default, so the cap cannot be
+    # disabled from configuration.
     #
     # @param tools [Array<Tool>] the resolved tools
     # @return [Array<Tool>] at most `max_tools` tools

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.2.6"
+  VERSION = "0.2.7"
 end

data/lib/robot_lab.rb

@@ -24,9 +24,9 @@ require 'typed_bus'
 #
 # @example Creating a network of robots
 #   network = RobotLab.create_network(name: "pipeline") do
-#     step :analyzer, analyzer, depends_on: :none
-#     step :writer, writer, depends_on: [:analyzer]
-#     step :reviewer, reviewer, depends_on: [:writer]
+#     task :analyzer, analyzer, depends_on: :none
+#     task :writer, writer, depends_on: [:analyzer]
+#     task :reviewer, reviewer, depends_on: [:writer]
 #   end
 #   result = network.run(message: "Process this document")
 #
@@ -35,7 +35,7 @@ require 'typed_bus'
 #   # ROBOT_LAB_DEFAULT_MODEL=gpt-4
 #   # ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
 #
-#   # Or via config files (~/.config/robot_lab/config.yml or ./config/robot_lab.yml)
+#   # Or via config files (~/.config/robot_lab/robot_lab.yml or ./config/robot_lab.yml)
 #   # See lib/robot_lab/config/defaults.yml for all options
 #
 #   # Access configuration values:
@@ -47,6 +47,7 @@ end
 
 loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
 loader.ignore("#{__dir__}/robot_lab/robot")
+loader.ignore("#{__dir__}/robot_lab/names.rb")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
 loader.inflector.inflect(
@@ -71,6 +72,11 @@ require_relative 'robot_lab/hooks'
 require_relative 'robot_lab/message'
 require_relative 'robot_lab/memory'
 
+# names.rb defines the NAMES data constant plus helper methods directly on
+# RobotLab, not a RobotLab::Names class/module, so Zeitwerk can't autoload it
+# by convention — ignored above and required explicitly instead.
+require_relative 'robot_lab/names'
+
 # Eager load everything in Rails or when explicitly requested.
 # Otherwise Zeitwerk's lazy autoloading keeps boot fast.
 loader.eager_load if defined?(Rails::Engine) || ENV["ROBOT_LAB_EAGER_LOAD"]
@@ -145,7 +151,7 @@ module RobotLab
     # Configuration is automatically loaded from:
     # - Bundled defaults (lib/robot_lab/config/defaults.yml)
     # - Environment-specific overrides (development, test, production)
-    # - XDG config files (~/.config/robot_lab/config.yml)
+    # - XDG config file (~/.config/robot_lab/robot_lab.yml)
     # - Project config (./config/robot_lab.yml)
     # - Environment variables (ROBOT_LAB_*)
     #
@@ -246,28 +252,28 @@ module RobotLab
     #
     # @param name [String] the unique identifier for the network
     # @param concurrency [Symbol] concurrency model (:auto, :threads, :async)
-    # @yield Block for defining pipeline steps
+    # @yield Block for defining pipeline tasks (the DSL method is `task`)
     # @return [Network] a new Network instance
     #
     # @example Sequential pipeline
     #   network = RobotLab.create_network(name: "pipeline") do
-    #     step :first, robot1, depends_on: :none
-    #     step :second, robot2, depends_on: [:first]
+    #     task :first, robot1, depends_on: :none
+    #     task :second, robot2, depends_on: [:first]
     #   end
     #
     # @example With optional routing
     #   network = RobotLab.create_network(name: "support") do
-    #     step :classifier, classifier, depends_on: :none
-    #     step :billing, billing_robot, depends_on: :optional
-    #     step :technical, technical_robot, depends_on: :optional
+    #     task :classifier, classifier, depends_on: :none
+    #     task :billing, billing_robot, depends_on: :optional
+    #     task :technical, technical_robot, depends_on: :optional
     #   end
     #
     # @example Parallel execution
     #   network = RobotLab.create_network(name: "analysis") do
-    #     step :fetch, fetcher, depends_on: :none
-    #     step :sentiment, sentiment_bot, depends_on: [:fetch]
-    #     step :entities, entity_bot, depends_on: [:fetch]
-    #     step :merge, merger, depends_on: [:sentiment, :entities]
+    #     task :fetch, fetcher, depends_on: :none
+    #     task :sentiment, sentiment_bot, depends_on: [:fetch]
+    #     task :entities, entity_bot, depends_on: [:fetch]
+    #     task :merge, merger, depends_on: [:sentiment, :entities]
     #   end
     def create_network(name:, concurrency: :auto, config: nil, &)
       Network.new(name: name, concurrency: concurrency, config: config, &)

data/mkdocs.yml

@@ -177,10 +177,15 @@ nav:
       - Core Classes:
           - api/core/index.md
           - Robot: api/core/robot.md
+          - RobotResult: api/core/result.md
           - Network: api/core/network.md
-          - State: api/core/state.md
           - Tool: api/core/tool.md
           - Memory: api/core/memory.md
+          - StateProxy: api/core/state.md
+      - Hooks: api/hooks.md
+      - Skills: api/skills.md
+      - Support Classes: api/support.md
+      - Errors: api/errors.md
       - Messages:
           - api/messages/index.md
           - UserMessage: api/messages/user-message.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: robot_lab
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - Dewayne VanHoozer
@@ -235,6 +235,7 @@ files:
 - docs/api/core/state.md
 - docs/api/core/tool.md
 - docs/api/errors.md
+- docs/api/hooks.md
 - docs/api/index.md
 - docs/api/mcp/client.md
 - docs/api/mcp/index.md
@@ -245,9 +246,11 @@ files:
 - docs/api/messages/tool-call-message.md
 - docs/api/messages/tool-result-message.md
 - docs/api/messages/user-message.md
+- docs/api/skills.md
 - docs/api/streaming/context.md
 - docs/api/streaming/events.md
 - docs/api/streaming/index.md
+- docs/api/support.md
 - docs/architecture/core-concepts.md
 - docs/architecture/index.md
 - docs/architecture/message-flow.md
@@ -295,6 +298,7 @@ files:
 - examples/13_spawn.rb
 - examples/14_rusty_circuit/.envrc
 - examples/14_rusty_circuit/.gitignore
+- examples/14_rusty_circuit/README.md
 - examples/14_rusty_circuit/comic.rb
 - examples/14_rusty_circuit/display.rb
 - examples/14_rusty_circuit/heckler.rb
@@ -473,6 +477,7 @@ files:
 - lib/robot_lab/memory.rb
 - lib/robot_lab/memory_change.rb
 - lib/robot_lab/message.rb
+- lib/robot_lab/names.rb
 - lib/robot_lab/narrator.rb
 - lib/robot_lab/network.rb
 - lib/robot_lab/robot.rb
@@ -536,7 +541,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.17
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Ruby framework for building and orchestrating multi-robot LLM workflows
 test_files: []