robot_lab 0.0.1 → 0.0.6

data/lib/robot_lab/robot_message.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Typed message envelope for bus-based robot communication.
+  #
+  # RobotMessage is a Data class (immutable value object) that wraps
+  # content sent between robots via a TypedBus channel.
+  #
+  # @example Creating a new message
+  #   msg = RobotMessage.build(id: 1, from: "alice", content: "Hello")
+  #   msg.key       #=> "alice:1"
+  #   msg.reply?    #=> false
+  #
+  # @example Creating a reply
+  #   reply = RobotMessage.build(
+  #     id: 2, from: "bob",
+  #     content: "Hi back",
+  #     in_reply_to: "alice:1"
+  #   )
+  #   reply.reply?  #=> true
+  #
+  RobotMessage = Data.define(:id, :from, :content, :in_reply_to) do
+    # Build a RobotMessage with in_reply_to defaulting to nil.
+    #
+    # @param id [Integer] per-robot message counter
+    # @param from [String] sender's robot name (= channel name)
+    # @param content [String, Hash] message payload
+    # @param in_reply_to [String, nil] composite key of the message being replied to
+    # @return [RobotMessage]
+    def self.build(id:, from:, content:, in_reply_to: nil)
+      new(id: id, from: from, content: content, in_reply_to: in_reply_to)
+    end
+
+    # Composite identity key: "from:id"
+    #
+    # @return [String]
+    def key = "#{from}:#{id}"
+
+    # Whether this message is a reply to another message.
+    #
+    # @return [Boolean]
+    def reply? = !in_reply_to.nil?
+  end
+end

data/lib/robot_lab/robot_result.rb

@@ -135,6 +135,7 @@ module RobotLab
     def last_text_content
       output.reverse.find(&:text?)&.content
     end
+    alias_method :reply, :last_text_content
 
     # Check if result contains tool calls
     #

data/lib/robot_lab/run_config.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Shared configuration object for LLM, tools, callbacks, and infrastructure.
+  #
+  # RunConfig provides a unified way to express operational defaults that flow
+  # through the configuration hierarchy:
+  #
+  #   RobotLab.config -> Network -> Robot -> Template front matter -> Task -> Runtime
+  #
+  # Only explicitly set values are stored. Merge semantics: the more-specific
+  # config's non-nil values win over the less-specific config.
+  #
+  # @example Keyword construction
+  #   config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.7)
+  #
+  # @example Block DSL
+  #   config = RunConfig.new do |c|
+  #     c.model "claude-sonnet-4"
+  #     c.temperature 0.7
+  #   end
+  #
+  # @example Merge (more-specific wins)
+  #   network_config = RunConfig.new(model: "claude-sonnet-4", temperature: 0.5)
+  #   robot_config   = RunConfig.new(temperature: 0.9)
+  #   effective       = network_config.merge(robot_config)
+  #   effective.temperature  #=> 0.9
+  #   effective.model        #=> "claude-sonnet-4"
+  #
+  class RunConfig
+    # LLM configuration fields (applied to chat via with_* methods)
+    LLM_FIELDS = %i[
+      model temperature top_p top_k max_tokens
+      presence_penalty frequency_penalty stop
+    ].freeze
+
+    # Tool-related fields
+    TOOL_FIELDS = %i[mcp tools].freeze
+
+    # Callback fields (Procs)
+    CALLBACK_FIELDS = %i[on_tool_call on_tool_result].freeze
+
+    # Infrastructure fields
+    INFRA_FIELDS = %i[bus enable_cache].freeze
+
+    # All recognized fields
+    FIELDS = (LLM_FIELDS + TOOL_FIELDS + CALLBACK_FIELDS + INFRA_FIELDS).freeze
+
+    # Fields that cannot be serialized to JSON (Procs, IO objects, etc.)
+    NON_SERIALIZABLE_FIELDS = (CALLBACK_FIELDS + %i[bus]).freeze
+
+    # Creates a new RunConfig.
+    #
+    # @param kwargs [Hash] field values to set
+    # @yield [self] optional block for DSL-style configuration
+    def initialize(**kwargs)
+      @fields = {}
+
+      kwargs.each do |key, value|
+        set(key, value)
+      end
+
+      yield self if block_given?
+    end
+
+    # Define getter/setter DSL methods for each field.
+    #
+    # With no arguments: returns the current value (getter).
+    # With one argument: sets the value and returns self (chainable setter).
+    FIELDS.each do |field|
+      define_method(field) do |value = :__unset__|
+        if value == :__unset__
+          @fields[field]
+        else
+          set(field, value)
+          self
+        end
+      end
+    end
+
+    # Returns a duplicate of the internal fields hash.
+    #
+    # @return [Hash] only the fields that have been explicitly set
+    def to_h
+      @fields.dup
+    end
+
+
+    # Returns a JSON-safe hash (skips Procs, IO, and other non-serializable values).
+    #
+    # @return [Hash]
+    def to_json_hash
+      @fields.reject { |k, _| NON_SERIALIZABLE_FIELDS.include?(k) }
+    end
+
+
+    # Merges another RunConfig (or Hash) on top of this one.
+    # The other's non-nil values win. Returns a new RunConfig.
+    #
+    # @param other [RunConfig, Hash] the more-specific configuration
+    # @return [RunConfig] a new merged RunConfig
+    def merge(other)
+      other_hash = other.is_a?(RunConfig) ? other.to_h : other
+      merged = @fields.merge(other_hash) { |_k, old_v, new_v| new_v.nil? ? old_v : new_v }
+      self.class.new(**merged)
+    end
+
+
+    # Applies LLM fields to a chat object via its with_* methods.
+    #
+    # @param chat [Object] a RubyLLM::Chat (or similar) that responds to with_model, with_temperature, etc.
+    def apply_to(chat)
+      LLM_FIELDS.each do |field|
+        value = @fields[field]
+        next unless value
+
+        method = :"with_#{field}"
+        chat.public_send(method, value) if chat.respond_to?(method)
+      end
+    end
+
+
+    # Build a RunConfig from prompt_manager front matter metadata.
+    #
+    # @param metadata [Object] a PM::Metadata object (responds to field names)
+    # @return [RunConfig]
+    def self.from_front_matter(metadata)
+      fields = {}
+
+      LLM_FIELDS.each do |key|
+        value = metadata.respond_to?(key) ? metadata.send(key) : nil
+        fields[key] = value if value
+      end
+
+      # Extract tool-related fields
+      %i[mcp tools].each do |key|
+        value = metadata.respond_to?(key) ? metadata.send(key) : nil
+        fields[key] = value if value
+      end
+
+      new(**fields)
+    end
+
+
+    # @return [Boolean] true if no fields have been set
+    def empty?
+      @fields.empty?
+    end
+
+
+    # @param field [Symbol] the field name
+    # @return [Boolean] true if the field has been explicitly set
+    def key?(field)
+      @fields.key?(field)
+    end
+
+
+    # @param other [RunConfig] the other RunConfig to compare
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(RunConfig) && to_h == other.to_h
+    end
+
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{@fields.inspect}>"
+    end
+
+    private
+
+    # Validates and stores a field value. Nil removes the key.
+    def set(field, value)
+      field = field.to_sym
+      raise ArgumentError, "Unknown RunConfig field: #{field}" unless FIELDS.include?(field)
+
+      if value.nil?
+        @fields.delete(field)
+      else
+        @fields[field] = value
+      end
+    end
+  end
+end

data/lib/robot_lab/state_proxy.rb

@@ -16,6 +16,8 @@ module RobotLab
   #   proxy.to_h        # => { count: 1, name: "test" }
   #
   class StateProxy
+    include Utils
+
     # Creates a new StateProxy.
     #
     # @param data [Hash] the initial data
@@ -172,17 +174,5 @@ module RobotLab
       "#<RobotLab::StateProxy #{@data.inspect}>"
     end
 
-    private
-
-    def deep_dup(obj)
-      case obj
-      when Hash
-        obj.transform_values { |v| deep_dup(v) }
-      when Array
-        obj.map { |v| deep_dup(v) }
-      else
-        obj.dup rescue obj
-      end
-    end
   end
 end

data/lib/robot_lab/streaming/context.rb

@@ -56,7 +56,7 @@ module RobotLab
         begin
           @publish.call(chunk)
         rescue StandardError => e
-          RobotLab.configuration.logger.warn("Streaming error: #{e.message}")
+          RobotLab.config.logger&.warn("Streaming error: #{e.message}")
         end
 
         chunk

data/lib/robot_lab/task.rb

@@ -39,13 +39,14 @@ module RobotLab
     # @param tools [Symbol, Array] tools config (:none, :inherit, or array)
     # @param memory [Memory, Hash, nil] task-specific memory
     #
-    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil)
+    def initialize(name:, robot:, context: {}, mcp: :none, tools: :none, memory: nil, config: nil)
       @name = name.to_sym
       @robot = robot
       @context = context
       @mcp = mcp
       @tools = tools
       @memory = memory
+      @config = config
     end
 
     # SimpleFlow step interface
@@ -68,6 +69,12 @@ module RobotLab
       run_params[:tools] = @tools unless @tools == :none
       run_params[:memory] = @memory if @memory
 
+      # Merge task's config on top of network's config
+      if @config
+        network_rc = run_params[:network_config]
+        run_params[:network_config] = network_rc ? network_rc.merge(@config) : @config
+      end
+
       # Create enhanced result with merged params
       enhanced_result = result.with_context(:run_params, run_params)
 

data/lib/robot_lab/tool.rb

@@ -1,222 +1,158 @@
 # frozen_string_literal: true
 
 module RobotLab
-  # Defines a tool/function that robots can use
+  # A tool that robots can use, built on RubyLLM::Tool.
   #
-  # Tools are capabilities that robots can invoke during execution.
-  # They have a name, description, parameter schema, and handler.
+  # Provides two patterns for defining tools:
   #
-  # @example Simple tool
-  #   tool = Tool.new(
-  #     name: "get_time",
-  #     description: "Get the current time",
-  #     handler: -> (_input, **_opts) { Time.now.to_s }
-  #   )
+  # 1. **Subclass pattern** — for reusable, robot-aware tools:
+  #
+  #   class GetWeather < RobotLab::Tool
+  #     description "Get weather for a location"
+  #     param :location, type: "string", desc: "City name"
   #
-  # @example Tool with parameters (using ruby_llm-schema)
-  #   class WeatherParams < RubyLLM::Schema
-  #     string :location, description: "City name"
-  #     string :unit, enum: %w[celsius fahrenheit], required: false
+  #     def execute(location:)
+  #       WeatherService.fetch(location)
+  #     end
   #   end
   #
-  #   tool = Tool.new(
-  #     name: "get_weather",
-  #     description: "Get weather for a location",
-  #     parameters: WeatherParams,
-  #     handler: ->(input, **opts) {
-  #       # input[:location], input[:unit] are validated
-  #       fetch_weather(input[:location], input[:unit] || "celsius")
-  #     }
-  #   )
+  # 2. **Factory pattern** — for dynamic/inline tools:
+  #
+  #   tool = RobotLab::Tool.create(
+  #     name: "get_time",
+  #     description: "Get the current time"
+  #   ) { |args| Time.now.to_s }
   #
-  class Tool
-    # @!attribute [r] name
-    #   @return [String] the unique identifier for the tool
-    # @!attribute [r] description
-    #   @return [String, nil] a description of what the tool does
-    # @!attribute [r] parameters
-    #   @return [Class, Hash, nil] the parameter schema (RubyLLM::Schema or JSON Schema hash)
-    # @!attribute [r] handler
-    #   @return [Proc, nil] the callable that executes the tool logic
+  # Subclasses have access to the owning +robot+ via an accessor,
+  # enabling tools that modify their robot's state (temperature,
+  # system prompt, spawning, etc.).
+  #
+  class Tool < RubyLLM::Tool
+    # @!attribute [rw] robot
+    #   @return [Robot, nil] the robot that owns this tool
+    attr_accessor :robot
+
     # @!attribute [r] mcp
     #   @return [String, nil] the MCP server name if this is an MCP-provided tool
-    # @!attribute [r] strict
-    #   @return [Boolean, nil] whether strict mode is enabled
-    attr_reader :name, :description, :parameters, :handler, :mcp, :strict
+    attr_reader :mcp
 
     # Creates a new Tool instance.
     #
-    # @param name [String] the unique identifier for the tool
-    # @param description [String, nil] a description of what the tool does
-    # @param parameters [Class, Hash, nil] parameter schema (RubyLLM::Schema or JSON Schema)
-    # @param handler [Proc, nil] the callable that executes the tool logic
-    # @param mcp [String, nil] MCP server name if this is an MCP tool
-    # @param strict [Boolean, nil] whether strict mode is enabled
-    # @yield [input, **opts] optional block as handler
-    #
-    # @example Tool with block handler
-    #   Tool.new(name: "greet", description: "Greet user") do |input, **opts|
-    #     "Hello, #{input[:name]}!"
-    #   end
-    def initialize(name:, description: nil, parameters: nil, handler: nil, mcp: nil, strict: nil, &block)
-      @name = name.to_s
-      @description = description
-      @parameters = parameters
-      @handler = handler || block
-      @mcp = mcp
-      @strict = strict
+    # @param robot [Robot, nil] the owning robot
+    def initialize(robot: nil)
+      super()
+      @robot = robot
     end
 
-    # Execute the tool with input and context
+    # Override name to support explicit names for dynamic/MCP tools.
     #
-    # Supports two calling conventions:
-    # - Direct: tool.call(input, robot: robot, network: network)
-    # - ruby_llm: tool.call(args) - called without keyword args
-    #
-    # @param input [Hash] The input parameters (validated against schema)
-    # @param robot [Robot, nil] The robot invoking this tool
-    # @param network [NetworkRun, nil] The network context if running in a network
-    # @param step [Object, nil] Durable execution step context
-    # @return [Object] The tool's output
+    # @return [String] the tool name
+    def name
+      defined?(@custom_name) && @custom_name ? @custom_name : super
+    end
+
+    # Check if this is an MCP-provided tool.
     #
-    def call(input, robot: nil, network: nil, step: nil)
-      raise Error, "Tool '#{name}' has no handler defined" unless handler
+    # @return [Boolean]
+    def mcp?
+      !@mcp.nil?
+    end
 
-      validated_input = validate_input(input)
-      handler.call(validated_input, robot: robot, network: network, step: step)
-    rescue Error
-      raise
-    rescue StandardError => e
-      { error: Errors.serialize(e) }
+    # Factory for dynamic tools (MCP wrappers, inline tools).
+    #
+    # @param name [String, Symbol] the tool name
+    # @param description [String, nil] what the tool does
+    # @param parameters [Hash, nil] JSON Schema parameter definition
+    # @param mcp [String, nil] MCP server name
+    # @param robot [Robot, nil] the owning robot
+    # @yield [args] block that executes the tool logic
+    # @return [Tool] a new tool instance
+    #
+    # @example Simple factory tool
+    #   tool = RobotLab::Tool.create(
+    #     name: "get_time",
+    #     description: "Get the current time"
+    #   ) { |args| Time.now.to_s }
+    #
+    # @example MCP tool wrapper
+    #   tool = RobotLab::Tool.create(
+    #     name: "search",
+    #     description: "Search the web",
+    #     parameters: { type: "object", properties: { q: { type: "string" } }, required: ["q"] },
+    #     mcp: "brave_search"
+    #   ) { |args| mcp_client.call_tool("search", args) }
+    #
+    def self.create(name:, description: nil, parameters: nil, mcp: nil, robot: nil, &handler)
+      desc_text = description
+      params_hash = parameters
+      block = handler
+
+      tool_class = Class.new(self) do
+        description(desc_text) if desc_text
+
+        if params_hash.is_a?(Hash) && params_hash[:properties]
+          required_list = Array(params_hash[:required]).map(&:to_s)
+          params_hash[:properties].each do |pname, pdef|
+            param pname.to_sym,
+                  type: pdef[:type] || "string",
+                  desc: pdef[:description],
+                  required: required_list.include?(pname.to_s)
+          end
+        end
+
+        define_method(:execute) do |**args|
+          block.call(args)
+        end
+      end
+
+      instance = tool_class.new(robot: robot)
+      instance.instance_variable_set(:@custom_name, name.to_s)
+      instance.instance_variable_set(:@mcp, mcp)
+      instance
     end
 
-    # Convert to JSON Schema for LLM function calling
+    # Convert to JSON Schema for LLM function calling.
+    # Used by RobotLab adapters for provider-specific formatting.
     #
     # @return [Hash] JSON Schema representation
-    #
     def to_json_schema
-      schema = if parameters.respond_to?(:to_json_schema)
-                 # ruby_llm-schema class
-                 parameters.new.to_json_schema[:schema]
-               elsif parameters.is_a?(Hash)
-                 # Raw JSON schema
-                 parameters
-               else
-                 # No parameters
-                 { type: "object", properties: {}, required: [] }
-               end
-
+      schema = params_schema || { "type" => "object", "properties" => {}, "required" => [] }
       {
         name: name,
         description: description,
-        parameters: schema
+        parameters: deep_symbolize_keys(schema)
       }.compact
     end
 
-    # Convert to ruby_llm Tool class for integration
-    #
-    # @return [Class] A RubyLLM::Tool subclass
-    #
-    def to_ruby_llm_tool
-      tool = self
-      Class.new(RubyLLM::Tool) do
-        description tool.description
-
-        # Define parameters from schema
-        if tool.parameters.respond_to?(:to_json_schema)
-          schema = tool.parameters.new.to_json_schema[:schema]
-          schema[:properties]&.each do |prop_name, prop_def|
-            param prop_name.to_sym,
-                  type: prop_def[:type],
-                  desc: prop_def[:description],
-                  required: schema[:required]&.include?(prop_name.to_s)
-          end
-        elsif tool.parameters.is_a?(Hash) && tool.parameters[:properties]
-          tool.parameters[:properties].each do |prop_name, prop_def|
-            param prop_name.to_sym,
-                  type: prop_def[:type] || "string",
-                  desc: prop_def[:description],
-                  required: tool.parameters[:required]&.include?(prop_name.to_s)
-          end
-        end
-
-        define_method(:execute) do |**kwargs|
-          # This will be overridden at runtime with proper context
-          kwargs
-        end
-      end
-    end
-
-    # Converts the tool to a hash representation.
+    # Hash representation.
     #
-    # @return [Hash] a hash containing the tool configuration
+    # @return [Hash]
     def to_h
       {
         name: name,
         description: description,
-        parameters: parameters_to_hash,
-        mcp: mcp,
-        strict: strict
+        mcp: mcp
       }.compact
     end
 
-    # Converts the tool to JSON.
+    # JSON representation.
     #
     # @param args [Array] arguments passed to to_json
-    # @return [String] JSON representation of the tool
+    # @return [String]
     def to_json(*args)
       to_h.to_json(*args)
     end
 
-    # Check if this is an MCP-provided tool
-    #
-    # @return [Boolean]
-    #
-    def mcp?
-      !mcp.nil?
-    end
-
-    # Return parameters schema for ruby_llm compatibility
-    #
-    # @return [Hash, nil] JSON Schema for tool parameters
-    #
-    def params_schema
-      if parameters.respond_to?(:to_json_schema)
-        parameters.new.to_json_schema[:schema]
-      elsif parameters.is_a?(Hash)
-        parameters
-      end
-    end
-
-    # Provider-specific parameters for ruby_llm compatibility
-    #
-    # @return [Hash] Empty hash (no provider-specific params)
-    #
-    def provider_params
-      {}
-    end
-
     private
 
-    def validate_input(input)
-      return input unless parameters
-
-      input = input.transform_keys(&:to_sym) if input.is_a?(Hash)
-
-      if parameters.respond_to?(:new) && parameters.ancestors.include?(defined?(RubyLLM::Schema) ? RubyLLM::Schema : Object)
-        # Validate with ruby_llm-schema (if available)
-        # For now, just pass through
-        input
+    def deep_symbolize_keys(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) { |(k, v), h| h[k.to_sym] = deep_symbolize_keys(v) }
+      when Array
+        obj.map { |v| deep_symbolize_keys(v) }
       else
-        input
-      end
-    end
-
-    def parameters_to_hash
-      if parameters.respond_to?(:to_json_schema)
-        parameters.new.to_json_schema
-      elsif parameters.is_a?(Hash)
-        parameters
+        obj
       end
     end
   end

data/lib/robot_lab/tool_config.rb

@@ -4,7 +4,7 @@ module RobotLab
   # Handles hierarchical MCP and tools configuration resolution
   #
   # Configuration hierarchy (each level overrides the previous):
-  # 1. RobotLab.configuration (global)
+  # 1. RobotLab.config (global)
   # 2. Network.new (network scope)
   # 3. Robot.new (robot definition scope)
   # 4. robot.run (runtime scope)

data/lib/robot_lab/tool_manifest.rb

@@ -183,22 +183,6 @@ module RobotLab
       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
@@ -221,11 +205,11 @@ module RobotLab
     #
     def self.from_hash(hash)
       tools = hash.map do |name, config|
-        Tool.new(
+        Tool.create(
           name: name,
           description: config[:description],
           parameters: config[:parameters],
-          handler: config[:handler]
+          &config[:handler]
         )
       end
       new(tools)