robot_lab 0.0.8 → 0.0.11

data/lib/robot_lab/delegation_future.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # A promise-like object returned by robot.delegate(async: true).
+  #
+  # The delegated task runs in a background thread. The caller can check
+  # whether the result is ready with +resolved?+ and block until it arrives
+  # with +value+ (or its alias +wait+).
+  #
+  # @example Fan-out to two specialists in parallel
+  #   f1 = manager.delegate(to: summarizer, task: "summarize ...", async: true)
+  #   f2 = manager.delegate(to: analyst,    task: "analyze ...",   async: true)
+  #
+  #   # Other work here while both run in parallel
+  #
+  #   summary  = f1.value           # blocks if not yet done
+  #   analysis = f2.value
+  #
+  # @example With a timeout
+  #   result = future.value(timeout: 10)   # raises DelegationTimeout if too slow
+  #
+  class DelegationFuture
+    # Raised when +value(timeout: N)+ expires before the result arrives.
+    class DelegationTimeout < Error; end
+
+    # @return [String] name of the robot that was delegated to
+    attr_reader :robot_name
+
+    # @return [String] name of the robot that created this future
+    attr_reader :delegated_by
+
+    # @param robot_name [String]
+    # @param delegated_by [String]
+    def initialize(robot_name:, delegated_by:)
+      @robot_name   = robot_name
+      @delegated_by = delegated_by
+      @mutex        = Mutex.new
+      @cv           = ConditionVariable.new
+      @result       = nil
+      @error        = nil
+      @resolved     = false
+    end
+
+    # True once the delegated task has completed (successfully or with an error).
+    #
+    # @return [Boolean]
+    def resolved?
+      @mutex.synchronize { @resolved }
+    end
+
+    # Block until the result is available and return it.
+    #
+    # @param timeout [Numeric, nil] maximum seconds to wait; nil means wait forever
+    # @return [RobotResult]
+    # @raise [DelegationTimeout] if +timeout+ is given and expires
+    # @raise [StandardError] re-raises any error thrown by the delegated task
+    def value(timeout: nil)
+      @mutex.synchronize do
+        unless @resolved
+          @cv.wait(@mutex, timeout)
+        end
+
+        unless @resolved
+          raise DelegationTimeout,
+                "Delegation to '#{@robot_name}' timed out after #{timeout}s"
+        end
+
+        raise @error if @error
+
+        @result
+      end
+    end
+    alias_method :wait, :value
+
+    # @api private — called by Robot#delegate from the worker thread
+    def resolve!(result)
+      @mutex.synchronize do
+        @result   = result
+        @resolved = true
+        @cv.broadcast
+      end
+    end
+
+    # @api private — called by Robot#delegate from the worker thread on error
+    def reject!(error)
+      @mutex.synchronize do
+        @error    = error
+        @resolved = true
+        @cv.broadcast
+      end
+    end
+  end
+end

data/lib/robot_lab/document_store.rb

@@ -0,0 +1,155 @@
+# 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/error.rb

@@ -35,4 +35,29 @@ module RobotLab
   # @example
   #   raise BusError, "No bus configured on this robot"
   class BusError < Error; end
+
+  # Raised when a robot's tool call loop exceeds the configured limit.
+  #
+  # @example
+  #   raise ToolLoopError, "Circuit breaker: 26 tool calls exceeded max_tool_rounds (25)"
+  class ToolLoopError < InferenceError; end
+
+  # Raised when a required optional gem dependency is not installed.
+  #
+  # @example
+  #   raise DependencyError, "Add gem 'classifier', '~> 2.3' to your Gemfile"
+  class DependencyError < ConfigurationError; end
+
+  # Raised when a value cannot be made Ractor-shareable before crossing
+  # a Ractor boundary (e.g., a live IO, Proc, or object with mutable state).
+  #
+  # @example
+  #   raise RactorBoundaryError, "Cannot freeze IO object"
+  class RactorBoundaryError < Error; end
+
+  # Raised when a tool fails during execution, including inside a Ractor worker.
+  #
+  # @example
+  #   raise ToolError, "Tool 'MyTool' failed: division by zero"
+  class ToolError < Error; end
 end

data/lib/robot_lab/history_compressor.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Compresses a robot's conversation history using TF-IDF relevance scoring.
+  #
+  # Old conversation turns are tiered against the most recent context:
+  # - High relevance (score >= keep_threshold)  → kept verbatim
+  # - Medium relevance (drop_threshold..keep_threshold) → summarized or dropped
+  # - Low relevance (score < drop_threshold)    → dropped
+  #
+  # System messages and tool call/result messages are always preserved.
+  # The most recent +recent_turns+ user+assistant pairs are also always kept.
+  #
+  # Requires the optional 'classifier' gem (~> 2.3).
+  #
+  # @example Basic usage from Robot
+  #   robot.compress_history(recent_turns: 3, keep_threshold: 0.6, drop_threshold: 0.2)
+  #
+  # @example With LLM summarizer (separate robot)
+  #   summarizer_robot = RobotLab.build(name: "summarizer", system_prompt: "Summarize concisely.")
+  #   robot.compress_history(
+  #     summarizer: ->(text) { summarizer_robot.run("One sentence: #{text}").reply }
+  #   )
+  class HistoryCompressor
+    # Minimum text length (characters) to score; shorter messages are kept as-is.
+    MIN_SCORE_LENGTH = 20
+
+    # Minimal duck-type for a summary replacement message compatible with
+    # RubyLLM::Chat's message array. Preserves the original message role so
+    # user/assistant turn ordering is maintained after compression.
+    SUMMARY_STRUCT = Struct.new(:role, :content, :tool_calls, :stop_reason) do
+      def text?      = true
+      def tool_use?  = false
+      def system?    = role == :system
+      def user?      = role == :user
+      def assistant? = role == :assistant
+    end
+
+    # @param messages [Array] full @chat.messages array
+    # @param recent_turns [Integer] number of user+assistant turn pairs to protect
+    # @param keep_threshold [Float] score >= this → keep verbatim
+    # @param drop_threshold [Float] score < this → drop
+    # @param summarizer [#call, nil] callable(text) -> String for medium-tier;
+    #                                nil means drop medium-tier
+    # @raise [ArgumentError] if keep_threshold <= drop_threshold
+    def initialize(messages:, recent_turns:, keep_threshold:, drop_threshold:, summarizer:)
+      if keep_threshold <= drop_threshold
+        raise ArgumentError,
+              "keep_threshold (#{keep_threshold}) must be greater than drop_threshold (#{drop_threshold})"
+      end
+
+      @messages        = messages
+      @recent_turns    = recent_turns
+      @keep_threshold  = keep_threshold
+      @drop_threshold  = drop_threshold
+      @summarizer      = summarizer
+    end
+
+    # Execute compression and return the new message array.
+    #
+    # @return [Array] compressed message array
+    def call
+      return @messages if @messages.empty?
+
+      # Classify each message index as pinned (always keep) or scorable
+      pinned_indices   = []
+      scorable_indices = []
+
+      @messages.each_with_index do |msg, idx|
+        if pinned_message?(msg)
+          pinned_indices << idx
+        else
+          scorable_indices << idx
+        end
+      end
+
+      # Nothing scorable, or everything fits inside the recent window: return as-is
+      return @messages if scorable_indices.empty?
+      return @messages if scorable_indices.size <= @recent_turns * 2
+
+      recent_count        = @recent_turns * 2
+      compressible        = scorable_indices[0..-(recent_count + 1)]
+      recent              = scorable_indices[-recent_count..]
+
+      return @messages if compressible.nil? || compressible.empty?
+
+      # Build reference vector from the recent window using stemmed term frequencies.
+      # Term frequencies (no IDF) are used because IDF on a topic-focused corpus
+      # would suppress the very terms that indicate relevance to that topic.
+      recent_texts = recent.filter_map { |i| extract_text(@messages[i]) }
+                           .reject { |t| t.strip.length < MIN_SCORE_LENGTH }
+
+      # No meaningful recent text → cannot score; return unchanged
+      return @messages if recent_texts.empty?
+
+      TextAnalysis.require_classifier!
+
+      recent_vectors = recent_texts.map { |t| TextAnalysis.l2_normalize(t.word_hash) }
+      reference      = mean_vector(recent_vectors)
+
+      # Decide action for each compressible message
+      actions = {}
+      compressible.each do |idx|
+        actions[idx] = score_action(reference, @messages[idx])
+      end
+
+      # Reconstruct the message array in original order
+      build_result(actions)
+    end
+
+    private
+
+    # Determine the action for one compressible message.
+    #
+    # @return [Symbol, String] :keep, :drop, or a summary String
+    def score_action(reference, msg)
+      text = extract_text(msg)
+
+      # Too short to score reliably → keep
+      return :keep if text.nil? || text.strip.length < MIN_SCORE_LENGTH
+
+      vec   = TextAnalysis.l2_normalize(text.word_hash)
+      score = TextAnalysis.cosine_similarity(vec, reference)
+
+      if score >= @keep_threshold
+        :keep
+      elsif score < @drop_threshold
+        :drop
+      elsif @summarizer
+        summary = @summarizer.call(text).to_s.strip
+        summary.empty? ? :drop : summary
+      else
+        :drop
+      end
+    end
+
+    # Build the final message array from the decided actions.
+    def build_result(actions)
+      result = []
+
+      @messages.each_with_index do |msg, idx|
+        action = actions[idx]
+
+        if action.nil?
+          # Pinned or recent: always include
+          result << msg
+        elsif action == :keep
+          result << msg
+        elsif action == :drop
+          # Omit entirely
+        else
+          # action is a summary String; preserve original role to keep turn ordering
+          result << SUMMARY_STRUCT.new(msg.role, action, nil, :stop)
+        end
+      end
+
+      result
+    end
+
+    # True if a message should never be scored or removed.
+    #
+    # System messages and tool-related messages are always pinned.
+    # Assistant messages with no text content (tool call dispatchers)
+    # are also pinned to avoid breaking tool_use/tool_result pairing.
+    def pinned_message?(msg)
+      role = msg.role
+
+      return true if role == :system
+      return true if role == :tool || role == :tool_result
+
+      # Assistant tool-call dispatcher: content is nil or blank
+      if role == :assistant
+        text = extract_text(msg)
+        return true if text.nil? || text.strip.empty?
+      end
+
+      false
+    end
+
+    # Extract plain text from a message's content field.
+    #
+    # @return [String, nil]
+    def extract_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
+
+    # Element-wise mean of a list of sparse vectors.
+    #
+    # @param vectors [Array<Hash{Symbol => Float}>]
+    # @return [Hash{Symbol => Float}]
+    def mean_vector(vectors)
+      return {} if vectors.empty?
+
+      sum = Hash.new(0.0)
+      vectors.each { |v| v.each { |k, val| sum[k] += val } }
+      n = vectors.size.to_f
+      sum.transform_values { |v| v / n }
+    end
+  end
+end

data/lib/robot_lab/mcp/client.rb

@@ -18,13 +18,15 @@ module RobotLab
       #   @return [Server] the MCP server configuration
       # @!attribute [r] connected
       #   @return [Boolean] whether currently connected
-      attr_reader :server, :connected
+      attr_reader :server, :connected, :transport
 
       # Creates a new MCP Client instance.
       #
       # @param server_or_config [Server, Hash] the server or configuration hash
+      # @param poller [MCP::ConnectionPoller, nil] optional shared IO.select poller
+      #   for multiplexing multiple stdio transports (opt-in, default nil = per-client blocking)
       # @raise [ArgumentError] if config is invalid
-      def initialize(server_or_config)
+      def initialize(server_or_config, poller: nil)
         @server = case server_or_config
                   when Server
                     server_or_config
@@ -33,9 +35,10 @@ module RobotLab
                   else
                     raise ArgumentError, "Invalid server config"
                   end
-        @connected = false
-        @transport = nil
+        @connected  = false
+        @transport  = nil
         @request_id = 0
+        @poller     = poller
       end
 
       # Connect to the MCP server
@@ -49,6 +52,9 @@ module RobotLab
         @transport.connect if @transport.respond_to?(:connect)
         @connected = true
 
+        # Register with shared poller after the transport is connected
+        @poller.register(self) if @poller
+
         self
       rescue StandardError => e
         RobotLab.config.logger.warn("MCP connection failed for #{@server.name}: #{e.message}")
@@ -63,6 +69,7 @@ module RobotLab
       def disconnect
         return self unless @connected
 
+        @poller.unregister(self) if @poller
         @transport.close if @transport.respond_to?(:close)
         @connected = false
         @transport = nil
@@ -162,15 +169,17 @@ module RobotLab
       end
 
       def create_transport
+        config = @server.transport.merge(timeout: @server.timeout)
+
         case @server.transport_type
         when "stdio"
-          Transports::Stdio.new(@server.transport)
+          Transports::Stdio.new(config)
         when "ws", "websocket"
-          Transports::WebSocket.new(@server.transport)
+          Transports::WebSocket.new(config)
         when "sse"
-          Transports::SSE.new(@server.transport)
+          Transports::SSE.new(config)
         when "streamable-http", "http"
-          Transports::StreamableHTTP.new(@server.transport)
+          Transports::StreamableHTTP.new(config)
         else
           raise MCPError, "Unsupported transport type: #{@server.transport_type}"
         end
@@ -186,7 +195,12 @@ module RobotLab
         }
         message[:params] = params if params
 
-        response = @transport.send_request(message)
+        response = if @poller && @transport.is_a?(Transports::Stdio)
+                     @poller.send_request(self, message, timeout: @server.timeout)
+                   else
+                     @transport.send_request(message)
+                   end
+
         parse_response(response)
       end