activeagent 0.6.3 → 1.0.0

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

@@ -0,0 +1,200 @@
+require_relative "_base"
+require_relative "responses/_types"
+require_relative "responses/transforms"
+
+module ActiveAgent
+  module Providers
+    module OpenAI
+      # Provider implementation for OpenAI's Responses API
+      #
+      # 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
+        # @return [Class]
+        def self.options_klass
+          Options
+        end
+
+        # @return [Responses::RequestType]
+        def self.prompt_request_type
+          Responses::RequestType.new
+        end
+
+        protected
+
+        # @return [Object] OpenAI client's responses endpoint
+        def api_prompt_executer
+          client.responses
+        end
+
+        # @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
+        #
+        # 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 chunk with :type key
+        # @return [void]
+        # @see Base#process_stream_chunk
+        def process_stream_chunk(api_response_event)
+          instrument("stream_chunk.active_agent", chunk_type: api_response_event.type)
+
+          case api_response_event.type
+          # Response Created
+          when :"response.created", :"response.in_progress"
+            broadcast_stream_open
+
+          # -> Message Created
+          when :"response.output_item.added"
+            process_stream_output_item_added(api_response_event)
+
+          # -> -> Content Part Create
+          when :"response.content_part.added"
+
+          # -> -> -> 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)
+
+          # -> -> -> 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
+            broadcast_stream_update(message, nil) # Don't double send content
+
+          # -> -> -> Content Function Call Append
+          when :"response.function_call_arguments.delta", :"response.function_call_arguments.done"
+          # No-Op: Wait for FC to Land
+
+          # -> -> Content Part Completed [Full Part]
+          when :"response.content_part.done"
+
+          # -> Message Completed
+          when :"response.output_item.done"
+            process_stream_output_item_done(api_response_event)
+
+          # Response Completed
+          when :"response.completed"
+            # Once we are finished, close out and run tooling callbacks (Recursive)
+            process_prompt_finished
+          else
+            raise "Unexpected Response Chunk Type: #{api_response_event.type}"
+          end
+        end
+
+        # 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]
+        def process_stream_output_item_added(api_response_event)
+          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
+            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
+            raise "Unexpected Item Type: #{api_response_event.item.type}"
+          end
+        end
+
+        # 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]
+        def process_stream_output_item_done(api_response_event)
+          case api_response_event.item.type
+          when :message
+            # No-Op: Message Up to Date
+          when :function_call
+            item_hash = Responses::Transforms.gem_to_hash(api_response_event.item)
+            message_stack << item_hash
+          else
+            raise "Unexpected Item Type: #{api_response_event.item.type}"
+          end
+        end
+
+        # 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|
+            output = instrument("tool_call.active_agent", tool_name: api_function_call[:name]) do
+              process_tool_call_function(api_function_call).to_json
+            end
+
+            # Create native gem input item for function call output
+            message = ::OpenAI::Models::Responses::ResponseInputItem::FunctionCallOutput.new(
+              call_id: api_function_call[:call_id],
+              output:
+            )
+
+            # 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] converted response hash
+        # @return [Array, nil] output array from response.output or nil
+        def process_prompt_finished_extract_messages(api_response)
+          return unless api_response
+
+          # Response is already a hash from process_prompt_finished
+          api_response[:output]
+        end
+
+        # Extracts function calls from message stack.
+        #
+        # @return [Array<Hash>] function call objects with type "function_call"
+        def process_prompt_finished_extract_function_calls
+          message_stack.select { _1[:type] == "function_call" }
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/open_ai_provider.rb

@@ -0,0 +1,94 @@
+require_relative "_base_provider"
+
+require_gem!(:openai, __FILE__)
+
+require_relative "open_ai/_base"
+require_relative "open_ai/chat_provider"
+require_relative "open_ai/responses_provider"
+require_relative "open_ai/embedding/_types"
+
+module ActiveAgent
+  module Providers
+    # Router for OpenAI's API versions based on supported features.
+    #
+    # This provider acts as a thin wrapper that routes requests between different versions
+    # of OpenAI's API (Chat API and Responses API) depending on the features used in the prompt.
+    # It automatically selects the appropriate API version based on:
+    # - Explicit API version specification (+:api_version+ option)
+    # - Presence of audio content in the request
+    #
+    # @example Basic usage
+    #   provider = ActiveAgent::Providers::OpenAIProvider.new(...)
+    #   result = provider.generate
+    #
+    # @see https://platform.openai.com/docs/guides/migrate-to-responses
+    class OpenAIProvider < OpenAI::Base
+      # Returns the embedding request type for OpenAI.
+      #
+      # @return [ActiveModel::Type::Value] The OpenAI embedding request type
+      def self.embed_request_type
+        OpenAI::Embedding::RequestType.new
+      end
+
+      attr_internal :api_version
+      attr_internal :raw_options
+
+      # Initializes the OpenAI provider router.
+      #
+      # Since this layer is just routing based on API version, we want to wait
+      # to cast values into their types.
+      #
+      # @param kwargs [Hash] Configuration options for the provider
+      # @option kwargs [Symbol] :service The service name to validate
+      # @option kwargs [Symbol] :api_version The OpenAI API version to use (:chat or :responses)
+      def initialize(kwargs = {})
+        # For Routing Prompt APIs
+        self.api_version = kwargs.delete(:api_version)
+        self.raw_options = kwargs.deep_dup
+
+        super
+      end
+
+      # Generates a response by routing to the appropriate OpenAI API version.
+      #
+      # This method determines which API version to use based on the prompt context:
+      # - Uses Chat API if +api_version: :chat+ is specified or audio is present
+      # - Uses Responses API otherwise (default)
+      #
+      # @return [Object] The generation result from the selected API provider
+      #
+      # @see https://platform.openai.com/docs/guides/migrate-to-responses
+      def prompt
+        if api_version == :chat || context[:audio].present?
+          OpenAI::ChatProvider.new(raw_options).prompt
+        else # api_version == :responses || true
+          OpenAI::ResponsesProvider.new(raw_options).prompt
+        end
+      end
+
+      # Generates a preview by routing to the appropriate OpenAI API version.
+      #
+      # Routes to Chat API or Responses API using the same logic as {#prompt}.
+      #
+      # @return [String] markdown-formatted preview
+      # @see #prompt
+      def preview
+        if api_version == :chat || context[:audio].present?
+          OpenAI::ChatProvider.new(raw_options).preview
+        else # api_version == :responses || true
+          OpenAI::ResponsesProvider.new(raw_options).preview
+        end
+      end
+
+      protected
+
+      # Executes an embedding request via OpenAI's API.
+      #
+      # @param parameters [Hash] The embedding request parameters
+      # @return [Object] The embedding response from OpenAI
+      def api_embed_execute(parameters)
+        client.embeddings.create(**parameters).as_json.deep_symbolize_keys
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "requests/_types"
+
+require_relative "request"
+require_relative "options"
+
+module ActiveAgent
+  module Providers
+    module OpenRouter
+      # 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
+            value
+          when Hash
+            Request.new(**value.deep_symbolize_keys)
+          when nil
+            nil
+          else
+            raise ArgumentError, "Cannot cast #{value.class} to Request"
+          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
+            value.serialize
+          when Hash
+            value
+          when nil
+            nil
+          else
+            raise ArgumentError, "Cannot serialize #{value.class}"
+          end
+        end
+
+        # Deserializes value from storage
+        #
+        # @param value [Object]
+        # @return [Request, nil]
+        def deserialize(value)
+          cast(value)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../open_ai/options"
+require_relative "requests/response_format"
+require_relative "requests/prediction"
+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)
+
+          super(**deep_compact(kwargs.merge(
+            app_name: kwargs[:app_name] || resolve_app_name(kwargs),
+            site_url: kwargs[:site_url] || resolve_site_url(kwargs),
+          )))
+        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
+
+        # 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,
+            "x-title"      => app_name.presence
+          )
+        end
+
+        private
+
+        def resolve_api_key(kwargs)
+          kwargs["api_key"] ||
+            ENV["OPENROUTER_API_KEY"] ||
+            ENV["OPEN_ROUTER_API_KEY"] ||
+            ENV["OPENROUTER_ACCESS_TOKEN"] ||
+            ENV["OPEN_ROUTER_ACCESS_TOKEN"]
+        end
+
+        # Not Used as Part of Open Router
+        def resolve_organization_id(kwargs) = nil
+        def resolve_project_id(kwargs)      = nil
+
+        def resolve_app_name(kwargs)
+          if defined?(Rails) && Rails.application
+            Rails.application.class.name.split("::").first
+          end
+        end
+
+        def resolve_site_url(kwargs)
+          # First check ActiveAgent kwargs
+          return kwargs[:default_url_options][:host] if kwargs.dig(:default_url_options, :host)
+
+          # Then check Rails routes default_url_options
+          if defined?(Rails) && Rails.application&.routes&.default_url_options&.any?
+            host     = Rails.application.routes.default_url_options[:host]
+            port     = Rails.application.routes.default_url_options[:port]
+            protocol = Rails.application.routes.default_url_options[:protocol] || "https"
+
+            if host
+              url = "#{protocol}://#{host}"
+              url += ":#{port}" if port && port != 80 && port != 443
+              return url
+            end
+          end
+
+          # Finally check ActionMailer options as fallback
+          if defined?(Rails) && Rails.application&.config&.action_mailer&.default_url_options
+            options = Rails.application.config.action_mailer.default_url_options
+            host = options[:host]
+            port = options[:port]
+            protocol = options[:protocol] || "https"
+
+            if host
+              url = "#{protocol}://#{host}"
+              url += ":#{port}" if port && port != 80 && port != 443
+              return url
+            end
+          end
+
+          nil
+        end
+      end
+    end
+  end
+end