robot_lab 0.0.9 → 0.0.11

data/lib/robot_lab/robot.rb

@@ -3,6 +3,7 @@
 require_relative 'robot/template_rendering'
 require_relative 'robot/mcp_management'
 require_relative 'robot/bus_messaging'
+require_relative 'robot/history_search'
 
 module RobotLab
   # LLM-powered robot built on RubyLLM::Agent
@@ -41,6 +42,7 @@ module RobotLab
     include Robot::TemplateRendering
     include Robot::MCPManagement
     include Robot::BusMessaging
+    include Robot::HistorySearch
 
     # @!attribute [r] name
     #   @return [String] the unique identifier for the robot
@@ -66,7 +68,8 @@ module RobotLab
 
     attr_reader :name, :description, :template, :system_prompt,
                 :local_tools, :mcp_clients, :mcp_tools, :memory,
-                :bus, :outbox, :config, :skills, :provider
+                :bus, :outbox, :config, :skills, :provider,
+                :total_input_tokens, :total_output_tokens, :learnings
 
     # @!attribute [r] mcp_config
     #   @return [Symbol, Array] build-time MCP configuration (raw, unresolved)
@@ -125,6 +128,9 @@ module RobotLab
       presence_penalty: nil,
       frequency_penalty: nil,
       stop: nil,
+      max_tool_rounds: nil,
+      token_budget: nil,
+      mcp_discovery: false,
       config: nil
     )
       @name = name.to_s
@@ -136,6 +142,7 @@ module RobotLab
       @local_tools = Array(local_tools)
       @skills = skills ? Array(skills).map(&:to_sym) : nil
       @expanded_skills = nil
+      @mcp_discovery = mcp_discovery
 
       # Build RunConfig from explicit kwargs, merged on top of passed-in config.
       # Explicit constructor kwargs always override the shared config.
@@ -144,7 +151,8 @@ module RobotLab
         max_tokens: max_tokens, presence_penalty: presence_penalty,
         frequency_penalty: frequency_penalty, stop: stop,
         on_tool_call: on_tool_call, on_tool_result: on_tool_result,
-        on_content: on_content, bus: bus, enable_cache: enable_cache
+        on_content: on_content, bus: bus, enable_cache: enable_cache,
+        max_tool_rounds: max_tool_rounds, token_budget: token_budget
       }.compact
 
       # Only include mcp/tools if explicitly set (not the default :none sentinel)
@@ -170,17 +178,29 @@ module RobotLab
       @mcp_initialized = false
 
       # Bus state (optional inter-robot communication)
-      @bus = @config.bus
-      @message_counter = 0
-      @outbox = {}
-      @message_handler = nil
-      @bus_processing = false
-      @bus_queue = []
+      @bus               = @config.bus
+      @message_counter   = 0
+      @outbox            = {}
+      @message_handler   = nil
+      @bus_poller        = nil
+      @private_bus_poller = nil
+      @bus_poller_group  = :default
+
+      # Token tracking
+      @total_input_tokens = 0
+      @total_output_tokens = 0
+
+      # Learning accumulation
+      @learnings = []
 
       # Inherent memory (used when standalone, not in a network)
       cache_enabled = @config.key?(:enable_cache) ? @config.enable_cache : true
       @memory = Memory.new(enable_cache: cache_enabled)
 
+      # Restore persisted learnings from inherent memory if present
+      persisted = @memory.get(:learnings)
+      @learnings = Array(persisted) if persisted
+
       # Ensure config is loaded (triggers PM setup, RubyLLM config, etc.)
       config = RobotLab.config
 
@@ -301,6 +321,13 @@ module RobotLab
         resolved_mcp = resolve_mcp_hierarchy(mcp, network: network, network_config: network_config)
         resolved_tools = resolve_tools_hierarchy(tools, network: network, network_config: network_config)
 
+        # Filter MCP servers by semantic relevance when discovery is enabled.
+        # Only applies on the first run (before @mcp_initialized) so connections
+        # are not torn down mid-conversation.
+        if @mcp_discovery && !@mcp_initialized && resolved_mcp.is_a?(Array)
+          resolved_mcp = MCP::ServerDiscovery.select(message.to_s, from: resolved_mcp)
+        end
+
         # Initialize or update MCP clients based on resolved config
         ensure_mcp_clients(resolved_mcp)
 
@@ -314,13 +341,29 @@ module RobotLab
         run_context = kwargs.except(:with)
         rerender_template(run_context) if @template && run_context.any?
 
+        # Prepend accumulated learnings to the user message
+        effective_message = inject_learnings(message)
+
+        # Install circuit breaker for this run if max_tool_rounds is configured
+        install_circuit_breaker if @config.max_tool_rounds
+
         # Delegate to Agent's ask (which calls @chat.ask)
         ask_kwargs = kwargs.slice(:with)
         streaming = effective_streaming_block(block)
-        response = ask(message, **ask_kwargs, &streaming)
+        response = ask(effective_message, **ask_kwargs, &streaming)
+
+        result = build_result(response, run_memory)
 
-        build_result(response, run_memory)
+        # Enforce token budget if configured
+        budget = @config.token_budget
+        if 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
+
+        result
       ensure
+        restore_tool_call_callback if @config.max_tool_rounds
         run_memory.current_writer = previous_writer
       end
     end
@@ -482,6 +525,89 @@ module RobotLab
       self
     end
 
+    # Compress conversation history using TF-IDF relevance scoring.
+    #
+    # Old 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+ pairs are also always kept verbatim.
+    #
+    # Requires the optional 'classifier' gem (~> 2.3).
+    # Raises +DependencyError+ if not installed.
+    #
+    # @param recent_turns [Integer] turn pairs to protect at the end (default 3)
+    # @param keep_threshold [Float] cosine score >= this → keep verbatim (default 0.6)
+    # @param drop_threshold [Float] cosine score < this → drop (default 0.2)
+    # @param summarizer [#call, nil] callable(text) -> String for medium-tier;
+    #                                nil drops medium-tier instead of summarizing
+    # @return [self]
+    def compress_history(recent_turns: 3, keep_threshold: 0.6, drop_threshold: 0.2, summarizer: nil)
+      compressed = HistoryCompressor.new(
+        messages:       @chat.messages,
+        recent_turns:   recent_turns,
+        keep_threshold: keep_threshold,
+        drop_threshold: drop_threshold,
+        summarizer:     summarizer
+      ).call
+      replace_messages(compressed)
+    end
+
+    # Delegate a task to another robot, synchronously or asynchronously.
+    #
+    # **Synchronous** (default, +async: false+): blocks until the delegatee
+    # finishes and returns a +RobotResult+ annotated with +delegated_by+,
+    # +duration+, and token counts.
+    #
+    # **Asynchronous** (+async: true+): starts the delegatee in a background
+    # thread and returns a +DelegationFuture+ immediately. Call +future.value+
+    # to block for the result, or +future.resolved?+ to poll.
+    #
+    # @example Synchronous
+    #   result = manager.delegate(to: analyst, task: "What are the risks?")
+    #   puts result.reply          # analyst's answer
+    #   puts result.delegated_by   # => "manager"
+    #   puts result.duration       # => 1.43 (seconds)
+    #
+    # @example Async fan-out
+    #   f1 = manager.delegate(to: summarizer, task: "summarize ...", async: true)
+    #   f2 = manager.delegate(to: analyst,    task: "analyze ...",   async: true)
+    #   summary  = f1.value          # blocks if not yet done
+    #   analysis = f2.value(timeout: 30)
+    #
+    # @param to [Robot] the robot to delegate to
+    # @param task [String] the message to send
+    # @param async [Boolean] when true, returns a DelegationFuture immediately
+    # @param kwargs [Hash] additional keyword args forwarded to Robot#run
+    # @return [RobotResult] when async: false
+    # @return [DelegationFuture] when async: true
+    def delegate(to:, task:, async: false, **kwargs)
+      if async
+        future = DelegationFuture.new(robot_name: to.name, delegated_by: @name)
+        delegator_name = @name
+
+        Thread.new do
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          result = to.run(task, **kwargs)
+          result.duration     = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          result.delegated_by = delegator_name
+          future.resolve!(result)
+        rescue => e
+          future.reject!(e)
+        end
+
+        future
+      else
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = to.run(task, **kwargs)
+        result.duration     = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+        result.delegated_by = @name
+        result
+      end
+    end
+
     # Return the provider for this robot's chat.
     # Useful for displaying model/provider info without reaching
     # into chat internals.
@@ -503,6 +629,44 @@ module RobotLab
     end
 
 
+    # Add a learning to this robot's accumulation store.
+    #
+    # Deduplicates by bidirectional substring matching: a new learning is
+    # skipped if it is already contained within an existing learning, or
+    # an existing learning is contained within the new one (the new one
+    # wins and replaces the weaker entry).
+    #
+    # Learnings are persisted to the robot's inherent memory under :learnings.
+    #
+    # @param text [String] the insight to record
+    # @return [self]
+    def learn(text)
+      text = text.to_s.strip
+      return self if text.empty?
+
+      # Remove any existing learning that is a substring of the new one
+      @learnings.reject! { |existing| text.include?(existing) }
+
+      # Skip if any existing learning already covers the new one
+      unless @learnings.any? { |existing| existing.include?(text) }
+        @learnings << text
+        @memory.set(:learnings, @learnings.dup)
+      end
+
+      self
+    end
+
+
+    # Reset cumulative token counters to zero.
+    #
+    # @return [self]
+    def reset_token_totals
+      @total_input_tokens = 0
+      @total_output_tokens = 0
+      self
+    end
+
+
     # Converts the robot to a hash representation
     #
     # @return [Hash]
@@ -578,12 +742,28 @@ module RobotLab
 
       tool_calls = response.respond_to?(:tool_calls) ? (response.tool_calls || []) : []
 
+      # Extract token usage from the response
+      input_toks = 0
+      output_toks = 0
+      if response.respond_to?(:tokens) && response.tokens
+        input_toks = response.tokens.input.to_i
+        output_toks = response.tokens.output.to_i
+      elsif response.respond_to?(:input_tokens)
+        input_toks = response.input_tokens.to_i
+        output_toks = response.respond_to?(:output_tokens) ? response.output_tokens.to_i : 0
+      end
+
+      @total_input_tokens += input_toks
+      @total_output_tokens += output_toks
+
       RobotResult.new(
         robot_name: @name,
         output: output,
         tool_calls: normalize_tool_calls(tool_calls),
         stop_reason: response.respond_to?(:stop_reason) ? response.stop_reason : nil,
-        raw: response
+        raw: response,
+        input_tokens: input_toks,
+        output_tokens: output_toks
       )
     end
 
@@ -629,5 +809,42 @@ module RobotLab
 
       ToolConfig.filter_tools(available, allowed_names: allowed_names)
     end
+
+
+    # Prepend accumulated learnings to a user message when learnings exist.
+    def inject_learnings(message)
+      return message if @learnings.empty? || message.nil?
+
+      learning_block = "LEARNINGS FROM PREVIOUS RUNS:\n" +
+                       @learnings.map { |l| "- #{l}" }.join("\n") +
+                       "\n\n"
+      "#{learning_block}#{message}"
+    end
+
+
+    # Install a per-run circuit breaker on the chat's on_tool_call hook.
+    # Raises ToolLoopError if tool calls exceed @config.max_tool_rounds.
+    # Stores the previous callback so restore_tool_call_callback can undo it.
+    def install_circuit_breaker
+      @circuit_breaker_call_count = 0
+      max = @config.max_tool_rounds
+      original = @on_tool_call
+
+      @chat.on_tool_call do |tool_call|
+        @circuit_breaker_call_count += 1
+        if @circuit_breaker_call_count > max
+          raise ToolLoopError,
+                "Circuit breaker triggered: #{@circuit_breaker_call_count} tool calls exceeded " \
+                "max_tool_rounds (#{max})"
+        end
+        original&.call(tool_call)
+      end
+    end
+
+
+    # Restore the original on_tool_call callback after a circuit-breaker run.
+    def restore_tool_call_callback
+      @chat.on_tool_call(&@on_tool_call)
+    end
   end
 end

data/lib/robot_lab/robot_result.rb

@@ -28,17 +28,24 @@ module RobotLab
     #   @return [String] unique identifier for this result
     # @!attribute [r] stop_reason
     #   @return [String, nil] reason execution stopped
-    attr_reader :robot_name, :output, :tool_calls, :created_at, :id, :stop_reason
+    # @!attribute [r] input_tokens
+    #   @return [Integer] input tokens consumed by this run
+    # @!attribute [r] output_tokens
+    #   @return [Integer] output tokens generated by this run
+    attr_reader :robot_name, :output, :tool_calls, :created_at, :id, :stop_reason,
+                :input_tokens, :output_tokens
 
     # @!attribute [rw] duration
     #   @return [Float, nil] elapsed seconds for this run
+    # @!attribute [rw] delegated_by
+    #   @return [String, nil] name of the robot that delegated this task
     # @!attribute [rw] prompt
     #   @return [Array<Message>, nil] the prompt messages used (debug)
     # @!attribute [rw] history
     #   @return [Array<Message>, nil] the history used (debug)
     # @!attribute [rw] raw
     #   @return [Object, nil] the raw LLM response (debug)
-    attr_accessor :duration, :prompt, :history, :raw
+    attr_accessor :duration, :delegated_by, :prompt, :history, :raw
 
     # Creates a new RobotResult instance.
     #
@@ -51,6 +58,8 @@ module RobotLab
     # @param history [Array<Message>, nil] history messages (debug)
     # @param raw [Object, nil] raw LLM response (debug)
     # @param stop_reason [String, nil] reason for stopping
+    # @param input_tokens [Integer] input tokens consumed (default 0)
+    # @param output_tokens [Integer] output tokens generated (default 0)
     def initialize(
       robot_name:,
       output:,
@@ -60,7 +69,9 @@ module RobotLab
       prompt: nil,
       history: nil,
       raw: nil,
-      stop_reason: nil
+      stop_reason: nil,
+      input_tokens: 0,
+      output_tokens: 0
     )
       @robot_name = robot_name
       @output = normalize_messages(output)
@@ -71,6 +82,8 @@ module RobotLab
       @history = history
       @raw = raw
       @stop_reason = stop_reason
+      @input_tokens = input_tokens.to_i
+      @output_tokens = output_tokens.to_i
     end
 
     # Generate a checksum for deduplication
@@ -98,12 +111,16 @@ module RobotLab
     def export
       {
         robot_name: robot_name,
+        delegated_by: delegated_by,
         output: output.map(&:to_h),
         tool_calls: tool_calls.map(&:to_h),
         created_at: created_at.iso8601,
         id: id,
         checksum: checksum,
-        stop_reason: stop_reason
+        stop_reason: stop_reason,
+        duration: duration,
+        input_tokens: input_tokens.positive? ? input_tokens : nil,
+        output_tokens: output_tokens.positive? ? output_tokens : nil
       }.compact
     end
 
@@ -173,7 +190,9 @@ module RobotLab
         prompt: hash[:prompt]&.map { |m| Message.from_hash(m) },
         history: hash[:history]&.map { |m| Message.from_hash(m) },
         raw: hash[:raw],
-        stop_reason: hash[:stop_reason]
+        stop_reason: hash[:stop_reason],
+        input_tokens: hash[:input_tokens] || 0,
+        output_tokens: hash[:output_tokens] || 0
       )
     end
 

data/lib/robot_lab/run_config.rb

@@ -41,7 +41,7 @@ module RobotLab
     CALLBACK_FIELDS = %i[on_tool_call on_tool_result on_content].freeze
 
     # Infrastructure fields
-    INFRA_FIELDS = %i[bus enable_cache].freeze
+    INFRA_FIELDS = %i[bus enable_cache max_tool_rounds token_budget ractor_pool_size].freeze
 
     # All recognized fields
     FIELDS = (LLM_FIELDS + TOOL_FIELDS + CALLBACK_FIELDS + INFRA_FIELDS).freeze

data/lib/robot_lab/text_analysis.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Shared TF-IDF text analysis utilities.
+  #
+  # Wraps +Classifier::TFIDF+ from the optional 'classifier' gem (~> 2.3).
+  # Call +require_classifier!+ before any analysis method to get a descriptive
+  # error if the gem is missing rather than a bare NameError.
+  #
+  # Vectors returned by +transform+ are L2-normalized, so cosine similarity
+  # equals the dot product of two vectors — no magnitude division needed.
+  module TextAnalysis
+    # Attempt to load the classifier gem.
+    #
+    # @raise [DependencyError] if the gem is not installed
+    def self.require_classifier!
+      load_classifier_gem
+    rescue LoadError
+      raise DependencyError,
+            "The 'classifier' gem is required for text analysis features. " \
+            "Add it to your Gemfile: gem 'classifier', '~> 2.3'"
+    end
+
+    # Load the classifier gem. Extracted for testability.
+    #
+    # @api private
+    def self.load_classifier_gem
+      require "classifier"
+    end
+
+    # Fit a TF-IDF model on a corpus of strings.
+    #
+    # @param corpus [Array<String>] non-empty array of document strings
+    # @return [Classifier::TFIDF] fitted model
+    def self.fit(corpus)
+      model = Classifier::TFIDF.new(min_df: 1)
+      model.fit(corpus)
+      model
+    end
+
+    # Transform a string into an L2-normalized TF-IDF term vector.
+    #
+    # @param model [Classifier::TFIDF] a fitted model
+    # @param text [String]
+    # @return [Hash{Symbol => Float}] sparse term vector; empty if no known terms
+    def self.transform(model, text)
+      model.transform(text.to_s) || {}
+    end
+
+    # Cosine similarity between two L2-normalized sparse vectors.
+    #
+    # Since +Classifier::TFIDF+ returns L2-normalized vectors, this is just
+    # a dot product. Result is clamped to [0.0, 1.0] to absorb float noise.
+    #
+    # @param vec_a [Hash{Symbol => Float}]
+    # @param vec_b [Hash{Symbol => Float}]
+    # @return [Float] in [0.0, 1.0]
+    def self.cosine_similarity(vec_a, vec_b)
+      return 0.0 if vec_a.empty? || vec_b.empty?
+
+      [dot(vec_a, vec_b), 1.0].min
+    end
+
+    # Dot product of two sparse vectors (shared keys only).
+    #
+    # @param vec_a [Hash{Symbol => Float}]
+    # @param vec_b [Hash{Symbol => Float}]
+    # @return [Float]
+    def self.dot(vec_a, vec_b)
+      (vec_a.keys & vec_b.keys).sum { |k| vec_a[k] * vec_b[k] }.to_f
+    end
+
+    # L2-normalize a sparse vector.
+    #
+    # @param vec [Hash{Symbol => Numeric}]
+    # @return [Hash{Symbol => Float}] normalized vector; {} if magnitude is zero
+    def self.l2_normalize(vec)
+      magnitude = Math.sqrt(vec.values.sum { |v| v * v }.to_f)
+      return {} if magnitude.zero?
+
+      vec.transform_values { |v| v.to_f / magnitude }
+    end
+
+    # Cosine similarity between two texts using stemmed term-frequency vectors.
+    #
+    # Uses +String#word_hash+ from the classifier gem (stems, removes stopwords)
+    # and L2-normalized term frequencies. Unlike TF-IDF, this does not require
+    # a reference corpus, making it reliable for direct 2-text comparison.
+    # Returns 0.0 when either text is too short to produce a term vector.
+    #
+    # @param text_a [String]
+    # @param text_b [String]
+    # @return [Float] in [0.0, 1.0]
+    def self.tf_cosine_similarity(text_a, text_b)
+      require_classifier!
+
+      vec_a = l2_normalize(text_a.word_hash)
+      vec_b = l2_normalize(text_b.word_hash)
+
+      cosine_similarity(vec_a, vec_b)
+    end
+  end
+end

data/lib/robot_lab/tool.rb

@@ -46,6 +46,33 @@ module RobotLab
       def raise_on_error?
         defined?(@raise_on_error) ? @raise_on_error : false
       end
+
+      # Declare that this tool class is safe to run inside a Ractor.
+      #
+      # Ractor-safe tools must be stateless — no captured mutable closures
+      # and no non-shareable class-level state. The tool is instantiated
+      # fresh inside the Ractor worker for each call.
+      #
+      # With no argument, acts as a getter (walks the inheritance chain).
+      # With a Boolean argument, sets the value.
+      #
+      # @param value [Boolean, nil]
+      # @return [Boolean]
+      def ractor_safe(value = nil)
+        if value.nil?
+          if instance_variable_defined?(:@ractor_safe)
+            @ractor_safe
+          elsif superclass.respond_to?(:ractor_safe)
+            superclass.ractor_safe
+          else
+            false
+          end
+        else
+          @ractor_safe = value
+        end
+      end
+
+      alias ractor_safe? ractor_safe
     end
 
     # Creates a new Tool instance.
@@ -56,13 +83,25 @@ module RobotLab
       @robot = robot
     end
 
-    # Wraps RubyLLM::Tool#call with error handling so the LLM receives
-    # a plain-text error message instead of crashing the run.
+    # Invokes the tool, routing through the Ractor worker pool if ractor_safe.
+    #
+    # For Ractor-safe tools with a resolvable class name: submits to
+    # RobotLab.ractor_pool and blocks for the frozen result. Anonymous
+    # classes (name.nil?) fall through to the inline path.
+    #
+    # For non-Ractor-safe tools: runs execute directly in the calling thread.
     #
     # @param args [Hash] the tool arguments from the LLM
     # @return [Object] the tool result or an error string
     def call(args)
-      super
+      if self.class.ractor_safe? && !self.class.name.nil?
+        RobotLab.ractor_pool.submit(self.class.name, args)
+      else
+        super
+      end
+    rescue RobotLab::ToolError => e
+      raise if self.class.raise_on_error?
+      "Error (#{name}): #{e.message}"
     rescue StandardError => e
       raise if self.class.raise_on_error?
 

data/lib/robot_lab/tool_config.rb

@@ -27,7 +27,7 @@ module RobotLab
   #   # => ["tool3"]
   #
   module ToolConfig
-    NONE_VALUES = [nil, [], :none].freeze
+    NONE_VALUES = [nil, [].freeze, :none].freeze
 
     class << self
       # Resolve a configuration value against its parent

data/lib/robot_lab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RobotLab
-  VERSION = "0.0.9"
+  VERSION = "0.0.11"
 end