robot_lab 0.1.0 → 0.2.6

data/lib/robot_lab/memory.rb

@@ -89,7 +89,8 @@ module RobotLab
     #
     # @example Network-owned memory
     #   Memory.new(network_name: "support_pipeline")
-    def initialize(data: {}, results: [], messages: [], session_id: nil, backend: :auto, enable_cache: true, network_name: nil)
+    def initialize(data: {}, results: [], messages: [], session_id: nil, backend: :auto, enable_cache: true,
+                   network_name: nil)
       @backend = select_backend(backend)
       @mutex = Mutex.new
       @enable_cache = enable_cache
@@ -104,7 +105,7 @@ module RobotLab
       set_internal(:cache, @enable_cache ? RubyLLM::SemanticCache : nil)
 
       # Data proxy for method-style access
-      @data_proxy = nil
+      @data = nil
 
       # Reactive infrastructure
       @subscriptions = Hash.new { |h, k| h[k] = [] }
@@ -149,7 +150,7 @@ module RobotLab
       # Reserved keys have special handling (no notifications)
       case key
       when :data
-        @data_proxy = nil  # Reset proxy
+        @data = nil  # Reset proxy
         set_internal(:data, value.is_a?(Hash) ? value.transform_keys(&:to_sym) : value)
       when :results
         set_internal(:results, Array(value))
@@ -164,8 +165,6 @@ module RobotLab
         # Non-reserved keys use reactive set
         set(key, value)
       end
-
-      value
     end
 
     # Access runtime data through StateProxy
@@ -173,7 +172,7 @@ module RobotLab
     # @return [StateProxy] proxy for method-style data access
     #
     def data
-      @data_proxy ||= StateProxy.new(get_internal(:data) || {})
+      @data ||= StateProxy.new(get_internal(:data) || {})
     end
 
     # Get copy of results (immutable access)
@@ -207,7 +206,6 @@ module RobotLab
     #
     def session_id=(id)
       set_internal(:session_id, id)
-      self
     end
 
     # Get the semantic cache module
@@ -450,16 +448,14 @@ module RobotLab
     #   hits.each { |h| puts "#{h[:key]} (#{h[:score].round(3)}): #{h[:text][0..80]}" }
     #
     def search_documents(query, limit: 5)
-      return [] unless @document_store
-
-      @document_store.search(query, limit: limit)
+      document_store.search(query, limit: limit)
     end
 
     # Keys of all documents stored in the embedded document store.
     #
     # @return [Array<Symbol>]
     def document_keys
-      @document_store&.keys || []
+      document_store.keys
     end
 
     # Remove a document from the store.
@@ -467,7 +463,7 @@ module RobotLab
     # @param key [Symbol, String]
     # @return [self]
     def delete_document(key)
-      @document_store&.delete(key)
+      document_store.delete(key)
       self
     end
 
@@ -590,7 +586,7 @@ module RobotLab
         @backend[:session_id] = nil
         @backend[:cache] = cached  # Restore cache instance
       end
-      @data_proxy = nil
+      @data = nil
       self
     end
 
@@ -641,7 +637,7 @@ module RobotLab
         results: results.map(&:export),
         messages: messages.map(&:to_h),
         session_id: session_id,
-        custom: keys.each_with_object({}) { |k, h| h[k] = self[k] }
+        custom: keys.to_h { |k| [k, self[k]] }
       }.compact
     end
 
@@ -650,8 +646,8 @@ module RobotLab
     # @param args [Array] arguments passed to to_json
     # @return [String]
     #
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Reconstruct memory from hash
@@ -687,7 +683,12 @@ module RobotLab
     private
 
     def document_store
-      @document_store ||= DocumentStore.new
+      unless RobotLab.extension_loaded?(:document_store)
+        raise RobotLab::DependencyError,
+              "document storage requires the robot_lab-document_store gem. " \
+              "Add `gem 'robot_lab-document_store'` to your Gemfile."
+      end
+      @document_store ||= RobotLab::DocumentStore.new
     end
 
     def create_semantic_cache
@@ -696,11 +697,9 @@ module RobotLab
 
     def select_backend(preference)
       case preference
-      when :redis
-        create_redis_backend || create_hash_backend
       when :hash
         create_hash_backend
-      else # :auto
+      else # :redis, :auto
         create_redis_backend || create_hash_backend
       end
     end
@@ -722,7 +721,7 @@ module RobotLab
 
       # Check if Redis is configured in RobotLab
       redis_config = RobotLab.config.respond_to?(:redis) ? RobotLab.config.redis : nil
-      redis_config || ENV["REDIS_URL"]
+      redis_config || ENV.fetch("REDIS_URL", nil)
     end
 
     def get_internal(key)
@@ -877,8 +876,15 @@ module RobotLab
       end
     ensure
       reschedule = @notification_queue_mutex.synchronize do
-        @drainer_scheduled = false
-        !@notification_queue.empty?
+        if @notification_queue.empty?
+          @drainer_scheduled = false
+          false
+        else
+          # Keep the flag set so concurrent writers don't also spawn a drainer.
+          # Only we will reschedule — no double-schedule race.
+          @drainer_scheduled = true
+          true
+        end
       end
       dispatch_async { drain_notification_queue } if reschedule
     end
@@ -890,9 +896,9 @@ module RobotLab
     def pattern_to_regex(pattern)
       # Convert glob pattern to regex
       regex_str = pattern
-        .gsub(".", "\\.")
-        .gsub("*", ".*")
-        .gsub("?", ".")
+                  .gsub(".", "\\.")
+                  .gsub("*", ".*")
+                  .gsub("?", ".")
 
       Regexp.new("\\A#{regex_str}\\z")
     end
@@ -917,7 +923,6 @@ module RobotLab
     def []=(key, value)
       serialized = value.is_a?(String) ? value : value.to_json
       @redis.set("#{@namespace}:#{key}", serialized)
-      value
     end
 
     def key?(key)

data/lib/robot_lab/memory_change.rb

@@ -98,8 +98,8 @@ module RobotLab
     # @param args [Array] arguments passed to to_json
     # @return [String]
     #
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Reconstruct from hash.

data/lib/robot_lab/message.rb

@@ -79,8 +79,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation of the message
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Creates a Message instance from a hash.
@@ -200,8 +200,8 @@ module RobotLab
     #
     # @param args [Array] arguments passed to to_json
     # @return [String] JSON representation
-    def to_json(*args)
-      to_h.to_json(*args)
+    def to_json(*)
+      to_h.to_json(*)
     end
 
     # Creates a ToolMessage from a hash.

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.
     #
@@ -86,7 +87,7 @@ module RobotLab
     #     task :billing, billing_robot, context: { dept: "billing" }, depends_on: :optional
     #   end
     #
-    def initialize(name:, concurrency: :auto, memory: nil, config: nil, parallel_mode: :async, &block)
+    def initialize(name:, concurrency: :auto, memory: nil, config: nil, parallel_mode: :async, &)
       @name = name.to_s
       @robots = {}
       @tasks = {}
@@ -94,10 +95,11 @@ 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
 
-      instance_eval(&block) if block_given?
+      instance_eval(&) if block_given?
     end
 
     # Add a robot as a pipeline task with optional per-task configuration
@@ -123,7 +125,8 @@ module RobotLab
     # @example Task with dependencies
     #   task :writer, writer_robot, depends_on: [:analyst]
     #
-    def task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, depends_on: :none, poller_group: :default)
+    def task(name, robot, context: {}, mcp: :none, tools: :none, memory: nil, config: nil, depends_on: :none,
+             poller_group: :default)
       task_wrapper = Task.new(
         name: name,
         robot: robot,
@@ -131,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
@@ -158,8 +162,8 @@ module RobotLab
     #   end
     #   task :process, processor, depends_on: :fetch_data
     #
-    def parallel(name = nil, depends_on: :none, &block)
-      @pipeline.parallel(name, depends_on: depends_on, &block)
+    def parallel(name = nil, depends_on: :none, &)
+      @pipeline.parallel(name, depends_on: depends_on, &)
       self
     end
 
@@ -176,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
@@ -302,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]
@@ -351,21 +399,18 @@ module RobotLab
     private
 
     def run_with_ractor_scheduler(run_context)
+      unless RobotLab.extension_loaded?(:ractor)
+        raise RobotLab::DependencyError,
+              "parallel_mode: :ractor requires the robot_lab-ractor gem. " \
+              "Add `gem 'robot_lab-ractor'` to your Gemfile."
+      end
       message   = run_context[:message].to_s
       dep_graph = @pipeline.step_dependencies  # { task_sym => [dep_sym, ...] }
 
       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)
@@ -374,5 +419,22 @@ module RobotLab
       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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Prepended module that intercepts run() to inject relevant AgentSkills.io
+    # skills into the system prompt and tool list for the duration of each call.
+    #
+    # Owns:    @_active_agent_skills, @_agent_skill_original_instructions, @_agent_skill_injected_tools
+    # Reads:   @pending_agent_skills, @agent_skill_store, @local_tools, @chat, @name
+    # Contract: prepended (wraps super); requires TemplateRendering to have set @pending_agent_skills
+    #
+    # Skills are matched by embedding similarity between the incoming message
+    # and each pending skill's description (via DocumentStore/fastembed).
+    # Injected content is fully restored in an ensure block after run() returns.
+    module AgentSkillMatching
+      SIMILARITY_THRESHOLD = 0.70
+
+      def run(message = nil, **, &)
+        matched = match_agent_skills(message.to_s)
+        inject_agent_skills(matched) if matched.any?
+        super
+      ensure
+        restore_after_agent_skills if @_active_agent_skills&.any?
+      end
+
+      # Override to re-inject skill instructions after template re-render replaces
+      # the system prompt during a run() call with runtime kwargs.
+      def rerender_template(run_context)
+        super
+        return unless @_active_agent_skills&.any?
+
+        @_agent_skill_original_instructions = current_agent_skill_instructions
+        prepend_skill_instructions(@_active_agent_skills)
+      end
+
+      private
+
+      # Find pending AgentSkills whose descriptions are semantically similar to message.
+      #
+      # @param message [String]
+      # @param threshold [Float] cosine similarity cutoff (default SIMILARITY_THRESHOLD)
+      # @return [Array<AgentSkill>]
+      def match_agent_skills(message, threshold: SIMILARITY_THRESHOLD)
+        return [] if @pending_agent_skills.nil? || @pending_agent_skills.empty?
+
+        results = @agent_skill_store.search(message, limit: @pending_agent_skills.size)
+        results
+          .select { |r| r[:score] >= threshold }
+          .filter_map { |r| @pending_agent_skills.find { |s| s.name.to_sym == r[:key] } }
+      rescue => e
+        RobotLab.config.logger.warn(
+          "Robot '#{@name}': AgentSkill embedding failed: #{e.message}"
+        )
+        []
+      end
+
+      # Prepend skill instructions before existing system prompt content.
+      #
+      # @param skills [Array<AgentSkill>]
+      def prepend_skill_instructions(skills)
+        skill_content = skills.map(&:instructions).join("\n\n")
+        base          = @_agent_skill_original_instructions.to_s
+        combined      = [skill_content, base].reject(&:empty?).join("\n\n")
+        @chat.with_instructions(combined)
+      end
+
+      # Inject script tools and snapshot instructions before injection.
+      #
+      # @param skills [Array<AgentSkill>]
+      def inject_agent_skills(skills)
+        return if skills.empty?
+
+        @_active_agent_skills               = skills
+        @_agent_skill_original_instructions = current_agent_skill_instructions
+        prepend_skill_instructions(skills)
+        @_agent_skill_injected_tools = skills.flat_map(&:script_tools).compact
+        @local_tools += @_agent_skill_injected_tools
+      end
+
+      # Remove injected tools and restore original system prompt.
+      def restore_after_agent_skills
+        @local_tools -= @_agent_skill_injected_tools || []
+        @chat.with_instructions(@_agent_skill_original_instructions.to_s)
+        @_active_agent_skills               = nil
+        @_agent_skill_original_instructions = nil
+        @_agent_skill_injected_tools        = nil
+      end
+
+      # Read the current system message content from the underlying chat.
+      #
+      # @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
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/budget.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Token/cost budget enforcement for a single Robot, backed by a
+    # RobotLab::Budget::Ledger.
+    #
+    # Two layers of enforcement:
+    # - reserve_budget!/reconcile_budget! wrap each LLM call. reserve_budget!
+    #   raises BudgetExceeded up front when a *prior* call already pushed
+    #   usage over budget, so a robot with an exhausted budget refuses
+    #   further calls instead of spending on them.
+    # - enforce_token_budget!/enforce_cost_budget! run after the call
+    #   completes and raise InferenceError when *this* call's actual usage
+    #   pushed cumulative usage over budget — unavoidable for the call that
+    #   causes the overage, since token/cost totals aren't known until the
+    #   response comes back.
+    module Budget
+      private
+
+      # @return [RobotLab::Budget::Ledger, nil] nil when neither token_budget
+      #   nor cost_budget is configured
+      def build_budget_ledger
+        limits = { tokens: @config.token_budget, cost: @config.cost_budget }.compact
+        return nil if limits.empty?
+
+        RobotLab::Budget::Ledger.new(limits: limits)
+      end
+
+      def enforce_token_budget!
+        budget = @config.token_budget
+        return unless budget && @total_input_tokens + @total_output_tokens > budget
+
+        raise InferenceError,
+              "Token budget exceeded: #{@total_input_tokens + @total_output_tokens} tokens used, budget is #{budget}"
+      end
+
+      def enforce_cost_budget!
+        budget = @config.cost_budget
+        return unless budget && @budget_ledger
+
+        consumed = @budget_ledger.consumed[:cost]
+        return unless consumed > budget
+
+        raise InferenceError,
+              format("Cost budget exceeded: $%<consumed>.6f used, budget is $%<budget>.6f",
+                     consumed: consumed, budget: budget)
+      end
+
+      # Reserves whatever remains of each configured budget dimension
+      # before attempting the LLM call.
+      #
+      # @return [Hash{Symbol=>Numeric}] the amount reserved per dimension, to pass to reconcile_budget!
+      # @raise [RobotLab::BudgetExceeded] if a dimension is already exhausted
+      def reserve_budget!
+        return {} unless @budget_ledger
+
+        @budget_ledger.limits.each_key.with_object({}) do |dimension, reservation|
+          amount = @budget_ledger.remaining(dimension)
+          @budget_ledger.reserve!(dimension, amount)
+          reservation[dimension] = amount
+        end
+      end
+
+      # Replaces a reservation from reserve_budget! with the actual usage
+      # from this call.
+      #
+      # @param reservation [Hash{Symbol=>Numeric}] the value returned by reserve_budget!
+      # @param response [Object] the raw LLM response, used to extract actual cost
+      # @param result [RobotResult] the built result, used to extract actual tokens
+      def reconcile_budget!(reservation, response:, result:)
+        return unless reservation&.any?
+
+        actual = { tokens: result.input_tokens + result.output_tokens, cost: extract_cost(response) }
+        reservation.each_pair { |dimension, amount| @budget_ledger.reconcile!(dimension, amount, actual[dimension] || 0) }
+      end
+
+      # @param response [Object] the raw LLM response
+      # @return [Float] the response's total cost, or 0.0 when unavailable (no pricing data)
+      def extract_cost(response)
+        return 0.0 unless response.respond_to?(:cost)
+
+        response.cost.total.to_f
+      rescue StandardError
+        0.0
+      end
+    end
+  end
+end