robot_lab 0.0.1 → 0.0.4

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/robotic_model.rb

@@ -244,7 +244,7 @@ module RobotLab
       when /^llama/, /^mistral/, /^mixtral/
         :ollama
       else
-        RobotLab.configuration.default_provider
+        RobotLab.config.ruby_llm.provider
       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/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)

data/lib/robot_lab/version.rb

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

data/lib/robot_lab.rb

@@ -1,13 +1,18 @@
 # frozen_string_literal: true
 
-require "zeitwerk"
-require "json"
-require "securerandom"
-require "digest"
+require 'zeitwerk'
+require 'json'
+require 'securerandom'
+require 'digest'
 
 # Core dependencies
-require "ruby_llm"
-require "async"
+# ActiveSupport delegation is required by ruby_llm (RubyLLM::Agent uses delegate)
+# but not declared in ruby_llm's gemspec. Load it before ruby_llm.
+require 'active_support/core_ext/module/delegation'
+require 'ruby_llm'
+require 'prompt_manager'
+require 'async'
+require 'typed_bus'
 
 # Define the module first so Zeitwerk can populate it
 #
@@ -29,10 +34,16 @@ require "async"
 #   result = network.run(message: "Process this document")
 #
 # @example Configuration
-#   RobotLab.configure do |config|
-#     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
-#     config.template_path = "app/templates"
-#   end
+#   # Via environment variables (ROBOT_LAB_* prefix)
+#   # ROBOT_LAB_DEFAULT_MODEL=gpt-4
+#   # ROBOT_LAB_RUBY_LLM__ANTHROPIC_API_KEY=sk-ant-...
+#
+#   # Or via config files (~/.config/robot_lab/config.yml or ./config/robot_lab.yml)
+#   # See lib/robot_lab/config/defaults.yml for all options
+#
+#   # Access configuration values:
+#   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+#   RobotLab.config.ruby_llm.request_timeout  #=> 120
 #
 module RobotLab
 end
@@ -43,16 +54,16 @@ loader.ignore("#{__dir__}/robot_lab/rails")
 
 # Custom inflections for classes that don't follow Zeitwerk naming conventions
 loader.inflector.inflect(
-  "robot_lab" => "RobotLab",
-  "robotic_model" => "RoboticModel",
-  "mcp" => "MCP",
-  "openai" => "OpenAI",
-  "sse" => "SSE",
-  "streamable_http" => "StreamableHTTP",
-  "websocket" => "WebSocket"
+  'robot_lab' => 'RobotLab',
+  'robotic_model' => 'RoboticModel',
+  'mcp' => 'MCP',
+  'openai' => 'OpenAI',
+  'sse' => 'SSE',
+  'streamable_http' => 'StreamableHTTP',
+  'websocket' => 'WebSocket'
 )
 
-# Note: adapters/ is NOT collapsed since files define RobotLab::Adapters::* classes
+# NOTE: adapters/ is NOT collapsed since files define RobotLab::Adapters::* classes
 
 loader.setup
 
@@ -63,40 +74,51 @@ module RobotLab
   # Error classes are defined in lib/robot_lab/error.rb
 
   class << self
-    # @!attribute [w] configuration
-    #   @return [Configuration] the configuration object
-    attr_writer :configuration
-
-    # Returns the current configuration object.
+    # Returns the Config object (MywayConfig-based).
+    #
+    # Configuration is automatically loaded from:
+    # - Bundled defaults (lib/robot_lab/config/defaults.yml)
+    # - Environment-specific overrides (development, test, production)
+    # - XDG config files (~/.config/robot_lab/config.yml)
+    # - Project config (./config/robot_lab.yml)
+    # - Environment variables (ROBOT_LAB_*)
     #
-    # @return [Configuration] the configuration instance
-    def configuration
-      @configuration ||= Configuration.new
+    # @return [Config] the config instance
+    #
+    # @example
+    #   RobotLab.config.ruby_llm.model            #=> "claude-sonnet-4"
+    #   RobotLab.config.ruby_llm.request_timeout  #=> 120
+    #   RobotLab.config.development?              #=> true
+    def config
+      @config ||= Config.new.tap(&:after_load)
     end
 
-    # Yields the configuration object for modification.
+
+    # Reload configuration from all sources.
     #
-    # @yield [Configuration] the configuration object
-    # @return [void]
+    # Clears the cached Config instance, forcing it to be
+    # reloaded on next access.
     #
-    # @example
-    #   RobotLab.configure do |config|
-    #     config.anthropic_api_key = "sk-..."
-    #   end
-    def configure
-      yield(configuration)
+    # @return [Config] the new config instance
+    def reload_config!
+      @config = nil
+      config
     end
 
+
     # Factory method to create a new Robot instance.
     #
-    # @param name [String] the unique identifier for the robot
-    # @param template [Symbol, nil] the ERB template for the robot's prompt
+    # @param name [String, nil] the unique identifier for the robot (auto-generated if nil)
+    # @param template [Symbol, nil] the prompt_manager template for the robot's prompt
     # @param system_prompt [String, nil] inline system prompt (can be used alone or with template)
     # @param context [Hash] variables to pass to the template
     # @param enable_cache [Boolean] whether to enable semantic caching (default: true)
     # @param options [Hash] additional options passed to Robot.new
     # @return [Robot] a new Robot instance
-    # @raise [ArgumentError] if neither template nor system_prompt is provided
+    #
+    # @example Bare robot (no template or prompt)
+    #   robot = RobotLab.build
+    #   robot.with_instructions("You are helpful.").run("Hello!")
     #
     # @example Robot with template
     #   robot = RobotLab.build(
@@ -110,31 +132,19 @@ module RobotLab
     #     name: "helper",
     #     system_prompt: "You are a helpful assistant."
     #   )
-    #
-    # @example Robot with both template and system prompt
-    #   robot = RobotLab.build(
-    #     name: "support",
-    #     template: :support_agent,
-    #     system_prompt: "Today's date is #{Date.today}."
-    #   )
-    #
-    # @example Robot with caching disabled
-    #   robot = RobotLab.build(
-    #     name: "simple",
-    #     system_prompt: "You are helpful.",
-    #     enable_cache: false
-    #   )
-    def build(name:, template: nil, system_prompt: nil, context: {}, enable_cache: true, **options)
+    def build(name: "robot", template: nil, system_prompt: nil, context: {}, enable_cache: true, bus: nil, **options)
       Robot.new(
         name: name,
         template: template,
         system_prompt: system_prompt,
         context: context,
         enable_cache: enable_cache,
+        bus: bus,
         **options
       )
     end
 
+
     # Factory method to create a new Network of robots.
     #
     # @param name [String] the unique identifier for the network
@@ -166,6 +176,7 @@ module RobotLab
       Network.new(name: name, concurrency: concurrency, &block)
     end
 
+
     # Factory method to create a new Memory object.
     #
     # @param data [Hash] initial runtime data
@@ -190,6 +201,6 @@ end
 
 # Load Rails integration if Rails is defined
 if defined?(Rails::Engine)
-  require "robot_lab/rails/engine"
-  require "robot_lab/rails/railtie"
+  require 'robot_lab/rails/engine'
+  require 'robot_lab/rails/railtie'
 end