Class: ActiveAgent::Providers::BaseProvider Abstract

Inherits:
Object
  • Object
show all
Extended by:
ActiveSupport::Delegation
Includes:
ExceptionHandler, Instrumentation, Previewable, ToolChoiceClearing
Defined in:
lib/active_agent/providers/_base_provider.rb

Overview

This class is abstract.

Subclasses must implement #api_prompt_execute, #process_stream_chunk, #process_prompt_finished_extract_messages, and #process_prompt_finished_extract_function_calls

Orchestrates LLM provider API requests, streaming, and multi-turn tool calling.

Each provider (OpenAI, Anthropic, etc.) subclasses this to implement provider-specific API interactions.

Defined Under Namespace

Classes: ProvidersError

Constant Summary collapse

DEFAULT_MAX_TOOL_TURNS =

Upper bound on tool-calling round-trips within one generation. A model that keeps emitting tool calls otherwise recurses until the provider stops it — override per agent/prompt with max_tool_turns:.

25

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ToolChoiceClearing

#prepare_prompt_request_tools

Methods included from Previewable

#preview_prompt

Methods included from Instrumentation

#instrumentation_prompt_payload

Methods included from ExceptionHandler

#configure_exception_handler, #rescue_with_handler, #with_exception_handling

Constructor Details

#initialize(kwargs = {}) ⇒ BaseProvider

Returns a new instance of BaseProvider.

Parameters:

  • kwargs (Hash) (defaults to: {}) —

    configuration and callbacks

Options Hash (kwargs):

  • :service (Symbol) —

    validates against provider's service name

  • :stream_broadcaster (Proc) —

    for streaming events (:open, :update, :close)

  • :tools_function (Proc) —

    to execute tool/function calls

Raises:

  • (RuntimeError) —

    when service name doesn't match provider



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/active_agent/providers/_base_provider.rb', line 104

def initialize(kwargs = {})
  assert_service!(kwargs.delete(:service))

  configure_exception_handler(
    exception_handler: kwargs.delete(:exception_handler)
  )

  self.trace_id           = kwargs[:trace_id]
  self.stream_broadcaster = kwargs.delete(:stream_broadcaster)
  self.streaming          = false
  self.tools_function     = kwargs.delete(:tools_function)
  self.max_tool_turns     = kwargs.delete(:max_tool_turns) || DEFAULT_MAX_TOOL_TURNS
  self.tool_turns         = 0
  self.options            = options_klass.new(kwargs.extract!(*options_klass.keys))
  self.context            = kwargs
  self.message_stack      = []
  self.usage_stack        = []
end

Class Method Details

.embed_request_type ⇒ ActiveModel::Type::Value

Returns for embedding casting/serialization.

Returns:

  • (ActiveModel::Type::Value) —

    for embedding casting/serialization

Raises:

  • (NotImplementedError) —

    when provider doesn't support embeddings



93
94
95
 
# File 'lib/active_agent/providers/_base_provider.rb', line 93

def self.embed_request_type
  fail(NotImplementedError)
end

.namespace ⇒ Module

Returns e.g., ActiveAgent::Providers::OpenAI.

Returns:

  • (Module) —

    e.g., ActiveAgent::Providers::OpenAI



77
78
79
 
# File 'lib/active_agent/providers/_base_provider.rb', line 77

def self.namespace
  "#{name.deconstantize}::#{service_name}".safe_constantize
end

.options_klass ⇒ Class

Returns:

  • (Class) 


82
83
84
 
# File 'lib/active_agent/providers/_base_provider.rb', line 82

def self.options_klass
  namespace::Options
end

.prompt_request_type ⇒ ActiveModel::Type::Value

Returns for prompt casting/serialization.

Returns:

  • (ActiveModel::Type::Value) —

    for prompt casting/serialization



87
88
89
 
# File 'lib/active_agent/providers/_base_provider.rb', line 87

def self.prompt_request_type
  namespace::RequestType.new
end

.service_name ⇒ String

Returns e.g., "Anthropic", "OpenAI".

Returns:

  • (String) —

    e.g., "Anthropic", "OpenAI"



67
68
69
 
# File 'lib/active_agent/providers/_base_provider.rb', line 67

def self.service_name
  name.split("::").last.delete_suffix("Provider")
end

.tag_name ⇒ String

Returns e.g., "Anthropic", "OpenAI::Chat".

Returns:

  • (String) —

    e.g., "Anthropic", "OpenAI::Chat"



72
73
74
 
# File 'lib/active_agent/providers/_base_provider.rb', line 72

def self.tag_name
  name.delete_prefix("ActiveAgent::Providers::").delete_suffix("Provider")
end

Instance Method Details

#embed ⇒ ActiveAgent::Providers::Common::EmbedResponse

Executes embedding request with error handling and instrumentation.

Returns:



148
149
150
151
152
153
154
155
156
157
 
# File 'lib/active_agent/providers/_base_provider.rb', line 148

def embed
  self.request = embed_request_type.cast(context.except(:trace_id))

  instrument("embed.active_agent") do |payload|
    response = resolve_embed
    instrumentation_embed_payload(payload, request, response)

    response
  end
end

#preview ⇒ String

Generates prompt preview without executing the API call.

Returns:

  • (String) —

    markdown-formatted preview



126
127
128
129
 
# File 'lib/active_agent/providers/_base_provider.rb', line 126

def preview
  self.request = prompt_request_type.cast(context.except(:trace_id))
  preview_prompt
end

#prompt ⇒ ActiveAgent::Providers::Common::PromptResponse

Executes prompt request with error handling and instrumentation.

Returns:



134
135
136
137
138
139
140
141
142
143
 
# File 'lib/active_agent/providers/_base_provider.rb', line 134

def prompt
  self.request = prompt_request_type.cast(context.except(:trace_id))

  instrument("prompt.active_agent") do |payload|
    response = resolve_prompt
    instrumentation_prompt_payload(payload, request, response)

    response
  end
end