activeagent 1.0.0 → 1.0.2

data/lib/active_agent/providers/concerns/tool_choice_clearing.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Provides unified logic for clearing tool_choice after tool execution.
+    #
+    # When a tool_choice is set to "required" or to a specific tool name,
+    # it forces the model to use that tool. After the tool is executed,
+    # we need to clear the tool_choice to prevent infinite loops where
+    # the model keeps calling the same tool repeatedly.
+    #
+    # Each provider implements:
+    # - `extract_used_function_names`: Returns array of tool names that have been called
+    # - `tool_choice_forces_required?`: Returns true if tool_choice forces any tool use
+    # - `tool_choice_forces_specific?`: Returns [true, name] if tool_choice forces specific tool
+    module ToolChoiceClearing
+      extend ActiveSupport::Concern
+
+      # @api private
+      def prepare_prompt_request_tools
+        return unless request.tool_choice
+
+        functions_used = extract_used_function_names
+
+        # Clear if forcing required and any tool was used
+        if tool_choice_forces_required? && functions_used.any?
+          request.tool_choice = nil
+          return
+        end
+
+        # Clear if forcing specific tool and that tool was used
+        forces_specific, tool_name = tool_choice_forces_specific?
+        if forces_specific && tool_name && functions_used.include?(tool_name)
+          request.tool_choice = nil
+        end
+      end
+
+      private
+
+      # Extracts the list of function names that have been called.
+      #
+      # @return [Array<String>] function names
+      def extract_used_function_names
+        raise NotImplementedError, "#{self.class} must implement #extract_used_function_names"
+      end
+
+      # Returns true if tool_choice forces any tool to be used (e.g., "required", "any").
+      #
+      # @return [Boolean]
+      def tool_choice_forces_required?
+        raise NotImplementedError, "#{self.class} must implement #tool_choice_forces_required?"
+      end
+
+      # Returns [true, tool_name] if tool_choice forces a specific tool, [false, nil] otherwise.
+      #
+      # @return [Array<Boolean, String|nil>]
+      def tool_choice_forces_specific?
+        raise NotImplementedError, "#{self.class} must implement #tool_choice_forces_specific?"
+      end
+    end
+  end
+end

data/lib/active_agent/providers/gemini/_types.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "../open_ai/chat/_types"
+require_relative "../open_ai/embedding/_types"
+
+module ActiveAgent
+  module Providers
+    module Gemini
+      # Reuse OpenAI Chat request type (same API format)
+      RequestType = OpenAI::Chat::RequestType
+
+      # Reuse OpenAI Embedding types (same API format)
+      module Embedding
+        RequestType = OpenAI::Embedding::RequestType
+      end
+    end
+  end
+end

data/lib/active_agent/providers/gemini/options.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+
+module ActiveAgent
+  module Providers
+    module Gemini
+      # Configuration options for Gemini provider
+      #
+      # Extends OpenAI::Options with Gemini-specific settings including
+      # the default base URL for Gemini's OpenAI-compatible API endpoint.
+      #
+      # @example Basic configuration
+      #   options = Options.new(api_key: 'your-api-key')
+      #
+      # @example With environment variable
+      #   # Set GEMINI_API_KEY or GOOGLE_API_KEY
+      #   options = Options.new({})
+      #
+      # @see https://ai.google.dev/gemini-api/docs/openai
+      class Options < ActiveAgent::Providers::OpenAI::Options
+        GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta/openai/"
+
+        attribute :base_url, :string, fallback: GEMINI_BASE_URL
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs[:api_key] ||
+            kwargs[:access_token] ||
+            ENV["GEMINI_API_KEY"] ||
+            ENV["GOOGLE_API_KEY"]
+        end
+
+        # Not used as part of Gemini
+        def resolve_organization_id(kwargs) = nil
+        def resolve_project_id(kwargs)      = nil
+      end
+    end
+  end
+end

data/lib/active_agent/providers/gemini_provider.rb

@@ -0,0 +1,94 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai_provider"
+require_relative "gemini/_types"
+
+module ActiveAgent
+  module Providers
+    # Provides access to Google's Gemini API via OpenAI-compatible endpoint.
+    #
+    # Extends OpenAI provider to work with Gemini's OpenAI-compatible API,
+    # enabling access to Gemini models through a familiar interface.
+    #
+    # @see OpenAI::ChatProvider
+    # @see https://ai.google.dev/gemini-api/docs/openai
+    class GeminiProvider < OpenAI::ChatProvider
+      # @return [String]
+      def self.service_name
+        "Gemini"
+      end
+
+      # @return [Class]
+      def self.options_klass
+        namespace::Options
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.prompt_request_type
+        namespace::RequestType.new
+      end
+
+      # @return [ActiveModel::Type::Value]
+      def self.embed_request_type
+        namespace::Embedding::RequestType.new
+      end
+
+      protected
+
+      # Executes chat completion request with Gemini-specific error handling.
+      #
+      # @see OpenAI::ChatProvider#api_prompt_execute
+      # @param parameters [Hash]
+      # @return [Object, nil] response object or nil for streaming
+      # @raise [OpenAI::Errors::APIConnectionError] when Gemini API unreachable
+      def api_prompt_execute(parameters)
+        super
+
+      rescue ::OpenAI::Errors::APIConnectionError => exception
+        log_connection_error(exception)
+        raise exception
+      end
+
+      # Executes embedding request with Gemini-specific error handling.
+      #
+      # @param parameters [Hash]
+      # @return [Hash] symbolized API response
+      # @raise [OpenAI::Errors::APIConnectionError] when Gemini API unreachable
+      def api_embed_execute(parameters)
+        client.embeddings.create(**parameters).as_json.deep_symbolize_keys
+      rescue ::OpenAI::Errors::APIConnectionError => exception
+        log_connection_error(exception)
+        raise exception
+      end
+
+      # Merges streaming delta into the message with role cleanup.
+      #
+      # Overrides parent to handle Gemini's role copying behavior which duplicates
+      # the role field in every streaming chunk, requiring manual cleanup to prevent
+      # message corruption.
+      #
+      # @see OpenAI::ChatProvider#message_merge_delta
+      # @param message [Hash]
+      # @param delta [Hash]
+      # @return [Hash]
+      def message_merge_delta(message, delta)
+        message[:role] = delta.delete(:role) if delta[:role]
+
+        hash_merge_delta(message, delta)
+      end
+
+      # Logs connection failures with Gemini API details for debugging.
+      #
+      # @param error [Exception]
+      # @return [void]
+      def log_connection_error(error)
+        instrument("connection_error.provider.active_agent",
+                  uri_base: options.base_url,
+                  exception: error.class,
+                  message: error.message)
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai/chat/transforms.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "active_support/core_ext/hash/keys"
+require "uri"
 
 module ActiveAgent
   module Providers
@@ -24,8 +25,8 @@ module ActiveAgent
             # Normalizes all request parameters for OpenAI Chat API
             #
             # Handles instructions mapping to developer messages, message normalization,
-            # and response_format conversion. This is the main entry point for parameter
-            # transformation.
+            # tools normalization, and response_format conversion. This is the main entry point
+            # for parameter transformation.
             #
             # @param params [Hash]
             # @return [Hash] normalized parameters
@@ -41,6 +42,12 @@ module ActiveAgent
               # Normalize messages for gem compatibility
               params[:messages] = normalize_messages(params[:messages]) if params[:messages]
 
+              # Normalize tools from common format to Chat API format
+              params[:tools] = normalize_tools(params[:tools]) if params[:tools]
+
+              # Normalize tool_choice from common format
+              params[:tool_choice] = normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
               # Normalize response_format if present
               params[:response_format] = normalize_response_format(params[:response_format]) if params[:response_format]
 
@@ -68,7 +75,8 @@ module ActiveAgent
                 messages.each do |msg|
                   normalized = normalize_message(msg)
 
-                  if grouped.empty? || grouped.last.role != normalized.role
+                  # Don't merge tool messages - each needs its own tool_call_id
+                  if grouped.empty? || grouped.last.role != normalized.role || normalized.role.to_s == "tool"
                     grouped << normalized
                   else
                     # Merge consecutive same-role messages
@@ -117,10 +125,19 @@ module ActiveAgent
                     { type: "text", text: msg_hash[:text] },
                     { type: "image_url", image_url: { url: msg_hash[:image] } }
                   ]
+                elsif msg_hash.key?(:text) && msg_hash.key?(:document)
+                  # Shorthand with both text and document: { text: "...", document: "url" }
+                  [
+                    { type: "text", text: msg_hash[:text] },
+                    build_file_content(msg_hash[:document])
+                  ]
                 elsif msg_hash.key?(:image)
                   # Shorthand with only image: { image: "url" }
                   # Text comes from adjacent prompt arguments
                   [ { type: "image_url", image_url: { url: msg_hash[:image] } } ]
+                elsif msg_hash.key?(:document)
+                  # Shorthand with only document: { document: "url" }
+                  [ build_file_content(msg_hash[:document]) ]
                 elsif msg_hash.key?(:text)
                   # Shorthand: { text: "..." } or { role: "...", text: "..." }
                   msg_hash[:text]
@@ -130,13 +147,39 @@ module ActiveAgent
                 end
 
                 # Create appropriate message param based on role and content
-                extra_params = msg_hash.except(:role, :content, :text, :image)
+                extra_params = msg_hash.except(:role, :content, :text, :image, :document)
                 create_message_param(role, content, extra_params)
               else
                 raise ArgumentError, "Cannot normalize #{message.class} to message"
               end
             end
 
+            # Builds a file content block for the Chat API file type
+            #
+            # Handles both URL and data URI formats:
+            # - URL: "http://example.com/document.pdf" → { type: "file", file: { filename: "...", url: "..." } }
+            # - Data URI: "data:application/pdf;base64,..." → { type: "file", file: { filename: "...", file_data: "..." } }
+            #
+            # @param document [String] URL or data URI
+            # @return [Hash] file content block
+            def build_file_content(document)
+              if document.start_with?("data:")
+                # Data URI - extract or infer filename from media type
+                media_type = document.match(%r{\Adata:([^;,]+)})&.[](1) || "application/octet-stream"
+                extension = media_type.split("/").last&.gsub(/[^a-zA-Z0-9]/, "_") || "bin"
+                filename = "document.#{extension}"
+                { type: "file", file: { filename: filename, file_data: document } }
+              else
+                # Regular URL
+                filename = File.basename(URI.parse(document).path.to_s)
+                filename = "document.pdf" if filename.empty?
+                { type: "file", file: { filename: filename, url: document } }
+              end
+            rescue URI::Error
+              # Fallback for invalid URLs
+              { type: "file", file: { filename: "document.pdf", url: document } }
+            end
+
             # Creates the appropriate gem message param class for the given role
             #
             # @param role [String] message role (developer, system, user, assistant, tool, function)
@@ -307,6 +350,79 @@ module ActiveAgent
               end
             end
 
+            # Normalizes tools from common format to OpenAI Chat API format.
+            #
+            # Accepts tools in multiple formats:
+            # - Common format: `{name: "...", description: "...", parameters: {...}}`
+            # - Common format alt: `{name: "...", description: "...", input_schema: {...}}`
+            # - Nested format: `{type: "function", function: {name: "...", parameters: {...}}}`
+            #
+            # Always outputs nested Chat API format: `{type: "function", function: {...}}`
+            #
+            # @param tools [Array<Hash>]
+            # @return [Array<Hash>]
+            def normalize_tools(tools)
+              return tools unless tools.is_a?(Array)
+
+              tools.map do |tool|
+                tool_hash = tool.is_a?(Hash) ? tool.deep_symbolize_keys : tool
+
+                # Already in nested format - return as is
+                if tool_hash[:type] == "function" && tool_hash[:function]
+                  tool_hash
+                # Common format - convert to nested format
+                elsif tool_hash[:name]
+                  {
+                    type: "function",
+                    function: {
+                      name: tool_hash[:name],
+                      description: tool_hash[:description],
+                      parameters: tool_hash[:parameters] || tool_hash[:input_schema]
+                    }.compact
+                  }
+                else
+                  tool_hash
+                end
+              end
+            end
+
+            # Normalizes tool_choice from common format to OpenAI Chat API format.
+            #
+            # Accepts:
+            # - "auto" (common) → "auto" (passthrough)
+            # - "required" (common) → "required" (passthrough)
+            # - `{name: "..."}` (common) → `{type: "function", function: {name: "..."}}`
+            # - Already nested format → passthrough
+            #
+            # @param tool_choice [String, Hash, Symbol]
+            # @return [String, Hash, Symbol]
+            def normalize_tool_choice(tool_choice)
+              case tool_choice
+              when "auto", :auto, "required", :required
+                # Passthrough - Chat API accepts these directly
+                tool_choice.to_s
+              when Hash
+                tool_choice_hash = tool_choice.deep_symbolize_keys
+
+                # Already in nested format with type and function keys
+                if tool_choice_hash[:type] == "function" && tool_choice_hash[:function]
+                  tool_choice_hash
+                # Common format with just name - convert to nested format
+                elsif tool_choice_hash[:name]
+                  {
+                    type: "function",
+                    function: {
+                      name: tool_choice_hash[:name]
+                    }
+                  }
+                else
+                  tool_choice_hash
+                end
+              else
+                tool_choice
+              end
+            end
+
             # Normalizes instructions to developer message format
             #
             # Converts instructions into developer messages with proper content structure.

data/lib/active_agent/providers/open_ai/chat_provider.rb

@@ -12,6 +12,8 @@ module ActiveAgent
       # @see Base
       # @see https://platform.openai.com/docs/api-reference/chat
       class ChatProvider < Base
+        include ToolChoiceClearing
+
         # @return [Class] the options class for this provider
         def self.options_klass
           Options
@@ -30,6 +32,42 @@ module ActiveAgent
           client.chat.completions
         end
 
+        # @see BaseProvider#prepare_prompt_request
+        # @return [Request]
+        def prepare_prompt_request
+          prepare_prompt_request_tools
+          super
+        end
+
+        # Extracts function names from Chat API tool_calls in assistant messages.
+        #
+        # @return [Array<String>]
+        def extract_used_function_names
+          message_stack
+            .select { |msg| msg[:role] == "assistant" && msg[:tool_calls] }
+            .flat_map { |msg| msg[:tool_calls] }
+            .map { |tc| tc.dig(:function, :name) }
+            .compact
+        end
+
+        # Returns true if tool_choice == "required".
+        #
+        # @return [Boolean]
+        def tool_choice_forces_required?
+          request.tool_choice == "required"
+        end
+
+        # Returns [true, name] if tool_choice is a hash with nested function name.
+        #
+        # @return [Array<Boolean, String|nil>]
+        def tool_choice_forces_specific?
+          if request.tool_choice.is_a?(Hash)
+            [ true, request.tool_choice.dig(:function, :name) ]
+          else
+            [ false, nil ]
+          end
+        end
+
         # @see BaseProvider#api_response_normalize
         # @param api_response [OpenAI::Models::ChatCompletion]
         # @return [Hash] normalized response hash
@@ -57,6 +95,8 @@ module ActiveAgent
         def process_stream_chunk(api_response_event)
           instrument("stream_chunk.active_agent")
 
+          broadcast_stream_open
+
           # Called Multiple Times: [Chunk<T>, T]<Content, ToolsCall>
           case api_response_event.type
           when :chunk

data/lib/active_agent/providers/open_ai/responses/request.rb

@@ -73,10 +73,25 @@ module ActiveAgent
             # Step 6: Normalize input content for gem compatibility
             params[:input] = Responses::Transforms.normalize_input(params[:input]) if params[:input]
 
-            # Step 7: Create gem model - delegates to OpenAI gem
+            # Step 7: Normalize tools and tool_choice from common format
+            params[:tools] = Responses::Transforms.normalize_tools(params[:tools]) if params[:tools]
+            params[:tool_choice] = Responses::Transforms.normalize_tool_choice(params[:tool_choice]) if params[:tool_choice]
+
+            # Step 8: Normalize MCP servers from common format (mcps parameter)
+            # OpenAI treats MCP servers as a special type of tool in the tools array
+            mcp_param = params[:mcps] || params[:mcp_servers]
+            if mcp_param&.any?
+              normalized_mcp_tools = Responses::Transforms.normalize_mcp_servers(mcp_param)
+              params.delete(:mcps)
+              params.delete(:mcp_servers)
+              # Merge MCP servers into tools array
+              params[:tools] = (params[:tools] || []) + normalized_mcp_tools
+            end
+
+            # Step 9: Create gem model - delegates to OpenAI gem
             gem_model = ::OpenAI::Models::Responses::ResponseCreateParams.new(**params)
 
-            # Step 8: Delegate all method calls to gem model
+            # Step 10: Delegate all method calls to gem model
             super(gem_model)
           rescue ArgumentError => e
             # Re-raise with more context

data/lib/active_agent/providers/open_ai/responses/transforms.rb

@@ -21,6 +21,141 @@ module ActiveAgent
               JSON.parse(gem_object.to_json, symbolize_names: true)
             end
 
+            # Normalizes tools from common format to OpenAI Responses API format.
+            #
+            # Accepts tools in multiple formats:
+            # - Common format: `{name: "...", description: "...", parameters: {...}}`
+            # - Nested format: `{type: "function", function: {name: "...", ...}}`
+            # - Responses format: `{type: "function", name: "...", parameters: {...}}`
+            #
+            # Always outputs flat Responses API format.
+            #
+            # @param tools [Array<Hash>]
+            # @return [Array<Hash>]
+            def normalize_tools(tools)
+              return tools unless tools.is_a?(Array)
+
+              tools.map do |tool|
+                tool_hash = tool.is_a?(Hash) ? tool.deep_symbolize_keys : tool
+
+                # If already in Responses format (flat with type, name, parameters), return as-is
+                if tool_hash[:type] == "function" && tool_hash[:name]
+                  next tool_hash
+                end
+
+                # If in nested Chat API format, flatten it
+                if tool_hash[:type] == "function" && tool_hash[:function]
+                  func = tool_hash[:function]
+                  next {
+                    type: "function",
+                    name: func[:name],
+                    description: func[:description],
+                    parameters: func[:parameters] || func[:input_schema]
+                  }.compact
+                end
+
+                # If in common format (no type field), convert to Responses format
+                if tool_hash[:name] && !tool_hash[:type]
+                  next {
+                    type: "function",
+                    name: tool_hash[:name],
+                    description: tool_hash[:description],
+                    parameters: tool_hash[:parameters] || tool_hash[:input_schema]
+                  }.compact
+                end
+
+                # Pass through other formats
+                tool_hash
+              end
+            end
+
+            # Normalizes MCP servers from common format to OpenAI Responses API format.
+            #
+            # Common format:
+            #   {name: "stripe", url: "https://...", authorization: "token"}
+            # OpenAI format:
+            #   {type: "mcp", server_label: "stripe", server_url: "https://...", authorization: "token"}
+            #
+            # @param mcp_servers [Array<Hash>]
+            # @return [Array<Hash>]
+            def normalize_mcp_servers(mcp_servers)
+              return mcp_servers unless mcp_servers.is_a?(Array)
+
+              mcp_servers.map do |server|
+                server_hash = server.is_a?(Hash) ? server.deep_symbolize_keys : server
+
+                # If already in OpenAI format (has type: "mcp" and server_label), return as-is
+                if server_hash[:type] == "mcp" && server_hash[:server_label]
+                  next server_hash
+                end
+
+                # Convert common format to OpenAI format
+                result = {
+                  type: "mcp",
+                  server_label: server_hash[:name] || server_hash[:server_label],
+                  server_url: server_hash[:url] || server_hash[:server_url]
+                }
+
+                # Keep authorization field (OpenAI uses 'authorization', not 'authorization_token')
+                if server_hash[:authorization]
+                  result[:authorization] = server_hash[:authorization]
+                end
+
+                result.compact
+              end
+            end
+
+            # Normalizes tool_choice from common format to OpenAI Responses API format.
+            #
+            # Responses API uses flat format for specific tool choice, unlike Chat API's nested format.
+            # Must return gem model objects for proper serialization.
+            #
+            # Maps:
+            # - "required" → :required symbol (force tool use)
+            # - "auto" → :auto symbol (let model decide)
+            # - { name: "..." } → ToolChoiceFunction model object
+            #
+            # @param tool_choice [String, Hash, Object]
+            # @return [Symbol, Object] Symbol or gem model object
+            def normalize_tool_choice(tool_choice)
+              # If already a gem model object, return as-is
+              return tool_choice if tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceFunction) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceAllowed) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceTypes) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceMcp) ||
+                                     tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceCustom)
+
+              case tool_choice
+              when "required"
+                :required  # Return as symbol
+              when "auto"
+                :auto  # Return as symbol
+              when "none"
+                :none  # Return as symbol
+              when Hash
+                choice_hash = tool_choice.deep_symbolize_keys
+
+                # If already in proper format with type, try to create gem model
+                if choice_hash[:type] == "function" && choice_hash[:name]
+                  # Create ToolChoiceFunction gem model object
+                  ::OpenAI::Models::Responses::ToolChoiceFunction.new(
+                    type: :function,
+                    name: choice_hash[:name]
+                  )
+                # Convert { name: "..." } to ToolChoiceFunction model
+                elsif choice_hash[:name] && !choice_hash[:type]
+                  ::OpenAI::Models::Responses::ToolChoiceFunction.new(
+                    type: :function,
+                    name: choice_hash[:name]
+                  )
+                else
+                  choice_hash
+                end
+              else
+                tool_choice
+              end
+            end
+
             # Simplifies input for cleaner API requests
             #
             # Unwraps single-element arrays:

data/lib/active_agent/providers/open_ai/responses_provider.rb

@@ -13,6 +13,8 @@ module ActiveAgent
       # @see Base
       # @see https://platform.openai.com/docs/api-reference/responses
       class ResponsesProvider < Base
+        include ToolChoiceClearing
+
         # @return [Class]
         def self.options_klass
           Options
@@ -25,6 +27,42 @@ module ActiveAgent
 
         protected
 
+        # @see BaseProvider#prepare_prompt_request
+        # @return [Request]
+        def prepare_prompt_request
+          prepare_prompt_request_tools
+
+          super
+        end
+
+        # Extracts function names from Responses API function_call items.
+        #
+        # @return [Array<String>]
+        def extract_used_function_names
+          message_stack
+            .select { |item| item[:type] == "function_call" }
+            .map { |item| item[:name] }
+            .compact
+        end
+
+        # Returns true if tool_choice == :required.
+        #
+        # @return [Boolean]
+        def tool_choice_forces_required?
+          request.tool_choice == :required
+        end
+
+        # Returns [true, name] if tool_choice is a ToolChoiceFunction model object.
+        #
+        # @return [Array<Boolean, String|nil>]
+        def tool_choice_forces_specific?
+          if request.tool_choice.is_a?(::OpenAI::Models::Responses::ToolChoiceFunction)
+            [ true, request.tool_choice.name ]
+          else
+            [ false, nil ]
+          end
+        end
+
         # @return [Object] OpenAI client's responses endpoint
         def api_prompt_executer
           client.responses