activeagent 0.6.3 → 1.0.0.rc1

data/lib/active_agent/providers/common/responses/format.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "active_agent/providers/common/model"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        class Format < Common::BaseModel
+          # Type of response format (text, json_object, json_schema)
+          attribute :type, :string, default: "text"
+          attribute :name, :string
+          attribute :schema
+
+          validates :type, inclusion: { in: %w[text json_object json_object] }, allow_nil: true
+
+          # OpenAI's Responses => Common Format
+          def format=(value)
+            self.type = value[:type]
+          end
+
+          # OpenAI's Chat => Common Format
+          def json_schema=(value)
+            self.name   = value[:name]   if value[:name]
+            self.schema = value[:schema] if value[:schema]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_agent/providers/common/responses/message.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../messages/base"

data/lib/active_agent/providers/common/responses/prompt.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "_types"
+require_relative "message"
+
+module ActiveAgent
+  module Providers
+    module Common
+      module Responses
+        # Response model for prompt/completion responses
+        #
+        # This class represents responses from conversational/completion endpoints.
+        # It includes the generated messages, the original context, raw API data,
+        # and usage statistics.
+        #
+        # == Example
+        #
+        #   response = PromptResponse.new(
+        #     context: context_hash,
+        #     messages: [message_object],
+        #     raw_response: { "usage" => { "prompt_tokens" => 10 } }
+        #   )
+        #
+        #   response.message        #=> <Message>
+        #   response.prompt_tokens  #=> 10
+        #   response.usage          #=> { "prompt_tokens" => 10, ... }
+        class Prompt < Base
+          # The list of messages from this conversation
+          attribute :messages, Types::MessagesType.new, writable: false
+
+          attribute :format, Types::FormatType.new, writable: false, default: {}
+
+          # The most recent message in the conversational stack
+          def message
+            messages.last
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Provides exception handling for provider operations.
+    #
+    # This concern implements basic exception handling that allows agents to
+    # define custom error handling logic via rescue_from callbacks. The actual
+    # retry logic is now handled by the underlying provider gems (ruby-openai,
+    # anthropic-rb, etc.) which provide their own retry mechanisms.
+    #
+    # @example Using exception handler
+    #   class MyProvider
+    #     include ActiveAgent::Providers::ExceptionHandler
+    #
+    #     def call
+    #       with_exception_handling do
+    #         # API call that may fail
+    #       end
+    #     end
+    #   end
+    #
+    # @example Agent-level error handling
+    #   class MyAgent < ActiveAgent::Base
+    #     rescue_from SomeError do |exception|
+    #       # Handle the error
+    #     end
+    #   end
+    module ExceptionHandler
+      extend ActiveSupport::Concern
+
+      included do
+        # @!attribute [rw] exception_handler
+        #   @return [Proc, nil] Callback for handling exceptions
+        attr_internal :exception_handler
+      end
+
+      # Configures instance-level exception handling.
+      #
+      # @param exception_handler [Proc, nil] callback for handling exceptions
+      # @return [void]
+      def configure_exception_handler(exception_handler: nil)
+        self.exception_handler = exception_handler
+      end
+
+      # Executes a block with exception handling.
+      #
+      # @yield Block to execute with exception protection
+      # @return [Object] The result of the block execution
+      # @raise [StandardError] Any unhandled exception from the block
+      #
+      # @example Basic usage
+      #   with_exception_handling { api_call }
+      def with_exception_handling(&block)
+        yield
+      rescue => exception
+        rescue_with_handler(exception) || raise
+      end
+
+      # Bubbles up exceptions to the Agent's rescue_from if a handler is defined.
+      #
+      # This method delegates exception handling to the configured exception handler,
+      # allowing agents to define custom error handling logic.
+      #
+      # @param exception [StandardError] The exception to handle
+      # @return [Object, nil] Result from the exception handler, or nil if no handler
+      def rescue_with_handler(exception)
+        exception_handler&.call(exception)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Providers
+    # Generates markdown previews of prompts for debugging and inspection.
+    #
+    # Renders request parameters, instructions, messages, and tools in a
+    # human-readable format without executing the actual API call.
+    module Previewable
+      extend ActiveSupport::Concern
+
+      # Generates a markdown preview of the prompt request.
+      #
+      # @return [String] markdown-formatted preview
+      def preview_prompt
+        request = prepare_prompt_request
+
+        # @todo Validate Request
+        api_parameters = api_request_build(request, prompt_request_type)
+
+        render_markdown_preview(api_parameters)
+      end
+
+      private
+
+      # Renders markdown preview with YAML metadata, instructions, messages, and tools.
+      #
+      # Sections are separated by `---` dividers for readability.
+      #
+      # @param parameters [Hash]
+      # @return [String]
+      def render_markdown_preview(parameters)
+        sections = []
+
+        # Instructions section
+        if (instructions = parameters.delete(:instructions)).present?
+          sections << render_instructions_section(instructions)
+        end
+
+        # Messages section
+        if (messages = parameters.delete(:messages) || parameters.delete(:input)).present?
+          sections << render_messages_section(messages)
+        end
+
+        # Tools section
+        if (tools = parameters.delete(:tools)).present?
+          sections << render_tools_section(tools)
+        end
+
+        # Prepend YAML section with request details
+        sections = [ render_yaml_section(parameters), "---" ] + sections
+
+        sections.compact.join("\n")
+      end
+
+      # @param instructions [String]
+      # @return [String]
+      def render_instructions_section(instructions)
+        "## Instructions\n#{instructions}"
+      end
+
+      # Renders conversation messages with role labels.
+      #
+      # @param messages [Array<Hash>]
+      # @return [String]
+      def render_messages_section(messages)
+        return "" if messages.nil? || messages.empty?
+
+        content = +"## Messages\n\n"
+
+        Array(messages).each_with_index do |message, index|
+          content << render_single_message(message, index + 1)
+          content << "\n\n" unless index == messages.size - 1
+        end
+
+        content
+      end
+
+      # @param message [Hash]
+      # @param index [Integer] 1-based message number
+      # @return [String]
+      def render_single_message(message, index)
+        role    = (message.is_a?(Hash) && message[:role]) || "user"
+        content = extract_message_content(message)
+
+        "### Message #{index} (#{role.capitalize})\n#{content}"
+      end
+
+      # Renders available tools with descriptions and parameter schemas.
+      #
+      # @param tools [Array<Hash>]
+      # @return [String]
+      def render_tools_section(tools)
+        return "" if tools.nil? || tools.empty?
+
+        content = +"## Tools\n\n"
+
+        tools.each_with_index do |tool, index|
+          content << "### #{tool[:name] || "Tool #{index + 1}"}\n"
+          content << "**Description:** #{tool[:description] || 'No description'}\n\n"
+
+          if tool[:parameters]
+            content << "**Parameters:**\n```json\n#{JSON.pretty_generate(tool[:parameters])}\n```\n\n"
+          end
+        end
+
+        content.chomp
+      end
+
+      # Extracts text content from various message formats.
+      #
+      # Handles string messages, hash messages with :content key, and
+      # array content blocks (extracting only text-type blocks).
+      #
+      # @param message [Hash, String, nil]
+      # @return [String]
+      def extract_message_content(message)
+        return "" if message.nil?
+
+        case message
+        when String
+          message
+        when Hash
+          content = message[:content]
+          case content
+          when String
+            content
+          when Array
+            content
+              .select { |block| block.is_a?(Hash) && block[:type] == "text" }
+              .map { |block| block[:text] }
+              .join(" ")
+          else
+            content.to_s
+          end
+        else
+          message.to_s
+        end
+      end
+
+      # Renders request metadata as YAML.
+      #
+      # @param parameters [Hash]
+      # @return [String]
+      def render_yaml_section(parameters)
+        parameters.to_yaml.chomp
+      end
+    end
+  end
+end

data/lib/active_agent/providers/log_subscriber.rb

@@ -0,0 +1,360 @@
+# frozen_string_literal: true
+
+require "active_support/log_subscriber"
+
+module ActiveAgent
+  module Providers
+    # Log subscriber for ActiveAgent provider operations.
+    #
+    # This subscriber listens to ActiveSupport::Notifications events published
+    # during provider operations and logs them in a consistent, configurable format.
+    #
+    # Events are automatically instrumented in the providers and can be customized
+    # or disabled through log level configuration.
+    #
+    # @example Custom log formatting
+    #   class MyLogSubscriber < ActiveAgent::LogSubscriber
+    #     def prompt_start(event)
+    #       info "🚀 Starting prompt: #{event.payload[:provider]}"
+    #     end
+    #   end
+    #
+    #   ActiveAgent::LogSubscriber.detach_from :active_agent_provider
+    #   MyLogSubscriber.attach_to :active_agent_provider
+    class LogSubscriber < ActiveSupport::LogSubscriber
+      # self.namespace = "active_agent" # Rails 8.1
+
+      # Logs the start of a prompt request
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def prompt_start(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Starting prompt request"
+        end
+      end
+      # event_log_level :prompt_start, :debug # Rails 8.1
+
+      # Logs the start of an embedding request
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def embed_start(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Starting embed request"
+        end
+      end
+      # event_log_level :embed_start, :debug # Rails 8.1
+
+      # Logs request preparation details
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def request_prepared(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        message_count  = event.payload[:message_count]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Prepared request with #{message_count} message(s)"
+        end
+      end
+      # event_log_level :request_prepared, :debug # Rails 8.1
+
+      # Logs API call execution
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def api_call(event)
+        return unless logger.debug?
+
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        streaming       = event.payload[:streaming]
+        duration        = event.duration.round(1)
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] API call completed in #{duration}ms (streaming: #{streaming})"
+        end
+      end
+      # event_log_level :api_call, :debug # Rails 8.1
+
+      # Logs embed API call execution
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def embed_call(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        duration        = event.duration.round(1)
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Embed API call completed in #{duration}ms"
+        end
+      end
+      # event_log_level :embed_call, :debug # Rails 8.1
+
+      # Logs stream opening
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def stream_open(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Opening stream"
+        end
+      end
+      # event_log_level :stream_open, :debug # Rails 8.1
+
+      # Logs stream closing
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def stream_close(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Closing stream"
+        end
+      end
+      # event_log_level :stream_close, :debug # Rails 8.1
+
+      # Logs message extraction from API response
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def messages_extracted(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        message_count   = event.payload[:message_count]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Extracted #{message_count} message(s) from API response"
+        end
+      end
+      # event_log_level :messages_extracted, :debug # Rails 8.1
+
+      # Logs tool/function call processing
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def tool_calls_processing(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        tool_count      = event.payload[:tool_count]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Processing #{tool_count} tool call(s)"
+        end
+      end
+      # event_log_level :tool_calls_processing, :debug # Rails 8.1
+
+      # Logs multi-turn conversation continuation
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def multi_turn_continue(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Continuing multi-turn conversation after tool execution"
+        end
+      end
+      # event_log_level :multi_turn_continue, :debug # Rails 8.1
+
+      # Logs prompt completion
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def prompt_complete(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        message_count   = event.payload[:message_count]
+        duration        = event.duration.round(1)
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Prompt completed with #{message_count} message(s) in stack (total: #{duration}ms)"
+        end
+      end
+      # event_log_level :prompt_complete, :debug # Rails 8.1
+
+      # Logs retry attempts
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def retry_attempt(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        attempt         = event.payload[:attempt]
+        max_retries     = event.payload[:max_retries]
+        exception       = event.payload[:exception]
+        backoff_time    = event.payload[:backoff_time]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}:Retries] Attempt #{attempt}/#{max_retries} failed with #{exception}, retrying in #{backoff_time}s"
+        end
+      end
+      # event_log_level :retry_attempt, :debug # Rails 8.1
+
+      # Logs when max retries are exceeded
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def retry_exhausted(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        max_retries     = event.payload[:max_retries]
+        exception       = event.payload[:exception]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}:Retries] Max retries (#{max_retries}) exceeded for #{exception}"
+        end
+      end
+      # event_log_level :retry_exhausted, :debug # Rails 8.1
+
+      # Logs tool execution
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def tool_execution(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        tool_name       = event.payload[:tool_name]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Executing tool: #{tool_name}"
+        end
+      end
+      # event_log_level :tool_execution, :debug # Rails 8.1
+
+      # Logs tool choice removal
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def tool_choice_removed(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Removing tool_choice constraint after tool execution"
+        end
+      end
+      # event_log_level :tool_choice_removed, :debug # Rails 8.1
+
+      # Logs API request
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def api_request(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        model           = event.payload[:model]
+        streaming       = event.payload[:streaming]
+
+
+        debug do
+          if streaming.nil?
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Executing request to #{model}"
+          else
+            mode = streaming ? "streaming" : "non-streaming"
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Executing #{mode} request to #{model}"
+          end
+        end
+      end
+      # event_log_level :api_request, :debug # Rails 8.1
+
+      # Logs stream chunk processing
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def stream_chunk_processing(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        chunk_type      = event.payload[:chunk_type]
+
+        debug do
+          if chunk_type
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Processing stream chunk: #{chunk_type}"
+          else
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Processing stream chunk"
+          end
+        end
+      end
+      # event_log_level :stream_chunk_processing, :debug # Rails 8.1
+
+      # Logs stream finished
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def stream_finished(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        finish_reason   = event.payload[:finish_reason]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Stream finished with reason: #{finish_reason}"
+        end
+      end
+      # event_log_level :stream_finished, :debug # Rails 8.1
+
+      # Logs API routing decisions
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def api_routing(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        api_type        = event.payload[:api_type]
+        api_version     = event.payload[:api_version]
+        has_audio       = event.payload[:has_audio]
+
+        debug do
+          if has_audio
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Routing to #{api_type.to_s.capitalize} API (api_version: #{api_version}, audio: #{has_audio})"
+          else
+            "[#{trace_id}] [ActiveAgent] [#{provider_module}] Routing to #{api_type.to_s.capitalize} API (api_version: #{api_version})"
+          end
+        end
+      end
+      # event_log_level :api_routing, :debug # Rails 8.1
+
+      # Logs embeddings requests
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def embeddings_request(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Executing embeddings request"
+        end
+      end
+      # event_log_level :embeddings_request, :debug # Rails 8.1
+
+      # Logs connection errors
+      #
+      # @param event [ActiveSupport::Notifications::Event]
+      def connection_error(event)
+        trace_id        = event.payload[:trace_id]
+        provider_module = event.payload[:provider_module]
+        uri_base        = event.payload[:uri_base]
+        exception       = event.payload[:exception]
+        message         = event.payload[:message]
+
+        debug do
+          "[#{trace_id}] [ActiveAgent] [#{provider_module}] Unable to connect to #{uri_base}. Please ensure the service is running. Error: #{exception} - #{message}"
+        end
+      end
+      # event_log_level :connection_error, :debug # Rails 8.1
+
+      private
+
+      # Use the logger configured for ActiveAgent::Base
+      #
+      # @return [Logger]
+      def logger
+        ActiveAgent::Base.logger
+      end
+    end
+  end
+end
+
+# region log_subscriber_attach
+ActiveAgent::Providers::LogSubscriber.attach_to :"provider.active_agent"
+# endregion log_subscriber_attach
+
+# Rails 8.1
+# ActiveSupport.event_reporter.subscribe(
+#   ActiveAgent::LogSubscriber.new, &ActiveAgent::LogSubscriber.subscription_filter
+# )