robot_lab 0.0.9 → 0.0.12

data/lib/robot_lab/ractor_memory_proxy.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "ractor/wrapper"
+
+module RobotLab
+  # Wraps a Memory instance via Ractor::Wrapper so Ractor workers can safely
+  # read and write shared state.
+  #
+  # Only get, set, and keys are proxied across the Ractor boundary.
+  # Subscriptions and callbacks are NOT proxied — closures are not
+  # Ractor-safe. Use the thread-side Memory directly for reactive subscriptions.
+  #
+  # Values passed to set() must be Ractor-shareable; RactorBoundary.freeze_deep
+  # is applied automatically.
+  #
+  # The proxy uses use_current_ractor: true so the Memory object stays in the
+  # calling Ractor and is not moved. This allows direct access alongside the
+  # proxy and works with Memory's mutex-based internals.
+  #
+  # @example
+  #   memory = Memory.new
+  #   proxy  = RactorMemoryProxy.new(memory)
+  #
+  #   # From any Ractor via the stub:
+  #   proxy.set(:result, "done")
+  #   proxy.get(:result)   #=> "done"
+  #
+  #   proxy.shutdown  # call when done
+  #
+  class RactorMemoryProxy
+    # @param memory [Memory] the memory instance to wrap
+    def initialize(memory)
+      @memory  = memory
+      @wrapper = Ractor::Wrapper.new(memory, use_current_ractor: true)
+      @stub    = @wrapper.stub
+    end
+
+    # Returns the Ractor-shareable stub for use inside Ractors.
+    #
+    # The stub proxies get/set/keys to the wrapped Memory. Pass this to
+    # Ractor.new rather than the proxy itself (the proxy is not shareable).
+    #
+    # @return [Ractor::Wrapper stub]
+    def stub
+      @stub
+    end
+
+    # Read a value from the proxied Memory.
+    #
+    # @param key [Symbol]
+    # @return [Object, nil]
+    def get(key)
+      @stub.get(key)
+    end
+
+    # Write a frozen value to the proxied Memory.
+    # The value is deep-frozen before crossing the Ractor boundary.
+    #
+    # @param key [Symbol]
+    # @param value [Object] must be Ractor-shareable after freeze_deep
+    # @return [void]
+    # @raise [RactorBoundaryError] if value cannot be made shareable
+    def set(key, value)
+      frozen_value = RactorBoundary.freeze_deep(value)
+      @stub.set(key, frozen_value)
+    end
+
+    # List all keys currently set in the proxied Memory.
+    #
+    # @return [Array<Symbol>]
+    def keys
+      @stub.keys
+    end
+
+    # Shut down the ractor-wrapper.
+    #
+    # @return [void]
+    def shutdown
+      @wrapper.async_stop
+      @wrapper.join
+    rescue => e
+      RobotLab.config.logger.warn("RactorMemoryProxy shutdown error: #{e.message}")
+    end
+  end
+end

data/lib/robot_lab/ractor_network_scheduler.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "etc"
+require "ractor_queue"
+
+module RobotLab
+  # Schedules frozen robot task descriptions across Ractor workers.
+  #
+  # Robots stay in threads for LLM calls (ruby_llm is not Ractor-safe).
+  # The scheduler distributes frozen RobotSpec payloads; each worker
+  # constructs a fresh Robot, runs the task, and returns a frozen result.
+  #
+  # Task ordering respects depends_on: tasks are only dispatched once all
+  # named dependencies have resolved (same topological semantics as
+  # SimpleFlow::Pipeline).
+  #
+  # @example
+  #   scheduler = RactorNetworkScheduler.new(memory: shared_memory)
+  #   scheduler.run_pipeline([
+  #     { spec: analyst_spec, depends_on: :none },
+  #     { spec: writer_spec,  depends_on: ["analyst"] }
+  #   ], message: "Process this")
+  #   scheduler.shutdown
+  #
+  class RactorNetworkScheduler
+    # Capacity for the work queue.
+    QUEUE_CAPACITY = 256
+
+    # @param memory [Memory] shared network memory for all robot tasks
+    # @param pool_size [Integer, :auto] number of Ractor workers
+    def initialize(memory:, pool_size: :auto)
+      @memory   = memory
+      @work_q   = RactorQueue.new(capacity: QUEUE_CAPACITY)
+      @size     = pool_size == :auto ? Etc.nprocessors : pool_size.to_i
+      @workers  = @size.times.map { spawn_worker(@work_q) }
+      @closed   = false
+    end
+
+    # Run a single spec and return the result string.
+    #
+    # @param spec [RobotSpec]
+    # @param message [String]
+    # @return [String] the robot's last_text_content
+    def run_spec(spec, message:)
+      execute_spec(spec, message)
+    end
+
+    # Run a pipeline of specs in dependency order.
+    #
+    # @param specs_with_deps [Array<Hash>] each entry has :spec and :depends_on
+    #   :depends_on is :none, :optional, or an Array<String> of spec names
+    # @param message [String] initial message passed to entry-point robots
+    # @return [Hash<String, String>] name => result for each completed robot
+    def run_pipeline(specs_with_deps, message:)
+      completed = {}  # name => result string
+      remaining = specs_with_deps.dup
+
+      until remaining.empty?
+        ready, remaining = remaining.partition do |entry|
+          deps = entry[:depends_on]
+          deps == :none || deps == :optional ||
+            Array(deps).all? { |d| completed.key?(d) }
+        end
+
+        raise RobotLab::Error, "Circular dependency or unresolvable deps in RactorNetworkScheduler" if ready.empty?
+
+        # Submit all ready tasks concurrently via threads.
+        # report_on_exception is disabled because exceptions are propagated
+        # to the caller via t.value — the default reporting is redundant noise.
+        threads = ready.map do |entry|
+          spec = entry[:spec]
+          msg  = completed.values.last || message
+          Thread.new { [spec.name, execute_spec(spec, msg)] }.tap { |t| t.report_on_exception = false }
+        end
+
+        threads.each do |t|
+          name, result = t.value
+          completed[name] = result
+        end
+      end
+
+      completed
+    end
+
+    # Gracefully shut down worker Ractors.
+    # @return [void]
+    def shutdown
+      return if @closed
+
+      @closed = true
+      @size.times { @work_q.push(nil) }
+      @workers.each { |w| w.join rescue nil }
+    end
+
+    private
+
+    # Dispatch a spec to a Ractor worker and block for the result.
+    def execute_spec(spec, message)
+      frozen_spec    = Ractor.make_shareable(spec)
+      frozen_message = message.to_s.freeze
+      reply_q        = RactorQueue.new(capacity: 1)
+
+      job = RactorJob.new(
+        id:          SecureRandom.uuid.freeze,
+        type:        :robot,
+        payload:     RactorBoundary.freeze_deep({
+          spec:    frozen_spec,
+          message: frozen_message
+        }),
+        reply_queue: reply_q
+      )
+
+      @work_q.push(job)
+      result = reply_q.pop
+
+      if result.is_a?(RactorJobError)
+        raise RobotLab::Error, "Robot '#{spec.name}' failed in Ractor: #{result.message}"
+      end
+
+      result
+    end
+
+    def spawn_worker(work_q)
+      Ractor.new(work_q) do |q|
+        loop do
+          job = q.pop
+          break if job.nil?
+
+          begin
+            spec    = job.payload[:spec]
+            message = job.payload[:message]
+
+            robot = RobotLab::Robot.new(
+              name:          spec.name,
+              template:      spec.template ? spec.template.to_sym : nil,
+              system_prompt: spec.system_prompt,
+              config:        spec.config_hash.empty? ? nil : RobotLab::RunConfig.new(**spec.config_hash.transform_keys(&:to_sym))
+            )
+
+            robot_result  = robot.run(message)
+            frozen_reply  = robot_result.last_text_content.to_s.freeze
+            job.reply_queue.push(frozen_reply)
+          rescue => e
+            err = RobotLab::RactorJobError.new(
+              message:   e.message.freeze,
+              backtrace: (e.backtrace || []).map(&:freeze).freeze
+            )
+            job.reply_queue.push(err)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/ractor_worker_pool.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "etc"
+require "ractor_queue"
+
+module RobotLab
+  # A pool of Ractor workers that execute CPU-bound, Ractor-safe tools.
+  #
+  # Work is distributed via a shared RactorQueue. Each worker runs a
+  # blocking loop, pops RactorJob instances, dispatches to the named
+  # tool class, and pushes the frozen result (or a RactorJobError) to
+  # the job's per-job reply_queue.
+  #
+  # Shutdown uses a poison-pill pattern: one nil sentinel per worker is
+  # pushed to the work queue; each worker exits when it pops nil.
+  #
+  # Only tools that declare +ractor_safe true+ should be submitted.
+  # Tool classes are instantiated fresh inside the Ractor for each call.
+  #
+  # @example
+  #   pool = RactorWorkerPool.new(size: 4)
+  #   result = pool.submit("MyTool", { "arg" => "value" })
+  #   pool.shutdown
+  #
+  class RactorWorkerPool
+    # Capacity of the shared work queue.
+    QUEUE_CAPACITY = 1024
+
+    # @return [Integer] number of worker Ractors
+    attr_reader :size
+
+    # Creates a new pool and starts worker Ractors immediately.
+    #
+    # @param size [Integer, :auto] number of workers (:auto = Etc.nprocessors)
+    def initialize(size: :auto)
+      @size    = size == :auto ? Etc.nprocessors : size.to_i
+      @closed  = false
+      @work_q  = RactorQueue.new(capacity: QUEUE_CAPACITY)
+      @workers = @size.times.map { spawn_worker(@work_q) }
+    end
+
+    # Submit a tool job and block until the result is available.
+    #
+    # @param tool_class_name [String] fully-qualified Ruby constant name of the tool class
+    # @param args [Hash] tool arguments (deep-frozen before crossing Ractor boundary)
+    # @return [Object] the tool's return value
+    # @raise [RactorBoundaryError] if args cannot be made Ractor-shareable
+    # @raise [ToolError] if the tool raises inside the Ractor
+    def submit(tool_class_name, args)
+      raise ToolError, "Pool is shut down" if @closed
+
+      reply_q = RactorQueue.new(capacity: 1)
+      payload = RactorBoundary.freeze_deep({
+        tool_class: tool_class_name.to_s,
+        args: args
+      })
+
+      job = RactorJob.new(
+        id:          SecureRandom.uuid.freeze,
+        type:        :tool,
+        payload:     payload,
+        reply_queue: reply_q
+      )
+
+      @work_q.push(job)
+      result = reply_q.pop
+
+      if result.is_a?(RactorJobError)
+        raise ToolError, "Tool '#{tool_class_name}' failed in Ractor: #{result.message}"
+      end
+
+      result
+    end
+
+    # Gracefully shut down the pool.
+    #
+    # Pushes one nil poison pill per worker so each exits its loop.
+    # Waits for all workers to terminate.
+    #
+    # @return [void]
+    def shutdown
+      return if @closed
+
+      @closed = true
+      # Push one nil poison pill per worker
+      @size.times { @work_q.push(nil) }
+      @workers.each { |w| w.join rescue nil }
+    end
+
+    private
+
+    def spawn_worker(work_q)
+      Ractor.new(work_q) do |q|
+        loop do
+          job = q.pop
+
+          # nil is the poison pill — exit cleanly
+          break if job.nil?
+
+          begin
+            tool_class = Object.const_get(job.payload[:tool_class])
+            tool       = tool_class.new
+            result     = tool.execute(**job.payload[:args].transform_keys(&:to_sym))
+            frozen_result = Ractor.make_shareable(result.frozen? ? result : result.dup.freeze)
+            job.reply_queue.push(frozen_result)
+          rescue => e
+            err = RobotLab::RactorJobError.new(
+              message:   e.message.freeze,
+              backtrace: (e.backtrace || []).map(&:freeze).freeze
+            )
+            job.reply_queue.push(err)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/robot/bus_messaging.rb

@@ -5,21 +5,16 @@ module RobotLab
     # Inter-robot communication via TypedBus.
     #
     # Expects the including class to provide:
-    #   @bus, @message_counter, @outbox, @message_handler,
-    #   @bus_subscriber_id, @bus_processing, @bus_queue, @name
-    #   and the `run` instance method
+    #   @bus, @bus_poller, @bus_poller_group, @message_counter,
+    #   @outbox, @message_handler, @bus_subscriber_id, @name
+    #   and the `run` instance method.
     #
-    # == Processing Guard
+    # == Delivery Serialization
     #
-    # TypedBus delivers messages in concurrent Async fibers. When a robot's
-    # +run()+ yields during HTTP I/O, the Async scheduler can switch to
-    # another fiber delivering a new bus message to the same robot. This
-    # would interleave user messages between +tool_use+ / +tool_result+
-    # pairs in +@chat+, corrupting Anthropic API message ordering.
-    #
-    # The processing guard serializes delivery handling: deliveries that
-    # arrive while the robot is already processing are queued and drained
-    # sequentially after the current one completes.
+    # 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.
     #
     module BusMessaging
       # Send a message to another robot via the bus.
@@ -84,19 +79,6 @@ module RobotLab
       # @param options [Hash] additional options passed to RobotLab.build
       # @return [Robot] the newly created robot
       #
-      # @example Spawn from a bus-less robot (bus and name created automatically)
-      #   bot  = RobotLab.build
-      #   bot2 = bot.spawn(system_prompt: "You are helpful.")
-      #
-      # @example Spawn a specialist from a message handler
-      #   on_message do |message|
-      #     specialist = spawn(
-      #       name: "fact_checker",
-      #       system_prompt: "You verify factual claims. Be concise."
-      #     )
-      #     specialist.send_message(to: name.to_sym, content: specialist.run(message.content).last_text_content)
-      #   end
-      #
       def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **options)
         ensure_bus
 
@@ -120,12 +102,6 @@ module RobotLab
       # @param bus [TypedBus::MessageBus, nil] bus to join (creates one if nil)
       # @return [self]
       #
-      # @example Join an existing bus
-      #   bot = RobotLab.build.with_bus(some_bus)
-      #
-      # @example Create a bus on demand
-      #   bot = RobotLab.build.with_bus
-      #
       def with_bus(bus = nil)
         return self if bus && @bus == bus
 
@@ -135,6 +111,22 @@ module RobotLab
         self
       end
 
+      # 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.
+      #
+      # @param poller [BusPoller] the network's shared poller
+      # @param group  [Symbol]    poller group for this robot (default: :default)
+      # @return [void]
+      #
+      def assign_bus_poller(poller, group: :default)
+        @private_bus_poller&.stop
+        @private_bus_poller = nil
+        @bus_poller       = poller
+        @bus_poller_group = group
+      end
+
       private
 
       # Create a bus if one doesn't exist and connect this robot to it
@@ -143,46 +135,42 @@ module RobotLab
       end
 
 
-      # Create a typed channel on the bus and subscribe to it
+      # Create a typed channel on the bus and subscribe to it.
+      # Auto-creates a private BusPoller if none has been assigned.
       def setup_bus_channel
+        unless @bus_poller
+          @private_bus_poller = BusPoller.new.start
+          @bus_poller         = @private_bus_poller
+          @bus_poller_group   = :default
+        end
+
         channel_name = @name.to_sym
         @bus.add_channel(channel_name, type: RobotMessage) unless @bus.channel?(channel_name)
-        @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| handle_incoming_delivery(delivery) }
+        @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| enqueue_delivery(delivery) }
       end
 
 
-      # Unsubscribe from the bus channel
+      # Unsubscribe from the bus channel and stop the private poller if any.
       def teardown_bus_channel
         channel_name = @name.to_sym
         @bus.unsubscribe(channel_name, @bus_subscriber_id) if @bus_subscriber_id
         @bus_subscriber_id = nil
-      end
 
+        @private_bus_poller&.stop
+        @private_bus_poller = nil
+        @bus_poller         = nil
+        @bus_poller_group   = :default
+      end
 
-      # Dispatch incoming bus delivery to handler.
-      #
-      # Uses a processing guard to serialize delivery handling. When
-      # the robot is already processing a delivery (e.g., inside a
-      # run() call that yields during HTTP I/O), new deliveries are
-      # queued and drained sequentially after the current one completes.
-      #
-      # Auto-ack when the handler takes 1 arg (message only);
-      # manual ack/nack when the handler takes 2 args (delivery, message).
-      def handle_incoming_delivery(delivery)
-        if @bus_processing
-          @bus_queue << delivery
-          return
-        end
 
-        process_delivery(delivery)
-        drain_bus_queue
+      # Enqueue a delivery to the robot's assigned poller.
+      def enqueue_delivery(delivery)
+        @bus_poller.enqueue(robot: self, delivery: delivery, group: @bus_poller_group)
       end
 
 
-      # Process a single delivery (called under the processing guard)
+      # Process a single delivery (called by BusPoller drain thread).
       def process_delivery(delivery)
-        @bus_processing = true
-
         message = delivery.message
 
         # Correlate replies with outbox entries
@@ -205,16 +193,6 @@ module RobotLab
       rescue => e
         delivery.nack! if delivery.pending?
         raise BusError, "Error handling bus message on robot '#{@name}': #{e.message}"
-      ensure
-        @bus_processing = false
-      end
-
-
-      # Drain queued deliveries sequentially
-      def drain_bus_queue
-        while (queued = @bus_queue.shift)
-          process_delivery(queued)
-        end
       end
 
 

data/lib/robot_lab/robot/history_search.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot
+    # Semantic search over a robot's conversation history.
+    #
+    # Scores each message in @chat.messages against the query using stemmed
+    # term-frequency cosine similarity (via the +classifier+ gem).  Returns the
+    # top-N messages ranked by relevance.
+    #
+    # Requires the optional 'classifier' gem (~> 2.3).
+    #
+    # @example
+    #   results = robot.search_history("quarterly revenue", limit: 3)
+    #   results.each do |r|
+    #     puts "[#{r.role}] (score #{r.score.round(3)}) #{r.text}"
+    #   end
+    module HistorySearch
+      # Minimum text length (characters) for a message to be considered.
+      MIN_SCORE_LENGTH = 20
+
+      # Value object returned by {#search_history}.
+      HistoryResult = Data.define(:text, :role, :score, :index)
+
+      # Search the robot's conversation history for messages relevant to +query+.
+      #
+      # @param query [String] natural-language search query
+      # @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
+      def search_history(query, limit: 5)
+        TextAnalysis.require_classifier!
+
+        query_vec = TextAnalysis.l2_normalize(query.word_hash)
+        return [] if query_vec.empty?
+
+        results = []
+
+        @chat.messages.each_with_index do |msg, idx|
+          text = extract_history_text(msg)
+          next if text.nil? || text.strip.length < MIN_SCORE_LENGTH
+
+          vec   = TextAnalysis.l2_normalize(text.word_hash)
+          score = TextAnalysis.cosine_similarity(query_vec, vec)
+          next if score.zero?
+
+          results << HistoryResult.new(text: text, role: msg.role, score: score, index: idx)
+        end
+
+        results.sort_by { |r| -r.score }.first(limit)
+      end
+
+      private
+
+      # Extract plain text from a message's content field.
+      #
+      # @param msg [Object] a RubyLLM message-like object
+      # @return [String, nil]
+      def extract_history_text(msg)
+        content = msg.content
+        case content
+        when String then content
+        when Array  then content.filter_map { |p| p[:text] || p["text"] }.join(" ")
+        else nil
+        end
+      end
+    end
+  end
+end