robot_lab 0.0.1

data/lib/robot_lab/adapters/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Adapters
+    # Base adapter interface for LLM providers
+    #
+    # Adapters handle provider-specific message formatting and response parsing.
+    # Each provider (Anthropic, OpenAI, Gemini) has different API conventions
+    # that the adapter normalizes.
+    #
+    # @abstract Subclass and implement {#format_messages} and {#parse_response}
+    #
+    class Base
+      # @!attribute [r] provider
+      #   @return [Symbol] the provider name
+      attr_reader :provider
+
+      # Creates a new adapter instance.
+      #
+      # @param provider [Symbol] the provider name
+      def initialize(provider)
+        @provider = provider
+      end
+
+      # Format internal messages for the provider's API
+      #
+      # @param messages [Array<Message>] Internal message format
+      # @return [Array<Hash>] Provider-specific message format
+      #
+      def format_messages(messages)
+        raise NotImplementedError, "#{self.class}#format_messages must be implemented"
+      end
+
+      # Parse provider response into internal message format
+      #
+      # @param response [Object] Provider-specific response
+      # @return [Array<Message>] Internal message format
+      #
+      def parse_response(response)
+        raise NotImplementedError, "#{self.class}#parse_response must be implemented"
+      end
+
+      # Format tools for the provider's function calling API
+      #
+      # @param tools [Array<Tool>] Internal tool definitions
+      # @return [Array<Hash>] Provider-specific tool format
+      #
+      def format_tools(tools)
+        tools.map(&:to_json_schema)
+      end
+
+      # Format tool choice for the provider
+      #
+      # @param choice [String, Symbol] "auto", "any", or specific tool name
+      # @return [Object] Provider-specific tool choice
+      #
+      def format_tool_choice(choice)
+        case choice.to_s
+        when "auto" then "auto"
+        when "any" then "required"
+        else { type: "function", function: { name: choice.to_s } }
+        end
+      end
+
+      # Extract system message from messages array
+      #
+      # @param messages [Array<Message>]
+      # @return [String, nil]
+      #
+      def extract_system_message(messages)
+        system_msg = messages.find(&:system?)
+        system_msg&.content
+      end
+
+      # Filter out system messages
+      #
+      # @param messages [Array<Message>]
+      # @return [Array<Message>]
+      #
+      def conversation_messages(messages)
+        messages.reject(&:system?)
+      end
+    end
+  end
+end

data/lib/robot_lab/adapters/gemini.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Adapters
+    # Adapter for Google Gemini models
+    #
+    # Handles Gemini-specific API conventions:
+    # - Role mapping (assistant -> model)
+    # - Contents/parts array structure
+    # - functionCall/functionResponse format
+    #
+    class Gemini < Base
+      # Creates a new Gemini adapter instance.
+      def initialize
+        super(:gemini)
+      end
+
+      # Format messages for Gemini API
+      #
+      # Gemini uses "model" role instead of "assistant" and structures
+      # content as parts arrays.
+      #
+      # @param messages [Array<Message>]
+      # @return [Array<Hash>]
+      #
+      def format_messages(messages)
+        # Gemini handles system messages differently - as system_instruction
+        conversation_messages(messages).map { |msg| format_single_message(msg) }
+      end
+
+      # Parse Gemini response into internal messages
+      #
+      # @param response [RubyLLM::Response]
+      # @return [Array<Message>]
+      #
+      def parse_response(response)
+        messages = []
+
+        # Handle text content
+        if response.content && !response.content.empty?
+          messages << TextMessage.new(
+            role: "assistant",
+            content: response.content,
+            stop_reason: response.tool_calls&.any? ? "tool" : "stop"
+          )
+        end
+
+        # Handle function calls
+        if response.tool_calls&.any?
+          tool_messages = response.tool_calls.map do |id, tool_call|
+            ToolMessage.new(
+              id: id,
+              name: tool_call.name,
+              input: parse_tool_arguments(tool_call.arguments)
+            )
+          end
+
+          messages << ToolCallMessage.new(
+            role: "assistant",
+            tools: tool_messages,
+            stop_reason: "tool"
+          )
+        end
+
+        messages
+      end
+
+      # Format tools for Gemini function declarations
+      #
+      # Gemini doesn't support additionalProperties in schemas
+      #
+      # @param tools [Array<Tool>]
+      # @return [Array<Hash>]
+      #
+      def format_tools(tools)
+        tools.map do |tool|
+          schema = tool.to_json_schema
+          params = clean_schema_for_gemini(schema[:parameters] || { type: "object", properties: {} })
+          {
+            name: schema[:name],
+            description: schema[:description],
+            parameters: params
+          }
+        end
+      end
+
+      # Gemini tool choice format
+      #
+      # @param choice [String, Symbol]
+      # @return [Hash]
+      #
+      def format_tool_choice(choice)
+        case choice.to_s
+        when "auto" then { mode: "AUTO" }
+        when "any" then { mode: "ANY" }
+        when "none" then { mode: "NONE" }
+        else { mode: "ANY", allowed_function_names: [choice.to_s] }
+        end
+      end
+
+      private
+
+      def format_single_message(msg)
+        role = gemini_role(msg.role)
+
+        case msg
+        when TextMessage
+          {
+            role: role,
+            parts: [{ text: msg.content }]
+          }
+        when ToolCallMessage
+          {
+            role: "model",
+            parts: msg.tools.map do |tool|
+              {
+                functionCall: {
+                  name: tool.name,
+                  args: tool.input
+                }
+              }
+            end
+          }
+        when ToolResultMessage
+          {
+            role: "user",
+            parts: [
+              {
+                functionResponse: {
+                  name: msg.tool.name,
+                  response: format_tool_result_content(msg.content)
+                }
+              }
+            ]
+          }
+        else
+          { role: role, parts: [{ text: msg.content.to_s }] }
+        end
+      end
+
+      def gemini_role(role)
+        case role.to_s
+        when "assistant" then "model"
+        when "system" then "user"  # Gemini handles system as system_instruction
+        else role.to_s
+        end
+      end
+
+      def format_tool_result_content(content)
+        case content
+        when Hash
+          content
+        when String
+          { result: content }
+        else
+          { result: content.to_s }
+        end
+      end
+
+      def parse_tool_arguments(arguments)
+        case arguments
+        when String
+          begin
+            JSON.parse(arguments, symbolize_names: true)
+          rescue JSON::ParserError
+            { raw: arguments }
+          end
+        when Hash
+          arguments.transform_keys(&:to_sym)
+        else
+          arguments || {}
+        end
+      end
+
+      # Remove additionalProperties which Gemini doesn't support
+      def clean_schema_for_gemini(schema)
+        return schema unless schema.is_a?(Hash)
+
+        cleaned = schema.dup
+        cleaned.delete(:additionalProperties)
+        cleaned.delete("additionalProperties")
+
+        if cleaned[:properties]
+          cleaned[:properties] = cleaned[:properties].transform_values do |prop|
+            clean_schema_for_gemini(prop)
+          end
+        end
+
+        cleaned
+      end
+    end
+  end
+end

data/lib/robot_lab/adapters/openai.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Adapters
+    # Adapter for OpenAI GPT models
+    #
+    # Handles OpenAI-specific API conventions:
+    # - Function calling format
+    # - Strict mode for structured outputs
+    # - finish_reason to stop_reason mapping
+    #
+    class OpenAI < Base
+      # Creates a new OpenAI adapter instance.
+      def initialize
+        super(:openai)
+      end
+
+      # Format messages for OpenAI API
+      #
+      # @param messages [Array<Message>]
+      # @return [Array<Hash>]
+      #
+      def format_messages(messages)
+        messages.map { |msg| format_single_message(msg) }
+      end
+
+      # Parse OpenAI response into internal messages
+      #
+      # @param response [RubyLLM::Response]
+      # @return [Array<Message>]
+      #
+      def parse_response(response)
+        messages = []
+
+        # Handle text content
+        if response.content && !response.content.empty?
+          messages << TextMessage.new(
+            role: "assistant",
+            content: response.content,
+            stop_reason: response.tool_calls&.any? ? "tool" : "stop"
+          )
+        end
+
+        # Handle tool calls
+        if response.tool_calls&.any?
+          tool_messages = response.tool_calls.map do |id, tool_call|
+            ToolMessage.new(
+              id: id,
+              name: tool_call.name,
+              input: parse_tool_arguments(tool_call.arguments)
+            )
+          end
+
+          messages << ToolCallMessage.new(
+            role: "assistant",
+            tools: tool_messages,
+            stop_reason: "tool"
+          )
+        end
+
+        messages
+      end
+
+      # Format tools for OpenAI function calling
+      #
+      # @param tools [Array<Tool>]
+      # @return [Array<Hash>]
+      #
+      def format_tools(tools)
+        tools.map do |tool|
+          schema = tool.to_json_schema
+          {
+            type: "function",
+            function: {
+              name: schema[:name],
+              description: schema[:description],
+              parameters: schema[:parameters] || { type: "object", properties: {} },
+              strict: tool.strict.nil? ? true : tool.strict
+            }.compact
+          }
+        end
+      end
+
+      # OpenAI tool choice format
+      #
+      # @param choice [String, Symbol]
+      # @return [String, Hash]
+      #
+      def format_tool_choice(choice)
+        case choice.to_s
+        when "auto" then "auto"
+        when "any" then "required"
+        when "none" then "none"
+        else { type: "function", function: { name: choice.to_s } }
+        end
+      end
+
+      private
+
+      def format_single_message(msg)
+        case msg
+        when TextMessage
+          { role: msg.role, content: msg.content }
+        when ToolCallMessage
+          {
+            role: "assistant",
+            content: nil,
+            tool_calls: msg.tools.map do |tool|
+              {
+                id: tool.id,
+                type: "function",
+                function: {
+                  name: tool.name,
+                  arguments: JSON.generate(tool.input)
+                }
+              }
+            end
+          }
+        when ToolResultMessage
+          {
+            role: "tool",
+            tool_call_id: msg.tool.id,
+            content: format_tool_result_content(msg.content)
+          }
+        else
+          { role: msg.role, content: msg.content.to_s }
+        end
+      end
+
+      def format_tool_result_content(content)
+        case content
+        when Hash
+          JSON.generate(content)
+        when String
+          content
+        else
+          content.to_s
+        end
+      end
+
+      def parse_tool_arguments(arguments)
+        case arguments
+        when String
+          # Handle OpenAI's backtick wrapping quirk
+          cleaned = arguments.gsub(/\A```(?:json)?\n?/, "").gsub(/\n?```\z/, "")
+          begin
+            JSON.parse(cleaned, symbolize_names: true)
+          rescue JSON::ParserError
+            { raw: arguments }
+          end
+        when Hash
+          arguments.transform_keys(&:to_sym)
+        else
+          arguments || {}
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/adapters/registry.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module RobotLab
+  module Adapters
+    # Registry for looking up provider adapters
+    #
+    # Maps provider symbols to their adapter classes.
+    #
+    # @example
+    #   adapter = Registry.for(:anthropic)
+    #   adapter.format_messages(messages)
+    #
+    module Registry
+      # @return [Hash<Symbol, Class>] mapping of provider symbols to adapter classes
+      ADAPTERS = {
+        anthropic: Anthropic,
+        openai: OpenAI,
+        gemini: Gemini,
+        # Azure uses OpenAI adapter
+        azure_openai: OpenAI,
+        # Grok uses OpenAI adapter
+        grok: OpenAI,
+        # Ollama uses OpenAI adapter
+        ollama: OpenAI,
+        # OpenRouter uses OpenAI adapter
+        openrouter: OpenAI,
+        # Bedrock uses Anthropic adapter
+        bedrock: Anthropic,
+        # VertexAI uses Gemini adapter
+        vertexai: Gemini
+      }.freeze
+
+      class << self
+        # Get adapter for a provider
+        #
+        # @param provider [Symbol, String] Provider name
+        # @return [Base] Adapter instance
+        # @raise [ArgumentError] If provider not found
+        #
+        def for(provider)
+          provider_sym = provider.to_s.downcase.gsub("-", "_").to_sym
+          adapter_class = ADAPTERS[provider_sym]
+
+          unless adapter_class
+            raise ArgumentError, "Unknown provider: #{provider}. " \
+                                 "Available providers: #{available.join(', ')}"
+          end
+
+          adapter_class.new
+        end
+
+        # List available providers
+        #
+        # @return [Array<Symbol>]
+        #
+        def available
+          ADAPTERS.keys
+        end
+
+        # Check if provider is supported
+        #
+        # @param provider [Symbol, String]
+        # @return [Boolean]
+        #
+        def supports?(provider)
+          provider_sym = provider.to_s.downcase.gsub("-", "_").to_sym
+          ADAPTERS.key?(provider_sym)
+        end
+
+        # Register a custom adapter
+        #
+        # @param provider [Symbol] Provider name
+        # @param adapter_class [Class] Adapter class
+        #
+        def register(provider, adapter_class)
+          ADAPTERS[provider.to_sym] = adapter_class
+        end
+      end
+    end
+  end
+end

data/lib/robot_lab/configuration.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Global configuration for RobotLab
+  #
+  # @example
+  #   RobotLab.configure do |config|
+  #     config.default_provider = :anthropic
+  #     config.default_model = "claude-sonnet-4"
+  #     config.template_path = "app/prompts"
+  #     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  #
+  #     # Global MCP servers available to all networks and robots
+  #     config.mcp = [
+  #       { name: "github", transport: { type: "stdio", command: "github-mcp" } }
+  #     ]
+  #
+  #     # Global tools whitelist (only these tools are available)
+  #     config.tools = %w[search_code create_issue]
+  #   end
+  #
+  class Configuration
+    # @!attribute [rw] default_provider
+    #   @return [Symbol] the default LLM provider (defaults to :anthropic)
+    # @!attribute [rw] default_model
+    #   @return [String] the default model to use (defaults to "claude-sonnet-4")
+    # @!attribute [rw] max_iterations
+    #   @return [Integer] maximum robot iterations per network run (defaults to 10)
+    # @!attribute [rw] max_tool_iterations
+    #   @return [Integer] maximum tool iterations per robot run (defaults to 10)
+    # @!attribute [rw] streaming_enabled
+    #   @return [Boolean] whether streaming is enabled by default (defaults to true)
+    # @!attribute [rw] logger
+    #   @return [Logger] the logger instance
+    # @!attribute [rw] mcp
+    #   @return [Symbol, Array] global MCP server configuration (:none, :inherit, or array)
+    # @!attribute [rw] tools
+    #   @return [Symbol, Array] global tools whitelist (:none, :inherit, or array)
+    attr_accessor :default_provider,
+                  :default_model,
+                  :max_iterations,
+                  :max_tool_iterations,
+                  :streaming_enabled,
+                  :logger,
+                  :mcp,
+                  :tools
+
+    # Creates a new Configuration with default values.
+    def initialize
+      @default_provider = :anthropic
+      @default_model = "claude-sonnet-4"
+      @max_iterations = 10
+      @max_tool_iterations = 10
+      @streaming_enabled = true
+      @logger = default_logger
+      @template_path = nil
+      @mcp = :none
+      @tools = :none
+    end
+
+    # Sets the Anthropic API key.
+    #
+    # @param key [String] the API key
+    # @return [void]
+    def anthropic_api_key=(key)
+      RubyLLM.configure { |c| c.anthropic_api_key = key }
+    end
+
+    # Sets the OpenAI API key.
+    #
+    # @param key [String] the API key
+    # @return [void]
+    def openai_api_key=(key)
+      RubyLLM.configure { |c| c.openai_api_key = key }
+    end
+
+    # Sets the Google Gemini API key.
+    #
+    # @param key [String] the API key
+    # @return [void]
+    def gemini_api_key=(key)
+      RubyLLM.configure { |c| c.gemini_api_key = key }
+    end
+
+    # Sets the AWS Bedrock API key.
+    #
+    # @param key [String] the API key
+    # @return [void]
+    def bedrock_api_key=(key)
+      RubyLLM.configure { |c| c.bedrock_api_key = key }
+    end
+
+    # Sets the OpenRouter API key.
+    #
+    # @param key [String] the API key
+    # @return [void]
+    def openrouter_api_key=(key)
+      RubyLLM.configure { |c| c.openrouter_api_key = key }
+    end
+
+    # Set the template path and configure ruby_llm-template
+    #
+    # @param path [String] Path to the templates directory
+    #
+    def template_path=(path)
+      @template_path = path
+      configure_template_library if path
+    end
+
+    # Returns the template path.
+    #
+    # @return [String] the configured template path or default
+    def template_path
+      @template_path || default_template_path
+    end
+
+    private
+
+    def configure_template_library
+      require "ruby_llm/template"
+      RubyLLM::Template.configure do |config|
+        config.template_directory = @template_path
+      end
+    end
+
+    def default_template_path
+      if defined?(Rails) && Rails.root
+        Rails.root.join("app", "prompts").to_s
+      else
+        "prompts"
+      end
+    end
+
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger
+      else
+        require "logger"
+        Logger.new($stdout, level: Logger::INFO)
+      end
+    end
+  end
+end

data/lib/robot_lab/error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module RobotLab
+  # Base error class for all RobotLab errors.
+  #
+  # All RobotLab-specific exceptions inherit from this class.
+  class Error < StandardError; end
+
+  # Raised when configuration is invalid or missing required values.
+  #
+  # @example
+  #   raise ConfigurationError, "API key not set"
+  class ConfigurationError < Error; end
+
+  # Raised when a requested tool is not found in the manifest.
+  #
+  # @example
+  #   raise ToolNotFoundError, "Tool 'unknown_tool' not found"
+  class ToolNotFoundError < Error; end
+
+  # Raised when LLM inference fails.
+  #
+  # @example
+  #   raise InferenceError, "API request failed: 429 Too Many Requests"
+  class InferenceError < Error; end
+
+  # Raised when MCP communication fails.
+  #
+  # @example
+  #   raise MCPError, "Connection to MCP server refused"
+  class MCPError < Error; end
+end