robot_lab 0.0.4 → 0.0.6

data/lib/robot_lab/robot.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'robot/template_rendering'
+require_relative 'robot/mcp_management'
+require_relative 'robot/bus_messaging'
+
 module RobotLab
   # LLM-powered robot built on RubyLLM::Agent
   #
@@ -34,15 +38,9 @@ module RobotLab
   #   )
   #
   class Robot < RubyLLM::Agent
-    # Front matter keys that map to chat configuration methods
-    FRONT_MATTER_CONFIG_KEYS = %i[
-      model temperature top_p top_k max_tokens
-      presence_penalty frequency_penalty stop
-    ].freeze
-
-    # Front matter keys for robot identity and capabilities.
-    # Note: uses `robot_name` because PM::Metadata reserves `name` for the filename.
-    FRONT_MATTER_EXTRA_KEYS = %i[tools mcp robot_name description].freeze
+    include Robot::TemplateRendering
+    include Robot::MCPManagement
+    include Robot::BusMessaging
 
     # @!attribute [r] name
     #   @return [String] the unique identifier for the robot
@@ -68,7 +66,7 @@ module RobotLab
 
     attr_reader :name, :description, :template, :system_prompt,
                 :local_tools, :mcp_clients, :mcp_tools, :memory,
-                :bus, :outbox
+                :bus, :outbox, :config
 
     # @!attribute [r] mcp_config
     #   @return [Symbol, Array] build-time MCP configuration (raw, unresolved)
@@ -99,6 +97,7 @@ module RobotLab
     # @param presence_penalty [Float, nil] penalize based on presence
     # @param frequency_penalty [Float, nil] penalize based on frequency
     # @param stop [String, Array, nil] stop sequences
+    # @param config [RunConfig, nil] shared configuration (merged with explicit kwargs)
     def initialize(
       name:,
       template: nil,
@@ -120,7 +119,8 @@ module RobotLab
       max_tokens: nil,
       presence_penalty: nil,
       frequency_penalty: nil,
-      stop: nil
+      stop: nil,
+      config: nil
     )
       @name = name.to_s
       @name_from_constructor = (name.to_s != "robot")
@@ -129,12 +129,32 @@ module RobotLab
       @build_context = context
       @description = description
       @local_tools = Array(local_tools)
-      @on_tool_call = on_tool_call
-      @on_tool_result = on_tool_result
+
+      # Build RunConfig from explicit kwargs, merged on top of passed-in config.
+      # Explicit constructor kwargs always override the shared config.
+      explicit_fields = {
+        model: model, temperature: temperature, top_p: top_p, top_k: top_k,
+        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,
+        bus: bus, enable_cache: enable_cache
+      }.compact
+
+      # Only include mcp/tools if explicitly set (not the default :none sentinel)
+      resolved_mcp = mcp_servers.any? ? mcp_servers : mcp
+      explicit_fields[:mcp] = resolved_mcp unless ToolConfig.none_value?(resolved_mcp)
+      explicit_fields[:tools] = tools unless ToolConfig.none_value?(tools)
+
+      explicit_config = RunConfig.new(**explicit_fields)
+      @config = config ? config.merge(explicit_config) : explicit_config
+
+      # Extract values from effective config for backward compatibility
+      @on_tool_call = @config.on_tool_call
+      @on_tool_result = @config.on_tool_result
 
       # Store raw config values for hierarchical resolution
-      @mcp_config = mcp_servers.any? ? mcp_servers : mcp
-      @tools_config = tools
+      @mcp_config = @config.mcp || :none
+      @tools_config = @config.tools || :none
 
       # MCP state
       @mcp_clients = {}
@@ -142,19 +162,22 @@ module RobotLab
       @mcp_initialized = false
 
       # Bus state (optional inter-robot communication)
-      @bus = bus
+      @bus = @config.bus
       @message_counter = 0
       @outbox = {}
       @message_handler = nil
+      @bus_processing = false
+      @bus_queue = []
 
       # Inherent memory (used when standalone, not in a network)
-      @memory = Memory.new(enable_cache: enable_cache)
+      cache_enabled = @config.key?(:enable_cache) ? @config.enable_cache : true
+      @memory = Memory.new(enable_cache: cache_enabled)
 
       # Ensure config is loaded (triggers PM setup, RubyLLM config, etc.)
       config = RobotLab.config
 
       # Build chat kwargs for Agent's super
-      resolved_model = model || config.ruby_llm.model
+      resolved_model = @config.model || config.ruby_llm.model
       chat_kwargs = { model: resolved_model }
 
       # Create the persistent chat via Agent's initialize
@@ -165,14 +188,14 @@ module RobotLab
       apply_template_to_chat(context) if @template
       @chat.with_instructions(@system_prompt) if @system_prompt
 
-      # Constructor params override template front matter
-      apply_chat_option(:with_temperature, temperature)
-      apply_chat_option(:with_top_p, top_p)
-      apply_chat_option(:with_top_k, top_k)
-      apply_chat_option(:with_max_tokens, max_tokens)
-      apply_chat_option(:with_presence_penalty, presence_penalty)
-      apply_chat_option(:with_frequency_penalty, frequency_penalty)
-      apply_chat_option(:with_stop, stop)
+      # Constructor params override template front matter (use config values)
+      apply_chat_option(:with_temperature, @config.temperature)
+      apply_chat_option(:with_top_p, @config.top_p)
+      apply_chat_option(:with_top_k, @config.top_k)
+      apply_chat_option(:with_max_tokens, @config.max_tokens)
+      apply_chat_option(:with_presence_penalty, @config.presence_penalty)
+      apply_chat_option(:with_frequency_penalty, @config.frequency_penalty)
+      apply_chat_option(:with_stop, @config.stop)
 
       # Apply callbacks
       @chat.on_tool_call(&@on_tool_call) if @on_tool_call
@@ -206,18 +229,6 @@ module RobotLab
       end
     end
 
-    # Apply a prompt_manager template to the robot's chat
-    #
-    # @param template_id [Symbol, String] the template identifier
-    # @param context [Hash] variables to pass to the template
-    # @return [self]
-    def with_template(template_id, **context)
-      @template = template_id.to_sym
-      @build_context = context
-      apply_template_to_chat(context)
-      self
-    end
-
 
     # Send a message and get a response, with Robot's extended capabilities
     #
@@ -228,8 +239,8 @@ module RobotLab
     # @param mcp [Symbol, Array, nil] runtime MCP override
     # @param tools [Symbol, Array, nil] runtime tools override
     # @return [RobotResult]
-    def run(message = nil, network: nil, network_memory: nil, memory: nil, mcp: :none, tools: :none,
-            **kwargs)
+    def run(message = nil, network: nil, network_memory: nil, network_config: nil,
+            memory: nil, mcp: :none, tools: :none, **kwargs)
       # Determine which memory to use
       run_memory = resolve_active_memory(network: network, network_memory: network_memory)
 
@@ -247,8 +258,8 @@ module RobotLab
 
       begin
         # Resolve hierarchical MCP and tools configuration
-        resolved_mcp = resolve_mcp_hierarchy(mcp, network: network)
-        resolved_tools = resolve_tools_hierarchy(tools, network: network)
+        resolved_mcp = resolve_mcp_hierarchy(mcp, network: network, network_config: network_config)
+        resolved_tools = resolve_tools_hierarchy(tools, network: network, network_config: network_config)
 
         # Initialize or update MCP clients based on resolved config
         ensure_mcp_clients(resolved_mcp)
@@ -329,130 +340,6 @@ module RobotLab
     end
 
 
-    # Send a message to another robot via the bus.
-    #
-    # @param to [String, Symbol] target robot's channel name
-    # @param content [String, Hash] message payload
-    # @return [RobotMessage] the sent message
-    # @raise [BusError] if no bus is configured
-    def send_message(to:, content:)
-      raise BusError, "No bus configured on robot '#{@name}'" unless @bus
-
-      @message_counter += 1
-      message = RobotMessage.build(id: @message_counter, from: @name, content: content)
-      @outbox[message.key] = { message: message, status: :sent, replies: [] }
-      publish_to_bus(to.to_sym, message)
-      message
-    end
-
-
-    # Send a reply to a specific message via the bus.
-    #
-    # @param to [String, Symbol] target robot's channel name
-    # @param content [String, Hash] reply payload
-    # @param in_reply_to [String] composite key of the message being replied to
-    # @return [RobotMessage] the reply message
-    # @raise [BusError] if no bus is configured
-    def send_reply(to:, content:, in_reply_to:)
-      raise BusError, "No bus configured on robot '#{@name}'" unless @bus
-
-      @message_counter += 1
-      reply = RobotMessage.build(id: @message_counter, from: @name, content: content, in_reply_to: in_reply_to)
-      publish_to_bus(to.to_sym, reply)
-      reply
-    end
-
-
-    # Convenience method to reply to a RobotMessage.
-    #
-    # @param message [RobotMessage] the message to reply to
-    # @param content [String, Hash] reply payload
-    # @return [RobotMessage] the reply message
-    def reply(message, content)
-      send_reply(to: message.from.to_sym, content: content, in_reply_to: message.key)
-    end
-
-
-    # Register a custom handler for incoming bus messages.
-    #
-    # Block arity controls delivery handling:
-    # - 1 argument `|message|`: auto-acks before calling, auto-nacks on exception
-    # - 2 arguments `|delivery, message|`: manual mode, you call ack!/nack!
-    #
-    # @yield [message] or [delivery, message]
-    # @return [self]
-    def on_message(&block)
-      @message_handler = block
-      self
-    end
-
-
-    # Spawn a new robot on a shared bus.
-    #
-    # Creates a new Robot instance that shares this robot's bus,
-    # allowing it to immediately send and receive messages with
-    # all other robots on the bus. If no bus exists yet, one is
-    # created automatically and the parent robot is connected to it.
-    #
-    # @param name [String] unique name for the new robot
-    # @param system_prompt [String, nil] inline system prompt
-    # @param template [Symbol, nil] prompt_manager template
-    # @param local_tools [Array] tools for the new robot
-    # @param options [Hash] additional options passed to RobotLab.build
-    # @return [Robot] the newly created robot
-    #
-    # @example Spawn from a bus-less robot (bus and name created automatically)
-    #   bot  = RobotLab.build
-    #   bot2 = bot.spawn(system_prompt: "You are helpful.")
-    #
-    # @example Spawn a specialist from a message handler
-    #   on_message do |message|
-    #     specialist = spawn(
-    #       name: "fact_checker",
-    #       system_prompt: "You verify factual claims. Be concise."
-    #     )
-    #     specialist.send_message(to: name.to_sym, content: specialist.run(message.content).last_text_content)
-    #   end
-    #
-    def spawn(name: "robot", system_prompt: nil, template: nil, local_tools: [], **options)
-      ensure_bus
-
-      RobotLab.build(
-        name: name,
-        system_prompt: system_prompt,
-        template: template,
-        local_tools: local_tools,
-        bus: @bus,
-        **options
-      )
-    end
-
-
-    # Connect this robot to a message bus.
-    #
-    # If a bus is provided, the robot joins it. If no bus is provided
-    # and the robot doesn't already have one, a new bus is created.
-    # No-op if the robot is already on the given bus.
-    #
-    # @param bus [TypedBus::MessageBus, nil] bus to join (creates one if nil)
-    # @return [self]
-    #
-    # @example Join an existing bus
-    #   bot = RobotLab.build.with_bus(some_bus)
-    #
-    # @example Create a bus on demand
-    #   bot = RobotLab.build.with_bus
-    #
-    def with_bus(bus = nil)
-      return self if bus && @bus == bus
-
-      teardown_bus_channel if @bus
-      @bus = bus || @bus || TypedBus::MessageBus.new
-      setup_bus_channel
-      self
-    end
-
-
     # Disconnect all MCP clients and bus channel.
     #
     # @return [self]
@@ -478,6 +365,7 @@ module RobotLab
         tools_config: @tools_config,
         mcp_servers: @mcp_clients.keys,
         model: model,
+        config: (@config.empty? ? nil : @config.to_json_hash),
         bus: @bus ? true : nil
       }.compact
     end
@@ -490,107 +378,6 @@ module RobotLab
     end
 
 
-    # Apply a prompt_manager template to the persistent chat.
-    # If required parameters are missing, applies front matter config but
-    # defers rendering until run time when all values are available.
-    def apply_template_to_chat(context)
-      parsed = PM.parse(@template)
-
-      # Extract extra config from front matter (name, description, tools, mcp)
-      apply_front_matter_extras(parsed.metadata)
-
-      # Extract and apply LLM config to the chat (model, temperature, etc.)
-      apply_front_matter_config(parsed.metadata)
-
-      # Resolve context (could be a Proc)
-      resolved_ctx = resolve_context(context, network: nil)
-
-      # Render the template body with context
-      begin
-        rendered = parsed.to_s(**resolved_ctx)
-        @chat.with_instructions(rendered)
-      rescue ArgumentError => e
-        raise unless e.message.start_with?("Missing required parameters:")
-
-        # Required parameters not yet available; template will be
-        # fully rendered at run time via rerender_template.
-      end
-    end
-
-
-    # Re-render the template with run-time context merged into build-time context.
-    # prompt_manager parameters may be required (null) and only available at run time.
-    def rerender_template(run_context)
-      merged = (@build_context || {}).merge(run_context)
-      parsed = PM.parse(@template)
-      resolved_ctx = resolve_context(merged, network: nil)
-      rendered = parsed.to_s(**resolved_ctx)
-      @chat.with_instructions(rendered)
-    end
-
-
-    # Extract whitelisted config from front matter and apply to chat
-    def apply_front_matter_config(metadata)
-      FRONT_MATTER_CONFIG_KEYS.each do |key|
-        value = metadata.respond_to?(key) ? metadata.send(key) : nil
-        next unless value
-
-        method = :"with_#{key}"
-        @chat.public_send(method, value) if @chat.respond_to?(method)
-      end
-
-      # Handle model specially (may need with_model)
-      return unless metadata.respond_to?(:model) && metadata.model
-
-      @chat.with_model(metadata.model)
-
-    end
-
-
-    # Extract identity and capability keys from front matter metadata.
-    # Constructor-provided values take precedence over frontmatter.
-    def apply_front_matter_extras(metadata)
-      if metadata.respond_to?(:robot_name) && metadata.robot_name && !@name_from_constructor
-        @name = metadata.robot_name.to_s
-      end
-
-      if metadata.respond_to?(:description) && metadata.description && @description.nil?
-        @description = metadata.description.to_s
-      end
-
-      if metadata.respond_to?(:tools) && metadata.tools.is_a?(Array) && @local_tools.empty?
-        @local_tools = resolve_frontmatter_tools(metadata.tools)
-      end
-
-      if metadata.respond_to?(:mcp) && metadata.mcp.is_a?(Array) && ToolConfig.none_value?(@mcp_config)
-        @mcp_config = metadata.mcp.map { |m| m.is_a?(Hash) ? m.transform_keys(&:to_sym) : m }
-      end
-    end
-
-
-    # Resolve string tool names from frontmatter to Ruby constants.
-    # Tool subclasses are instantiated; instances are used as-is.
-    # Unresolvable names are skipped with a warning.
-    def resolve_frontmatter_tools(tool_names)
-      tool_names.filter_map do |name|
-        case name
-        when String
-          begin
-            const = Object.const_get(name)
-            const.is_a?(Class) && const < RubyLLM::Tool ? const.new : const
-          rescue NameError
-            RobotLab.config.logger.warn("Robot '#{@name}': tool '#{name}' not found, skipping")
-            nil
-          end
-        when Class
-          name.new
-        else
-          name
-        end
-      end
-    end
-
-
     # Determine which memory to use
     def resolve_active_memory(network: nil, network_memory: nil)
       network_memory || network&.memory || @memory
@@ -606,6 +393,7 @@ module RobotLab
       tools = run_params.delete(:tools) || :none
       memory = run_params.delete(:memory)
       network_memory = run_params.delete(:network_memory)
+      network_config = run_params.delete(:network_config)
 
       # Build base context from remaining run params
       base = run_params.dup
@@ -627,20 +415,12 @@ module RobotLab
       merged[:tools] = tools
       merged[:memory] = memory if memory
       merged[:network_memory] = network_memory if network_memory
+      merged[:network_config] = network_config if network_config
 
       merged
     end
 
 
-    def resolve_context(context, network:)
-      case context
-      when Proc then context.call(network: network)
-      when Hash then context
-      else {}
-      end
-    end
-
-
     def build_result(response, _memory)
       output = if response.respond_to?(:content) && response.content
                  [TextMessage.new(role: 'assistant', content: response.content)]
@@ -675,81 +455,6 @@ module RobotLab
     end
 
 
-    # Resolve MCP hierarchy: runtime -> robot build -> network -> config
-    def resolve_mcp_hierarchy(runtime_value, network:)
-      parent_value = network&.network&.mcp || RobotLab.config.mcp
-      build_resolved = ToolConfig.resolve_mcp(@mcp_config, parent_value: parent_value)
-      ToolConfig.resolve_mcp(runtime_value, parent_value: build_resolved)
-    end
-
-
-    # Resolve tools hierarchy: runtime -> robot build -> network -> config
-    def resolve_tools_hierarchy(runtime_value, network:)
-      parent_value = network&.network&.tools || RobotLab.config.tools
-      build_resolved = ToolConfig.resolve_tools(@tools_config, parent_value: parent_value)
-      ToolConfig.resolve_tools(runtime_value, parent_value: build_resolved)
-    end
-
-
-    # Ensure MCP clients are initialized for the given server configs
-    def ensure_mcp_clients(mcp_servers)
-      return if mcp_servers.empty?
-
-      needed_servers = mcp_servers.map { |s| s.is_a?(Hash) ? s[:name] : s.to_s }.compact
-      return if @mcp_initialized && (@mcp_clients.keys.sort == needed_servers.sort)
-
-      disconnect if @mcp_initialized
-
-      @mcp_clients = {}
-      @mcp_tools = []
-
-      mcp_servers.each do |server_config|
-        init_mcp_client(server_config)
-      end
-
-      @mcp_initialized = true
-    end
-
-
-    def init_mcp_client(server_config)
-      client = MCP::Client.new(server_config)
-      client.connect
-
-      if client.connected?
-        server_name = client.server.name
-        @mcp_clients[server_name] = client
-        discover_mcp_tools(client, server_name)
-      else
-        RobotLab.config.logger.warn(
-          "Robot '#{@name}' failed to connect to MCP server: #{server_config[:name] || server_config}"
-        )
-      end
-    end
-
-
-    def discover_mcp_tools(client, server_name)
-      tools = client.list_tools
-
-      tools.each do |tool_def|
-        tool_name = tool_def[:name]
-        mcp_client = client
-
-        tool = Tool.create(
-          name: tool_name,
-          description: tool_def[:description],
-          parameters: tool_def[:inputSchema],
-          mcp: server_name
-        ) { |args| mcp_client.call_tool(tool_name, args) }
-
-        @mcp_tools << tool
-      end
-
-      RobotLab.config.logger.info(
-        "Robot '#{@name}' discovered #{tools.size} tools from MCP server '#{server_name}'"
-      )
-    end
-
-
     def all_tools
       @local_tools + @mcp_tools
     end
@@ -761,74 +466,5 @@ module RobotLab
 
       ToolConfig.filter_tools(available, allowed_names: allowed_names)
     end
-
-
-    # Create a bus if one doesn't exist and connect this robot to it
-    def ensure_bus
-      with_bus unless @bus
-    end
-
-
-    # Create a typed channel on the bus and subscribe to it
-    def setup_bus_channel
-      channel_name = @name.to_sym
-      @bus.add_channel(channel_name, type: RobotMessage) unless @bus.channel?(channel_name)
-      @bus_subscriber_id = @bus.subscribe(channel_name) { |delivery| handle_incoming_delivery(delivery) }
-    end
-
-
-    # Unsubscribe from the bus channel
-    def teardown_bus_channel
-      channel_name = @name.to_sym
-      @bus.unsubscribe(channel_name, @bus_subscriber_id) if @bus_subscriber_id
-      @bus_subscriber_id = nil
-    end
-
-
-    # Dispatch incoming bus delivery to handler.
-    # Auto-ack when the handler takes 1 arg (message only);
-    # manual ack/nack when the handler takes 2 args (delivery, message).
-    def handle_incoming_delivery(delivery)
-      message = delivery.message
-
-      # Correlate replies with outbox entries
-      if message.reply? && @outbox.key?(message.in_reply_to)
-        entry = @outbox[message.in_reply_to]
-        entry[:status] = :replied
-        entry[:replies] << message
-      end
-
-      if @message_handler
-        if @message_handler.arity == 1
-          delivery.ack!
-          @message_handler.call(message)
-        else
-          @message_handler.call(delivery, message)
-        end
-      else
-        handle_message_via_llm(delivery, message)
-      end
-    rescue => e
-      delivery.nack! if delivery.pending?
-      raise BusError, "Error handling bus message on robot '#{@name}': #{e.message}"
-    end
-
-
-    # Default handler: interpret message via LLM and reply
-    def handle_message_via_llm(delivery, message)
-      delivery.ack!
-      result = run(message.content.to_s)
-      send_reply(to: message.from.to_sym, content: result.last_text_content, in_reply_to: message.key)
-    end
-
-
-    # Publish a RobotMessage to a bus channel
-    def publish_to_bus(channel_name, message)
-      if defined?(Async::Task) && Async::Task.current?
-        @bus.publish(channel_name, message)
-      else
-        Async { @bus.publish(channel_name, message) }
-      end
-    end
   end
 end