activeagent 1.0.0.rc1 → 1.0.1

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

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/keys"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      module Responses
+        # Provides transformation methods for normalizing response parameters
+        # to OpenAI gem's native format
+        #
+        # Handles input normalization, message conversion, and response format
+        # transformation for the Responses API.
+        module Transforms
+          class << self
+            # Converts gem model object to hash via JSON round-trip
+            #
+            # @param gem_object [Object]
+            # @return [Hash] with symbolized keys
+            def gem_to_hash(gem_object)
+              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:
+            # - `["text"]` → `"text"`
+            # - `[{type: "input_text", text: "..."}]` → `"..."`
+            # - `[{role: "user", content: "..."}]` → `"..."`
+            #
+            # @param input [Array, String, Hash]
+            # @return [String, Array, Hash]
+            def simplify_input(input)
+              return input unless input.is_a?(Array)
+
+              # Single string element - unwrap it
+              if input.size == 1 && input[0].is_a?(String)
+                return input[0]
+              end
+
+              # Single content object {type: "input_text", text: "..."} - unwrap to string
+              if input.size == 1 &&
+                 input[0].is_a?(Hash) &&
+                 input[0][:type] == "input_text" &&
+                 input[0][:text].is_a?(String) &&
+                 input[0].keys.sort == [ :text, :type ]
+                return input[0][:text]
+              end
+
+              # Single message with string content - simplify to string
+              if input.size == 1 &&
+                 input[0].is_a?(Hash) &&
+                 input[0][:role] == "user" &&
+                 input[0][:content].is_a?(String)
+                return input[0][:content]
+              end
+
+              input
+            end
+
+            # Normalizes response_format to OpenAI Responses API text parameter
+            #
+            # Maps common response_format structures to Responses API format.
+            # Returns ResponseTextConfig object to preserve proper nesting.
+            #
+            # @param format [Hash, Symbol, String]
+            # @return [OpenAI::Models::Responses::ResponseTextConfig]
+            def normalize_response_format(format)
+              text_hash = case format
+              when Hash
+                if format[:type] == "json_schema" || format[:type] == :json_schema
+                  # json_schema format: map to Responses API structure
+                  {
+                    format: {
+                      type: "json_schema",
+                      name: format[:name] || format[:json_schema]&.dig(:name),
+                      schema: format[:schema] || format[:json_schema]&.dig(:schema),
+                      strict: format[:strict] || format[:json_schema]&.dig(:strict)
+                    }.compact
+                  }
+                elsif format[:type] == "json_object" || format[:type] == :json_object
+                  # json_object format
+                  { format: { type: "json_object" } }
+                elsif format[:type]
+                  # Other simple type formats (text, etc.) - wrap in format key
+                  { format: { type: format[:type].to_s } }
+                else
+                  # Pass through other hash formats (already has format key or complex structure)
+                  format
+                end
+              when Symbol, String
+                # Simple format types
+                { format: { type: format.to_s } }
+              else
+                format
+              end
+
+              # Convert hash to ResponseTextConfig object to preserve nesting
+              ::OpenAI::Models::Responses::ResponseTextConfig.new(**text_hash)
+            end
+
+            # Normalizes input/messages to gem-compatible format
+            #
+            # Handles various input formats:
+            # - `"text"` → string (passthrough)
+            # - `{role: "user", content: "..."}` → wrapped in array
+            # - `[{text: "..."}, {image: "url"}]` → wrapped as user message with content array
+            # - `["msg1", "msg2"]` → array of user messages
+            #
+            # @param input [String, Hash, Array, Object]
+            # @return [String, Array<Hash>]
+            def normalize_input(input)
+              # String inputs pass through unchanged
+              return input if input.is_a?(String)
+
+              # Single hash should be wrapped in an array
+              if input.is_a?(Hash)
+                return [ normalize_message(input) ]
+              end
+
+              # Handle arrays
+              return input unless input.respond_to?(:map)
+
+              # Check if this is an array of content items (strings or text/image/document hashes)
+              # Content items don't have a :role key (messages do)
+              # BUT NOT a single string (which should have been caught above)
+              all_content_items = input.size > 1 && input.all? do |item|
+                if item.is_a?(String)
+                  true
+                elsif item.is_a?(Hash)
+                  # If it has a role, it's a message, not a content item
+                  !item.key?(:role) && (item.key?(:text) || item.key?(:image) || item.key?(:document))
+                else
+                  false
+                end
+              end
+
+              if all_content_items
+                # These are multiple content items, wrap in a user message
+                content = input.map { |item| normalize_message(item) }
+                return [ { role: "user", content: content } ]
+              end
+
+              # Otherwise treat as array of messages
+              input.map { |item| normalize_message(item, context: :input) }
+            end
+
+            # Normalizes a single message to hash format
+            #
+            # Handles shorthand formats:
+            # - `{text: "..."}` → user message
+            # - `{image: "url"}` → input_image content part
+            # - `{document: "url"}` → input_file content part
+            #
+            # @param message [Hash, String, Object]
+            # @param context [Symbol] :input for messages, :content for content parts
+            # @return [Hash, String]
+            def normalize_message(message, context: :content)
+              # If it's our custom model object, serialize it
+              if message.respond_to?(:serialize)
+                message.serialize
+              elsif message.is_a?(Hash)
+                # If it has a role, it's a message - convert :text to :content
+                if message.key?(:role)
+                  normalized = message.dup
+                  if normalized.key?(:text) && !normalized.key?(:content)
+                    normalized[:content] = normalized.delete(:text)
+                  end
+                  return normalized
+                end
+
+                # Expand shorthand formats to full structures for content items
+                if message.key?(:image)
+                  { type: "input_image", image_url: message[:image] }
+                elsif message.key?(:document)
+                  document_value = message[:document]
+                  if document_value.start_with?("data:")
+                    { type: "input_file", filename: "document.pdf", file_data: document_value }
+                  else
+                    { type: "input_file", file_url: document_value }
+                  end
+                elsif message.key?(:text) && message.size == 1
+                  # Single :text key without :role - treat as user message
+                  { role: "user", content: message[:text] }
+                elsif message.key?(:text)
+                  # Bare text content item with other keys
+                  { type: "input_text", text: message[:text] }
+                else
+                  message
+                end
+              elsif message.is_a?(String)
+                # Context matters: in input array, strings become messages; in content array, they become input_text
+                if context == :input
+                  { role: "user", content: message }
+                else
+                  { type: "input_text", text: message }
+                end
+              else
+                # Pass through anything else
+                message
+              end
+            end
+
+            # Cleans up serialized request for API submission
+            #
+            # Removes default values and simplifies input where possible.
+            #
+            # @param hash [Hash] serialized request
+            # @param defaults [Hash] default values to remove
+            # @param gem_object [Object] original gem object
+            # @return [Hash] cleaned request hash
+            def cleanup_serialized_request(hash, defaults, gem_object)
+              # Remove default values that shouldn't be in the request body
+              defaults.each do |key, value|
+                hash.delete(key) if hash[key] == value
+              end
+
+              # Simplify input when possible for cleaner API requests
+              hash[:input] = simplify_input(hash[:input]) if hash[:input]
+
+              hash
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,17 +1,20 @@
 require_relative "_base"
 require_relative "responses/_types"
+require_relative "responses/transforms"
 
 module ActiveAgent
   module Providers
     module OpenAI
-      # Handles OpenAI's Responses API with improved streaming and structured function calling.
+      # Provider implementation for OpenAI's Responses API
       #
-      # Uses the newer responses endpoint instead of the chat completions endpoint
-      # for more reliable streaming and better structured interactions with function calls.
+      # Uses the responses endpoint for improved streaming and structured function
+      # calling compared to the chat completions endpoint.
       #
       # @see Base
       # @see https://platform.openai.com/docs/api-reference/responses
       class ResponsesProvider < Base
+        include ToolChoiceClearing
+
         # @return [Class]
         def self.options_klass
           Options
@@ -24,22 +27,75 @@ 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
         end
 
-        # Processes streaming response chunks from the Responses API.
+        # @see BaseProvider#api_response_normalize
+        # @param api_response [OpenAI::Models::Responses::Response]
+        # @return [Hash] normalized response hash
+        def api_response_normalize(api_response)
+          return api_response unless api_response
+
+          Responses::Transforms.gem_to_hash(api_response)
+        end
+
+        # Processes streaming response chunks from the Responses API
         #
-        # Handles event types: response.created, response.output_item.added,
-        # response.output_text.delta, response.function_call_arguments.delta,
-        # and response.completed. Updates message stack and broadcasts streaming
-        # updates to listeners.
+        # Event types handled:
+        # - `:"response.created"`, `:"response.in_progress"` - response lifecycle
+        # - `:"response.output_item.added"` - message or function call added
+        # - `:"response.content_part.added"` - content part started
+        # - `:"response.output_text.delta"` - incremental text updates
+        # - `:"response.output_text.done"` - complete text
+        # - `:"response.function_call_arguments.delta"` - function argument updates
+        # - `:"response.function_call_arguments.done"` - complete function arguments
+        # - `:"response.content_part.done"` - content part completed
+        # - `:"response.output_item.done"` - message or function call completed
+        # - `:"response.completed"` - response finished
         #
-        # @param api_response_event [Hash] streaming response chunk with :type key
+        # @param api_response_event [Hash] streaming chunk with :type key
         # @return [void]
+        # @see Base#process_stream_chunk
         def process_stream_chunk(api_response_event)
-          instrument("stream_chunk_processing.provider.active_agent", chunk_type: api_response_event.type)
+          instrument("stream_chunk.active_agent", chunk_type: api_response_event.type)
 
           case api_response_event.type
           # Response Created
@@ -55,14 +111,14 @@ module ActiveAgent
 
           # -> -> -> Content Text Append
           when :"response.output_text.delta"
-            message = message_stack.find { _1[:id] == api_response_event[:item_id] }
-            message[:content] += api_response_event[:delta]
-            broadcast_stream_update(message, api_response_event[:delta])
+            message = message_stack.find { _1[:id] == api_response_event.item_id }
+            message[:content] += api_response_event.delta
+            broadcast_stream_update(message, api_response_event.delta)
 
           # -> -> -> Content Text Completed [Full Text]
           when :"response.output_text.done"
-            message = message_stack.find { _1[:id] == api_response_event[:item_id] }
-            message[:content] = api_response_event[:text]
+            message = message_stack.find { _1[:id] == api_response_event.item_id }
+            message[:content] = api_response_event.text
             broadcast_stream_update(message, nil) # Don't double send content
 
           # -> -> -> Content Function Call Append
@@ -81,11 +137,17 @@ module ActiveAgent
             # Once we are finished, close out and run tooling callbacks (Recursive)
             process_prompt_finished
           else
-            fail "Unexpected Response Chunk Type: #{type}"
+            raise "Unexpected Response Chunk Type: #{api_response_event.type}"
           end
         end
 
-        # Processes output item added events from streaming response.
+        # Processes output item added events from streaming response
+        #
+        # Handles message and function_call item types. For messages, adds to stack
+        # with empty content. For function calls, waits for completion event.
+        #
+        # Required because API returns empty array instead of empty string for
+        # initial message content due to serialization bug.
         #
         # @param api_response_event [Hash] response chunk with :item key
         # @return [void]
@@ -93,15 +155,19 @@ module ActiveAgent
           case api_response_event.item.type
           when :message
             # PATCH: API returns an empty array instead of empty string due to a bug in their serialization
-            message_stack << { content: "" }.merge(api_response_event.item.to_h.compact_blank)
+            item_hash = Responses::Transforms.gem_to_hash(api_response_event.item).compact_blank
+            message_stack << { content: "" }.merge(item_hash)
           when :function_call
             # No-Op: Wait for FC to Land (-> response.output_item.done)
           else
-            fail "Unexpected Item Type: #{api_response_event.item.type}"
+            raise "Unexpected Item Type: #{api_response_event.item.type}"
           end
         end
 
-        # Processes output item completion events from streaming response.
+        # Processes output item completion events from streaming response
+        #
+        # For function calls, adds completed item to message stack.
+        # For messages, no action needed as content already updated via delta events.
         #
         # @param api_response_event [Hash] response chunk with completed :item
         # @return [void]
@@ -110,35 +176,54 @@ module ActiveAgent
           when :message
             # No-Op: Message Up to Date
           when :function_call
-            message_stack << api_response_event.item
+            item_hash = Responses::Transforms.gem_to_hash(api_response_event.item)
+            message_stack << item_hash
           else
-            fail "Unexpected Item Type: #{api_response_event.item.type}"
+            raise "Unexpected Item Type: #{api_response_event.item.type}"
           end
         end
 
-        # Executes function calls and creates output messages for conversation continuation.
+        # Executes function calls and creates output messages for conversation continuation
         #
         # @param api_function_calls [Array<Hash>] function calls with :call_id and :name keys
         # @return [void]
+        # @see Base#process_function_calls
         def process_function_calls(api_function_calls)
           api_function_calls.each do |api_function_call|
-            instrument("tool_execution.provider.active_agent", tool_name: api_function_call[:name])
+            output = instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+              process_tool_call_function(api_function_call).to_json
+            end
 
-            message = Responses::Requests::Inputs::FunctionCallOutput.new(
+            # Create native gem input item for function call output
+            message = ::OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput.new(
               call_id: api_function_call[:call_id],
-              output:  process_tool_call_function(api_function_call).to_json
+              output:
             )
 
-            message_stack.push(message.serialize)
+            # Convert to hash for message_stack
+            message_stack.push(Responses::Transforms.gem_to_hash(message))
           end
         end
 
+        # Converts OpenAI gem response object to hash for storage.
+        #
+        # @param api_response [OpenAI::Models::Responses::Response]
+        # @return [Common::PromptResponse, nil]
+        def process_prompt_finished(api_response = nil)
+          # Convert gem object to hash so that raw_response["usage"] works
+          api_response_hash = api_response ? Responses::Transforms.gem_to_hash(api_response) : nil
+          super(api_response_hash)
+        end
+
         # Extracts messages from completed API response.
         #
-        # @param api_response [Hash] completed API response
-        # @return [Array, nil] output array from response[:output] or nil
+        # @param api_response [Hash] converted response hash
+        # @return [Array, nil] output array from response.output or nil
         def process_prompt_finished_extract_messages(api_response)
-          api_response&.dig(:output)
+          return unless api_response
+
+          # Response is already a hash from process_prompt_finished
+          api_response[:output]
         end
 
         # Extracts function calls from message stack.

data/lib/active_agent/providers/open_ai_provider.rb

@@ -60,10 +60,8 @@ module ActiveAgent
       # @see https://platform.openai.com/docs/guides/migrate-to-responses
       def prompt
         if api_version == :chat || context[:audio].present?
-          instrument("api_routing.provider.active_agent", api_type: :chat, api_version: api_version, has_audio: context[:audio].present?)
           OpenAI::ChatProvider.new(raw_options).prompt
         else # api_version == :responses || true
-          instrument("api_routing.provider.active_agent", api_type: :responses, api_version: api_version)
           OpenAI::ResponsesProvider.new(raw_options).prompt
         end
       end
@@ -89,7 +87,6 @@ module ActiveAgent
       # @param parameters [Hash] The embedding request parameters
       # @return [Object] The embedding response from OpenAI
       def api_embed_execute(parameters)
-        instrument("embeddings_request.provider.active_agent")
         client.embeddings.create(**parameters).as_json.deep_symbolize_keys
       end
     end

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

@@ -8,8 +8,25 @@ require_relative "options"
 module ActiveAgent
   module Providers
     module OpenRouter
-      # Type for Request model
+      # ActiveModel type for casting and serializing OpenRouter requests
+      #
+      # Handles conversion between hashes, Request objects, and serialized
+      # request hashes for the OpenRouter API.
+      #
+      # @example Type casting
+      #   type = RequestType.new
+      #   request = type.cast({ model: "openai/gpt-4", messages: "Hello" })
+      #   # => #<Request ...>
+      #
+      # @example Serialization
+      #   serialized = type.serialize(request)
+      #   # => { model: "openai/gpt-4", messages: [...] }
       class RequestType < ActiveModel::Type::Value
+        # Casts value to Request object
+        #
+        # @param value [Request, Hash, nil]
+        # @return [Request, nil]
+        # @raise [ArgumentError] if value cannot be cast
         def cast(value)
           case value
           when Request
@@ -23,6 +40,11 @@ module ActiveAgent
           end
         end
 
+        # Serializes Request to hash for API submission
+        #
+        # @param value [Request, Hash, nil]
+        # @return [Hash, nil]
+        # @raise [ArgumentError] if value cannot be serialized
         def serialize(value)
           case value
           when Request
@@ -36,6 +58,10 @@ module ActiveAgent
           end
         end
 
+        # Deserializes value from storage
+        #
+        # @param value [Object]
+        # @return [Request, nil]
         def deserialize(value)
           cast(value)
         end