robot_lab 0.2.1 → 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/narrator.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Opt-in live observability hook: narrates what a robot is doing as it happens,
+  # so a run is never silent between events. Complements RobotLab::Audit (which
+  # records to a persistent store) with a human-facing console feed.
+  #
+  # Enable it globally (applies to every robot run, including networks):
+  #
+  #   RobotLab::Narrator.enable!            # narrate to $stderr
+  #   RobotLab::Narrator.enable!(output: $stdout)
+  #
+  # or register like any hook for finer scope:
+  #
+  #   robot.on(RobotLab::Narrator)
+  #   network.on(RobotLab::Narrator)
+  #
+  # Output goes to $stderr by default and uses IO#puts (not Kernel#warn, which is
+  # silenced when Ruby warnings are disabled — i.e. $VERBOSE is nil, common under
+  # `bundle exec`).
+  class Narrator < RobotLab::Hook
+    self.namespace = :narrator
+
+    MAX = 80
+
+    class << self
+      attr_writer :output
+
+      # @return [IO] where narration is written (default $stderr)
+      def output
+        @output ||= $stderr
+      end
+
+      # Register the narrator globally and set its output.
+      #
+      # @param output [IO]
+      # @return [Class] self
+      def enable!(output: $stderr)
+        self.output = output
+        RobotLab.on(self)
+        self
+      end
+
+      # --- hooks ---------------------------------------------------------------
+
+      def before_llm_generation(ctx)
+        who = ctx.respond_to?(:robot) ? ctx.robot&.name : nil
+        say "#{"#{who}: " if who}thinking…"
+      rescue StandardError
+        nil
+      end
+
+      def before_tool_call(ctx)
+        say "→ #{ctx.tool_name}#{summarize(ctx.tool_args)}"
+      rescue StandardError
+        nil
+      end
+
+      def after_tool_call(ctx)
+        say "  ✗ #{clip(ctx.tool_error.message)}" if ctx.tool_error
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def say(message)
+        output.puts("  · #{message}")
+      rescue StandardError
+        nil
+      end
+
+      # Compact one-line summary of the first tool argument, e.g. " path=\"a.rb\"".
+      def summarize(args)
+        return "" unless args.is_a?(Hash) && !args.empty?
+
+        key, value = args.first
+        " #{key}=#{clip(value).inspect}"
+      end
+
+      def clip(text)
+        line = text.to_s.lines.first.to_s.strip
+        line.length > MAX ? "#{line[0, MAX]}…" : line
+      end
+    end
+  end
+end

data/lib/robot_lab/network.rb

@@ -59,6 +59,7 @@ module RobotLab
   #
   class Network
     include Utils
+    include Runnable
 
     # Reserved key for broadcast messages in memory
     BROADCAST_KEY = :_network_broadcast
@@ -71,7 +72,7 @@ module RobotLab
     #   @return [Hash<String, Robot>] robots in this network, keyed by name
     # @!attribute [r] memory
     #   @return [Memory] shared memory for all robots in the network
-    attr_reader :name, :pipeline, :robots, :memory, :config, :parallel_mode
+    attr_reader :name, :pipeline, :robots, :memory, :config, :parallel_mode, :hooks
 
     # Creates a new Network instance.
     #
@@ -94,6 +95,7 @@ module RobotLab
       @memory = memory || Memory.new(network_name: @name)
       @config = config || RunConfig.new
       @parallel_mode = parallel_mode
+      @hooks = HookRegistry.new
       @broadcast_handlers = []
       @bus_poller = BusPoller.new.start
 
@@ -132,7 +134,8 @@ module RobotLab
         mcp: mcp,
         tools: tools,
         memory: memory,
-        config: config
+        config: config,
+        network: self
       )
 
       # Register the group and assign the shared poller to the robot
@@ -177,24 +180,55 @@ module RobotLab
     #   result.value  # => RobotResult from last robot
     #   result.context[:classifier]  # => RobotResult from classifier
     #
-    def run(**run_context)
+    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.
+      run_context[:message] = message unless message.nil?
+
       # Include shared memory in run params so robots can access it
       run_context[:network_memory] = @memory
+      run_context[:network] = self
 
       # Pass network's config so robots can inherit it
       run_context[:network_config] = @config unless @config.empty?
 
-      if @parallel_mode == :ractor
-        run_with_ractor_scheduler(run_context)
-      else
-        initial_result = SimpleFlow::Result.new(
-          run_context,
-          context: { run_params: run_context }
-        )
-        @pipeline.call_parallel(initial_result, max_concurrent: @config.max_concurrent_robots)
+      context = NetworkRunHookContext.new(
+        network: self,
+        context: run_context,
+        memory: @memory,
+        config: @config
+      )
+
+      RobotLab::Hooks.run(:network_run, context, registries: [RobotLab.hooks, @hooks]) do
+        if @parallel_mode == :ractor
+          run_with_ractor_scheduler(context.context)
+        else
+          initial_result = SimpleFlow::Result.new(
+            context.context,
+            context: { run_params: context.context }
+          )
+          @pipeline.call_parallel(initial_result, max_concurrent: @config.max_concurrent_robots)
+        end
       end
     end
 
+    # Runnable protocol: the network's robots as an Array (in pipeline order),
+    # and the network? predicate. (`robots` itself stays a name=>robot Hash.)
+    #
+    # @return [Array<Robot>]
+    def crew
+      robots.values
+    end
+
+    # @return [Boolean] always true for a Network
+    def network?
+      true
+    end
+
+    def on(handler_class, context: nil)
+      @hooks.on(handler_class, context: context)
+    end
+
     # Broadcast a message to all robots in the network.
     #
     # This sends a network-wide message that all robots subscribed via
@@ -303,6 +337,19 @@ module RobotLab
       self
     end
 
+    # Remove a dynamically-added robot from the network by name. Returns the
+    # removed robot, or nil if no robot by that name was present.
+    #
+    # Only removes the robot from the crew (`@robots`); it does not rewrite the
+    # pipeline, so callers should not remove a robot that is a pipeline task.
+    #
+    # @param name [String, Symbol] the robot's name
+    # @return [Robot, nil]
+    #
+    def remove_robot(name)
+      @robots.delete(name.to_s)
+    end
+
     # Visualize the pipeline as ASCII
     #
     # @return [String, nil]
@@ -363,15 +410,7 @@ module RobotLab
       specs_with_deps = @tasks.map do |task_name, task_wrapper|
         deps = dep_graph[task_name.to_sym] || []
         deps = deps.empty? ? :none : deps.map(&:to_s)
-
-        spec = RobotSpec.new(
-          name:          task_wrapper.robot.name.freeze,
-          template:      task_wrapper.robot.template&.to_s&.freeze,
-          system_prompt: task_wrapper.robot.system_prompt&.freeze,
-          config_hash:   RactorBoundary.freeze_deep(task_wrapper.robot.config.to_json_hash)
-        )
-
-        { spec: spec, depends_on: deps }
+        { spec: build_robot_spec(task_wrapper), depends_on: deps }
       end
 
       scheduler = RactorNetworkScheduler.new(memory: @memory)
@@ -379,5 +418,23 @@ module RobotLab
       scheduler.shutdown
       results
     end
+
+    def build_robot_spec(task_wrapper)
+      robot = task_wrapper.robot
+      RobotSpec.new(
+        name:          robot.name.freeze,
+        template:      robot.template&.to_s&.freeze,
+        system_prompt: robot.system_prompt&.freeze,
+        config_hash:   RactorBoundary.freeze_deep(robot.config.to_json_hash),
+        hook_classes:  ractor_hook_classes_for(robot)
+      )
+    end
+
+    def ractor_hook_classes_for(robot)
+      [RobotLab.hooks, @hooks, robot.hooks]
+        .flat_map { |registry| registry.registrations.map(&:handler_class) }
+        .uniq
+        .freeze
+    end
   end
 end

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