robot_lab 0.1.0 → 0.2.1

data/lib/generators/robot_lab/templates/routing_robot.rb.tt

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-# <%= class_name %> Routing Robot
-#
-# <%= robot_description %>
-#
-# This robot classifies requests and activates optional tasks in a Network.
-# Use it as the first task in a network with optional downstream tasks:
-#
-#   classifier = <%= class_name %>Robot.build
-#   billing    = BillingRobot.build
-#   technical  = TechnicalRobot.build
-#
-#   network = RobotLab.create_network(name: "support") do
-#     task :classifier, classifier, depends_on: :none
-#     task :billing,    billing,    depends_on: :optional
-#     task :technical,  technical,  depends_on: :optional
-#   end
-#
-#   result = network.run(message: "I was charged twice")
-#
-class <%= class_name %>Robot < RobotLab::Robot
-  SYSTEM_PROMPT = <<~PROMPT
-    You are a routing robot that classifies user requests.
-
-    Analyze the user's request and respond with ONLY the category name.
-    Valid categories: billing, technical, general
-  PROMPT
-
-  def self.build(**options)
-    new(
-      name: "<%= file_name %>",
-      description: "<%= robot_description %>",
-      system_prompt: SYSTEM_PROMPT,
-      **options
-    )
-  end
-
-  # Override call to inspect classification output and activate optional tasks.
-  def call(result)
-    context = extract_run_context(result)
-    message = context.delete(:message)
-
-    robot_result = run(message, **context)
-
-    new_result = result
-      .with_context(@name.to_sym, robot_result)
-      .continue(robot_result)
-
-    category = robot_result.last_text_content.to_s.strip.downcase
-
-    # Route based on classification — customize these patterns
-    case category
-    when /billing/  then new_result.activate(:billing)
-    when /technical/ then new_result.activate(:technical)
-    else new_result.activate(:general)
-    end
-  end
-end

data/lib/generators/robot_lab/templates/thread_model.rb.tt

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# RobotLab Thread Model
-#
-# Stores conversation threads for history persistence.
-#
-class RobotLabThread < ApplicationRecord
-  has_many :results,
-           class_name: "RobotLabResult",
-           foreign_key: :session_id,
-           primary_key: :session_id,
-           dependent: :destroy
-
-  validates :session_id, presence: true, uniqueness: true
-
-  # Find or create a thread by ID
-  #
-  # @param id [String] Thread ID
-  # @return [RobotLabThread]
-  #
-  def self.find_or_create_by_session_id(id)
-    find_or_create_by(session_id: id)
-  end
-
-  # Get the last result for this thread
-  #
-  # @return [RobotLabResult, nil]
-  #
-  def last_result
-    results.order(sequence_number: :desc).first
-  end
-
-  # Get message count for this thread
-  #
-  # @return [Integer]
-  #
-  def message_count
-    results.count
-  end
-end

data/lib/robot_lab/document_store.rb

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-require "fastembed"
-
-module RobotLab
-  # Embedding-based document store for semantic search over arbitrary text.
-  #
-  # Documents are embedded using {https://github.com/khasinski/fastembed-rb fastembed}
-  # (BAAI/bge-small-en-v1.5 by default) and stored in memory.  Queries are
-  # embedded the same way, then compared by cosine similarity to find the
-  # closest documents.
-  #
-  # The embedding model is initialised lazily on first use — the ONNX model
-  # file is downloaded on that first call (cached locally afterwards).
-  #
-  # @example
-  #   store = RobotLab::DocumentStore.new
-  #   store.store(:q4_report, "Q4 revenue came in at $4.2M, up 18% YoY…")
-  #   store.store(:q3_report, "Q3 showed 15% growth, driven by APAC…")
-  #
-  #   results = store.search("revenue growth", limit: 2)
-  #   results.each { |r| puts "#{r[:key]} (#{r[:score].round(3)}): #{r[:text][0..60]}" }
-  #
-  # @example Via Memory
-  #   memory.store_document(:readme, File.read("README.md"))
-  #   memory.search_documents("how to configure redis", limit: 3)
-  #
-  class DocumentStore
-    # Default embedding model used when none is specified.
-    DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
-
-    # @param model_name [String] fastembed model name (default: BAAI/bge-small-en-v1.5)
-    def initialize(model_name: DEFAULT_MODEL)
-      @model_name = model_name
-      @documents  = {}  # key (Symbol) => { text: String, vector: Array<Float> }
-      @mutex      = Mutex.new
-      @model      = nil  # lazy: initialised on first embed call
-    end
-
-    # Embed +text+ and store it under +key+.
-    #
-    # If a document already exists under +key+ it is replaced.
-    #
-    # @param key [Symbol, String] identifier for this document
-    # @param text [String] the document text to embed and store
-    # @return [self]
-    def store(key, text)
-      key    = key.to_sym
-      vector = passage_vector(text)
-      @mutex.synchronize { @documents[key] = { text: text, vector: vector } }
-      self
-    end
-
-    # Search for documents semantically similar to +query+.
-    #
-    # @param query [String] natural-language search query
-    # @param limit [Integer] maximum number of results (default 5)
-    # @return [Array<Hash>] results sorted by score descending.
-    #   Each hash contains +:key+, +:text+, and +:score+ (Float 0.0..1.0).
-    def search(query, limit: 5)
-      return [] if empty?
-
-      query_vec = query_vector(query)
-      results   = []
-
-      @mutex.synchronize do
-        @documents.each do |key, doc|
-          score = cosine_similarity(query_vec, doc[:vector])
-          results << { key: key, text: doc[:text], score: score }
-        end
-      end
-
-      results.sort_by { |r| -r[:score] }.first(limit)
-    end
-
-    # Number of stored documents.
-    #
-    # @return [Integer]
-    def size
-      @mutex.synchronize { @documents.size }
-    end
-
-    # Keys of all stored documents.
-    #
-    # @return [Array<Symbol>]
-    def keys
-      @mutex.synchronize { @documents.keys }
-    end
-
-    # Whether the store contains no documents.
-    #
-    # @return [Boolean]
-    def empty?
-      @mutex.synchronize { @documents.empty? }
-    end
-
-    # Remove the document stored under +key+.
-    #
-    # @param key [Symbol, String]
-    # @return [self]
-    def delete(key)
-      @mutex.synchronize { @documents.delete(key.to_sym) }
-      self
-    end
-
-    # Remove all stored documents.
-    #
-    # @return [self]
-    def clear
-      @mutex.synchronize { @documents.clear }
-      self
-    end
-
-    private
-
-    # Return (or lazily create) the fastembed model instance.
-    def model
-      @model ||= Fastembed::TextEmbedding.new(model_name: @model_name, show_progress: false)
-    end
-
-    # Embed a single passage string.
-    def passage_vector(text)
-      model.passage_embed([text]).to_a.first
-    end
-
-    # Embed a single query string.
-    def query_vector(text)
-      model.query_embed([text]).to_a.first
-    end
-
-    # Cosine similarity between two dense float vectors.
-    #
-    # Returns 0.0 for nil, empty, or mismatched-length vectors.
-    def cosine_similarity(vec_a, vec_b)
-      return 0.0 unless vec_a && vec_b
-      return 0.0 if vec_a.empty? || vec_b.empty?
-      return 0.0 if vec_a.length != vec_b.length
-
-      dot    = 0.0
-      norm_a = 0.0
-      norm_b = 0.0
-
-      vec_a.each_with_index do |a, i|
-        b       = vec_b[i]
-        dot    += a * b
-        norm_a += a * a
-        norm_b += b * b
-      end
-
-      return 0.0 if norm_a.zero? || norm_b.zero?
-
-      dot / (Math.sqrt(norm_a) * Math.sqrt(norm_b))
-    end
-  end
-end

data/lib/robot_lab/ractor_boundary.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  # Utility for making values safe to pass across Ractor boundaries.
-  #
-  # Recursively freezes Hash and Array structures. Raises RactorBoundaryError
-  # if a value cannot be made Ractor-shareable (e.g. a live IO or Proc).
-  #
-  # @example
-  #   safe = RactorBoundary.freeze_deep({ model: "sonnet", args: { x: 1 } })
-  #   Ractor.shareable?(safe)  #=> true
-  #
-  module RactorBoundary
-    # Recursively freeze an object for safe Ractor boundary crossing.
-    #
-    # @param obj [Object] the value to freeze
-    # @return [Object] a frozen, Ractor-shareable copy
-    # @raise [RactorBoundaryError] if the value cannot be made shareable
-    def self.freeze_deep(obj)
-      return obj if Ractor.shareable?(obj)
-
-      result = case obj
-               when Hash
-                 obj.transform_keys { |k| freeze_deep(k) }
-                    .transform_values { |v| freeze_deep(v) }
-               when Array
-                 obj.map { |v| freeze_deep(v) }
-               else
-                 begin
-                   obj.dup
-                 rescue TypeError
-                   raise RactorBoundaryError,
-                         "Cannot make #{obj.class} Ractor-shareable: dup not supported"
-                 end
-               end
-
-      Ractor.make_shareable(result)
-    rescue Ractor::IsolationError, Ractor::Error => e
-      raise RactorBoundaryError, "Cannot make value Ractor-shareable: #{e.message}"
-    end
-  end
-end

data/lib/robot_lab/ractor_job.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module RobotLab
-  # Carrier for work crossing a Ractor boundary.
-  #
-  # All fields must be Ractor-shareable (frozen Data, frozen String,
-  # frozen Hash, or a RactorQueue). Build with RactorBoundary.freeze_deep
-  # on the payload before constructing.
-  #
-  # @example
-  #   job = RactorJob.new(
-  #     id:          SecureRandom.uuid.freeze,
-  #     type:        :tool,
-  #     payload:     RactorBoundary.freeze_deep({ tool_class: "MyTool", args: { x: 1 } }),
-  #     reply_queue: RactorQueue.new(capacity: 1)
-  #   )
-  RactorJob = Data.define(:id, :type, :payload, :reply_queue)
-
-  # Frozen error representation for exceptions raised inside a Ractor worker.
-  # Serialized at the Ractor boundary and re-raised on the thread side.
-  #
-  # @example
-  #   err = RactorJobError.new(message: e.message.freeze, backtrace: e.backtrace.freeze)
-  RactorJobError = Data.define(:message, :backtrace)
-
-  # Carries everything needed to reconstruct a Robot inside a Ractor.
-  # All fields must be frozen strings, symbols, or hashes.
-  #
-  # @example
-  #   spec = RobotSpec.new(
-  #     name:          "analyst",
-  #     template:      :analyst,
-  #     system_prompt: nil,
-  #     config_hash:   { model: "claude-sonnet-4" }.freeze
-  #   )
-  RobotSpec = Data.define(:name, :template, :system_prompt, :config_hash)
-end

data/lib/robot_lab/ractor_memory_proxy.rb

@@ -1,85 +0,0 @@
-# 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

@@ -1,154 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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