robot_lab 0.0.4 → 0.0.6

data/lib/robot_lab/robot/bus_messaging.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Inter-robot communication via TypedBus.
+    #
+    # Expects the including class to provide:
+    #   @bus, @message_counter, @outbox, @message_handler,
+    #   @bus_subscriber_id, @bus_processing, @bus_queue, @name
+    #   and the `run` instance method
+    #
+    # == Processing Guard
+    #
+    # TypedBus delivers messages in concurrent Async fibers. When a robot's
+    # +run()+ yields during HTTP I/O, the Async scheduler can switch to
+    # another fiber delivering a new bus message to the same robot. This
+    # would interleave user messages between +tool_use+ / +tool_result+
+    # pairs in +@chat+, corrupting Anthropic API message ordering.
+    #
+    # The processing guard serializes delivery handling: deliveries that
+    # arrive while the robot is already processing are queued and drained
+    # sequentially after the current one completes.
+    #
+    module BusMessaging
+      # 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
+
+
+      # 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
+
+      private
+
+      # 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.
+      #
+      # Uses a processing guard to serialize delivery handling. When
+      # the robot is already processing a delivery (e.g., inside a
+      # run() call that yields during HTTP I/O), new deliveries are
+      # queued and drained sequentially after the current one completes.
+      #
+      # 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)
+        if @bus_processing
+          @bus_queue << delivery
+          return
+        end
+
+        process_delivery(delivery)
+        drain_bus_queue
+      end
+
+
+      # Process a single delivery (called under the processing guard)
+      def process_delivery(delivery)
+        @bus_processing = true
+
+        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}"
+      ensure
+        @bus_processing = false
+      end
+
+
+      # Drain queued deliveries sequentially
+      def drain_bus_queue
+        while (queued = @bus_queue.shift)
+          process_delivery(queued)
+        end
+      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
+end

data/lib/robot_lab/robot/mcp_management.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # MCP client lifecycle and hierarchical tool/MCP resolution.
+    #
+    # Expects the including class to provide:
+    #   @mcp_config, @tools_config, @mcp_clients, @mcp_tools,
+    #   @mcp_initialized, @name, @chat, @local_tools
+    module MCPManagement
+      private
+
+      # Resolve MCP hierarchy: runtime -> robot build -> network -> config
+      def resolve_mcp_hierarchy(runtime_value, network: nil, network_config: nil)
+        parent_value = network_config&.mcp || 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: nil, network_config: nil)
+        parent_value = network_config&.tools || 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
+    end
+  end
+end

data/lib/robot_lab/robot/template_rendering.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RobotLab
+  class Robot < RubyLLM::Agent
+    # Template loading, rendering, and front-matter extraction.
+    #
+    # Expects the including class to provide:
+    #   @chat, @template, @build_context, @name, @name_from_constructor,
+    #   @description, @local_tools, @mcp_config
+    module TemplateRendering
+      # 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
+
+      # 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
+
+      private
+
+      # 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 LLM config from front matter and apply to chat.
+        # Front matter is the base; @config (from constructor kwargs) overrides.
+        fm_config = RunConfig.from_front_matter(parsed.metadata)
+        effective = fm_config.merge(@config)
+        effective.apply_to(@chat)
+
+        # 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 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
+
+
+      def resolve_context(context, network:)
+        case context
+        when Proc then context.call(network: network)
+        when Hash then context
+        else {}
+        end
+      end
+    end
+  end
+end