robot_lab 0.0.1

data/lib/robot_lab/tool_config.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Handles hierarchical MCP and tools configuration resolution
+  #
+  # Configuration hierarchy (each level overrides the previous):
+  # 1. RobotLab.configuration (global)
+  # 2. Network.new (network scope)
+  # 3. Robot.new (robot definition scope)
+  # 4. robot.run (runtime scope)
+  #
+  # Value semantics:
+  # - :inherit     -> Use parent level's configuration
+  # - nil          -> No items allowed
+  # - []           -> No items allowed
+  # - :none        -> No items allowed
+  # - [item1, ...] -> Only these specific items allowed
+  #
+  # @example
+  #   ToolConfig.resolve(:inherit, parent_value: %w[tool1 tool2])
+  #   # => ["tool1", "tool2"]
+  #
+  #   ToolConfig.resolve(nil, parent_value: %w[tool1 tool2])
+  #   # => []
+  #
+  #   ToolConfig.resolve(%w[tool3], parent_value: %w[tool1 tool2])
+  #   # => ["tool3"]
+  #
+  module ToolConfig
+    NONE_VALUES = [nil, [], :none].freeze
+
+    class << self
+      # Resolve a configuration value against its parent
+      #
+      # @param value [Symbol, Array, nil] The current level's value
+      # @param parent_value [Array] The parent level's resolved value
+      # @return [Array] The resolved configuration
+      #
+      def resolve(value, parent_value:)
+        return Array(parent_value) if value == :inherit
+        return [] if none_value?(value)
+
+        Array(value)
+      end
+
+      # Resolve MCP servers configuration
+      #
+      # @param value [Symbol, Array, nil] MCP configuration
+      # @param parent_value [Array] Parent's MCP servers
+      # @return [Array] Resolved MCP server configurations
+      #
+      def resolve_mcp(value, parent_value:)
+        resolve(value, parent_value: parent_value)
+      end
+
+      # Resolve tools configuration
+      #
+      # @param value [Symbol, Array, nil] Tools configuration (tool names as strings)
+      # @param parent_value [Array] Parent's tools
+      # @return [Array<String>] Resolved tool names
+      #
+      def resolve_tools(value, parent_value:)
+        resolved = resolve(value, parent_value: parent_value)
+        resolved.map(&:to_s)
+      end
+
+      # Check if value represents "no items"
+      #
+      # @param value [Object] Value to check
+      # @return [Boolean]
+      #
+      def none_value?(value)
+        NONE_VALUES.include?(value)
+      end
+
+      # Check if value represents "inherit from parent"
+      #
+      # @param value [Object] Value to check
+      # @return [Boolean]
+      #
+      def inherit_value?(value)
+        value == :inherit
+      end
+
+      # Filter tools based on allowed tool names
+      #
+      # Given a list of tool objects and a whitelist of tool names,
+      # returns only the tools whose names are in the whitelist.
+      #
+      # @param tools [Array] Tool objects (must respond to :name)
+      # @param allowed_names [Array<String>] Whitelist of tool names
+      # @return [Array] Filtered tools
+      #
+      def filter_tools(tools, allowed_names:)
+        return [] if allowed_names.empty?
+
+        allowed_set = allowed_names.map(&:to_s).to_set
+        tools.select { |tool| allowed_set.include?(tool_name(tool)) }
+      end
+
+      private
+
+      def tool_name(tool)
+        case tool
+        when String then tool
+        when Symbol then tool.to_s
+        else tool.respond_to?(:name) ? tool.name.to_s : tool.to_s
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/tool_manifest.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Registry of tools with lookup by name
+  #
+  # ToolManifest provides a collection interface for managing multiple tools,
+  # with methods for lookup, iteration, and conversion to various formats.
+  #
+  # @example Creating a manifest
+  #   manifest = ToolManifest.new([weather_tool, calculator_tool])
+  #   manifest[:get_weather]  # => Tool
+  #   manifest.names          # => ["get_weather", "calculate"]
+  #
+  class ToolManifest
+    include Enumerable
+
+    # Creates a new ToolManifest instance.
+    #
+    # @param tools [Array<Tool>] initial tools to add to the manifest
+    #
+    # @example
+    #   manifest = ToolManifest.new([weather_tool, calculator_tool])
+    def initialize(tools = [])
+      @tools = {}
+      Array(tools).each { |tool| add(tool) }
+    end
+
+    # Add a tool to the manifest
+    #
+    # @param tool [Tool] The tool to add
+    # @return [self]
+    #
+    def add(tool)
+      @tools[tool.name] = tool
+      self
+    end
+
+    # @!method <<(tool)
+    #   Alias for {#add}.
+    #   @param tool [Tool] the tool to add
+    #   @return [self]
+    alias << add
+
+    # Remove a tool from the manifest
+    #
+    # @param name [String, Symbol] The tool name
+    # @return [Tool, nil] The removed tool
+    #
+    def remove(name)
+      @tools.delete(name.to_s)
+    end
+
+    # Get a tool by name
+    #
+    # @param name [String, Symbol] The tool name
+    # @return [Tool, nil]
+    #
+    def [](name)
+      @tools[name.to_s]
+    end
+
+    # Get a tool by name, raising if not found
+    #
+    # @param name [String, Symbol] The tool name
+    # @return [Tool]
+    # @raise [ToolNotFoundError] If tool doesn't exist
+    #
+    def fetch(name)
+      @tools.fetch(name.to_s) do
+        raise ToolNotFoundError, "Tool not found: #{name}. Available tools: #{names.join(', ')}"
+      end
+    end
+
+    # Check if a tool exists
+    #
+    # @param name [String, Symbol] The tool name
+    # @return [Boolean]
+    #
+    def include?(name)
+      @tools.key?(name.to_s)
+    end
+
+    # @!method has?(name)
+    #   Alias for {#include?}.
+    #   @param name [String, Symbol] the tool name
+    #   @return [Boolean]
+    alias has? include?
+
+    # Get all tool names
+    #
+    # @return [Array<String>]
+    #
+    def names
+      @tools.keys
+    end
+
+    # Get all tools
+    #
+    # @return [Array<Tool>]
+    #
+    def values
+      @tools.values
+    end
+
+    # @!method all
+    #   Alias for {#values}.
+    #   @return [Array<Tool>]
+    alias all values
+
+    # @!method to_a
+    #   Alias for {#values}.
+    #   @return [Array<Tool>]
+    alias to_a values
+
+    # Number of tools
+    #
+    # @return [Integer]
+    #
+    def size
+      @tools.size
+    end
+
+    # @!method count
+    #   Alias for {#size}.
+    #   @return [Integer]
+    alias count size
+
+    # @!method length
+    #   Alias for {#size}.
+    #   @return [Integer]
+    alias length size
+
+    # Check if manifest is empty
+    #
+    # @return [Boolean]
+    #
+    def empty?
+      @tools.empty?
+    end
+
+    # Iterate over tools
+    #
+    # @yield [Tool] Each tool in the manifest
+    #
+    def each(&block)
+      @tools.values.each(&block)
+    end
+
+    # Clear all tools
+    #
+    # @return [self]
+    #
+    def clear
+      @tools.clear
+      self
+    end
+
+    # Replace all tools
+    #
+    # @param tools [Array<Tool>] New tools
+    # @return [self]
+    #
+    def replace(tools)
+      clear
+      Array(tools).each { |tool| add(tool) }
+      self
+    end
+
+    # Merge another manifest or array of tools
+    #
+    # @param other [ToolManifest, Array<Tool>] Tools to merge
+    # @return [self]
+    #
+    def merge(other)
+      case other
+      when ToolManifest
+        other.each { |tool| add(tool) }
+      when Array
+        other.each { |tool| add(tool) }
+      when Tool
+        add(other)
+      end
+      self
+    end
+
+    # Convert to hash for JSON Schema
+    #
+    # @return [Hash] Map of tool names to their JSON schemas
+    #
+    def to_json_schema
+      @tools.transform_values(&:to_json_schema)
+    end
+
+    # Convert to array of ruby_llm Tool classes
+    #
+    # @return [Array<Class>]
+    #
+    def to_ruby_llm_tools
+      @tools.values.map(&:to_ruby_llm_tool)
+    end
+
+    # Converts the manifest to a hash representation.
+    #
+    # @return [Hash<String, Hash>] map of tool names to their hash representations
+    def to_h
+      @tools.transform_values(&:to_h)
+    end
+
+    # Converts the manifest to JSON.
+    #
+    # @param args [Array] arguments passed to to_json
+    # @return [String] JSON representation
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Create manifest from hash of tool definitions
+    #
+    # @param hash [Hash] Map of names to tool configs
+    # @return [ToolManifest]
+    #
+    def self.from_hash(hash)
+      tools = hash.map do |name, config|
+        Tool.new(
+          name: name,
+          description: config[:description],
+          parameters: config[:parameters],
+          handler: config[:handler]
+        )
+      end
+      new(tools)
+    end
+  end
+end

data/lib/robot_lab/user_message.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Enhanced user message with metadata and system prompt augmentation
+  #
+  # UserMessage wraps the user's input with additional context like
+  # thread ID, system prompt additions, and other metadata that can
+  # influence robot behavior.
+  #
+  # @example Basic usage
+  #   message = UserMessage.new("What is the weather?")
+  #   message.content  # => "What is the weather?"
+  #
+  # @example With metadata
+  #   message = UserMessage.new(
+  #     "What is the weather?",
+  #     session_id: "thread_123",
+  #     system_prompt: "Respond in Spanish",
+  #     metadata: { user_id: "user_456" }
+  #   )
+  #
+  class UserMessage
+    # @!attribute [r] content
+    #   @return [String] the message content
+    # @!attribute [r] session_id
+    #   @return [String, nil] the conversation thread identifier
+    # @!attribute [r] system_prompt
+    #   @return [String, nil] additional system prompt to inject
+    # @!attribute [r] metadata
+    #   @return [Hash] additional metadata
+    # @!attribute [r] id
+    #   @return [String] unique message identifier
+    # @!attribute [r] created_at
+    #   @return [Time] when the message was created
+    attr_reader :content, :session_id, :system_prompt, :metadata, :id, :created_at
+
+    # Creates a new UserMessage instance.
+    #
+    # @param content [String] the message content
+    # @param session_id [String, nil] conversation thread identifier
+    # @param system_prompt [String, nil] additional system prompt
+    # @param metadata [Hash, nil] additional metadata
+    # @param id [String, nil] unique identifier (defaults to UUID)
+    def initialize(content, session_id: nil, system_prompt: nil, metadata: nil, id: nil)
+      @content = content.to_s
+      @session_id = session_id
+      @system_prompt = system_prompt
+      @metadata = metadata || {}
+      @id = id || SecureRandom.uuid
+      @created_at = Time.now
+    end
+
+    # Convert to a simple text message for the conversation
+    #
+    # @return [TextMessage]
+    #
+    def to_message
+      RobotLab::TextMessage.new(role: "user", content: content)
+    end
+
+    # Get the string content (for compatibility with String inputs)
+    #
+    # @return [String]
+    #
+    def to_s
+      content
+    end
+
+    # Converts the message to a hash representation.
+    #
+    # @return [Hash]
+    def to_h
+      {
+        content: content,
+        session_id: session_id,
+        system_prompt: system_prompt,
+        metadata: metadata,
+        id: id,
+        created_at: created_at.iso8601
+      }.compact
+    end
+
+    # Converts the message to JSON.
+    #
+    # @param args [Array] arguments passed to to_json
+    # @return [String] JSON representation
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Create from string or hash
+    #
+    # @param input [String, Hash, UserMessage] Input to normalize
+    # @return [UserMessage]
+    #
+    def self.from(input)
+      case input
+      when UserMessage
+        input
+      when String
+        new(input)
+      when Hash
+        input = input.transform_keys(&:to_sym)
+        new(
+          input[:content],
+          session_id: input[:session_id],
+          system_prompt: input[:system_prompt],
+          metadata: input[:metadata],
+          id: input[:id]
+        )
+      when TextMessage
+        new(input.content)
+      else
+        new(input.to_s)
+      end
+    end
+  end
+end

data/lib/robot_lab/version.rb

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

data/lib/robot_lab/waiter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Thread-safe waiter for blocking get operations on Memory
+  #
+  # Waiter provides a condition variable wrapper that allows one thread
+  # to wait for a value that will be provided by another thread.
+  #
+  # @example Basic usage
+  #   waiter = Waiter.new
+  #
+  #   # In thread A (waiting)
+  #   value = waiter.wait(timeout: 30)
+  #
+  #   # In thread B (signaling)
+  #   waiter.signal("the value")
+  #
+  # @api private
+  class Waiter
+    # Creates a new Waiter instance.
+    def initialize
+      @mutex = Mutex.new
+      @condition = ConditionVariable.new
+      @value = nil
+      @signaled = false
+    end
+
+    # Wait for a value to be signaled.
+    #
+    # @param timeout [Numeric, nil] maximum seconds to wait (nil = indefinite)
+    # @return [Object, :timeout] the signaled value, or :timeout if timed out
+    #
+    def wait(timeout: nil)
+      @mutex.synchronize do
+        return @value if @signaled
+
+        if timeout
+          deadline = Time.now + timeout
+          until @signaled
+            remaining = deadline - Time.now
+            return :timeout if remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          @value
+        else
+          @condition.wait(@mutex) until @signaled
+          @value
+        end
+      end
+    end
+
+    # Signal a value to waiting threads.
+    #
+    # @param value [Object] the value to signal
+    # @return [void]
+    #
+    def signal(value)
+      @mutex.synchronize do
+        @value = value
+        @signaled = true
+        @condition.broadcast
+      end
+    end
+
+    # Check if this waiter has been signaled.
+    #
+    # @return [Boolean]
+    #
+    def signaled?
+      @mutex.synchronize { @signaled }
+    end
+  end
+end