activeagent 1.0.0.rc1 → 1.0.0

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

@@ -0,0 +1,228 @@
+# 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
+
+            # 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,13 +1,14 @@
 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
@@ -29,17 +30,34 @@ module ActiveAgent
           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 +73,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 +99,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 +117,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 +138,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

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

@@ -8,11 +8,48 @@ require_relative "requests/provider_preferences"
 module ActiveAgent
   module Providers
     module OpenRouter
+      # Configuration options for OpenRouter provider
+      #
+      # Extends OpenAI::Options with OpenRouter-specific settings including
+      # HTTP-Referer and X-Title headers for app identification and ranking.
+      #
+      # @example Basic configuration
+      #   options = Options.new(
+      #     api_key: 'sk-or-v1-...',
+      #     app_name: 'MyApp',
+      #     site_url: 'https://myapp.com'
+      #   )
+      #
+      # @example Rails auto-configuration
+      #   # Automatically resolves app_name from Rails.application
+      #   # and site_url from routes.default_url_options
+      #   options = Options.new(api_key: ENV['OPENROUTER_API_KEY'])
+      #
+      # @see https://openrouter.ai/docs/api-keys OpenRouter API Keys
+      # @see https://openrouter.ai/docs/rankings OpenRouter App Rankings
       class Options < ActiveAgent::Providers::OpenAI::Options
+        # @!attribute base_url
+        #   @return [String] API endpoint (default: "https://openrouter.ai/api/v1")
         attribute :base_url, :string, as: "https://openrouter.ai/api/v1"
+
+        # @!attribute app_name
+        #   @return [String] application name for X-Title header (default: "ActiveAgent" or Rails app name)
         attribute :app_name, :string, fallback: "ActiveAgent"
+
+        # @!attribute site_url
+        #   @return [String] site URL for HTTP-Referer header (default: "https://activeagents.ai/" or Rails URL)
         attribute :site_url, :string, fallback: "https://activeagents.ai/"
 
+        # Creates new OpenRouter options with auto-resolution
+        #
+        # Automatically resolves app_name from Rails application name and
+        # site_url from Rails routes/ActionMailer default_url_options.
+        #
+        # @param kwargs [Hash] configuration options
+        # @option kwargs [String] :api_key OpenRouter API key
+        # @option kwargs [String] :app_name application name for rankings
+        # @option kwargs [String] :site_url site URL for rankings
+        # @return [Options]
         def initialize(kwargs = {})
           kwargs = kwargs.deep_symbolize_keys if kwargs.respond_to?(:deep_symbolize_keys)
 
@@ -22,11 +59,22 @@ module ActiveAgent
           )))
         end
 
+        # Serializes options for API requests
+        #
+        # Excludes app_name and site_url as they're sent via headers.
+        #
+        # @return [Hash] serialized options
         def serialize
           super.except(:app_name, :site_url)
         end
 
-        # We fallback to ActiveAgent but allow empty strings to unset
+        # Returns extra headers for OpenRouter API
+        #
+        # Maps app_name and site_url to OpenRouter's required headers:
+        # - HTTP-Referer: site_url
+        # - X-Title: app_name
+        #
+        # @return [Hash] headers hash
         def extra_headers
           deep_compact(
             "http-referer" => site_url.presence,