class RubyLLM::Provider

A Provider connects RubyLLM to one AI service. It knows where to talk (host, authentication headers, configuration) and which protocol to speak for a given model and request. The wire formats themselves live under RubyLLM::Protocols.

Subclass Provider to support a new service, then make it available with ::register:

class Acme < RubyLLM::Provider
  protocol :chat_completions, RubyLLM::Protocols::ChatCompletions

  def self.configuration_options
    %i[acme_api_key]
  end

  def api_base
    'https://api.acme.ai/v1'
  end

  def headers
    { 'Authorization' => "Bearer #{@config.acme_api_key}" }
  end
end

RubyLLM::Provider.register :acme, Acme

See the custom providers guide for the full walkthrough.

Attributes

config [R]

The Configuration the provider was built with.

Public Class Methods

assume_models_exist? ()

Source

# File lib/ruby_llm/provider.rb, line 362
def assume_models_exist?
  false
end

Returns whether the provider accepts model ids missing from the model registry. The base implementation returns false.

capabilities ()

Source

# File lib/ruby_llm/provider.rb, line 321
def capabilities
  nil
end

Returns a module that reports model capabilities (context window, pricing, feature support) for the provider’s model ids. Used to fill in details the provider’s model list API does not return. The base implementation returns nil.

configuration_options ()

Source

# File lib/ruby_llm/provider.rb, line 345
def configuration_options
  []
end

Returns every configuration key the provider contributes. ::register defines a Configuration accessor for each one. The base implementation returns an empty array.

def self.configuration_options
  %i[acme_api_key acme_api_base]
end

configuration_requirements ()

Source

# File lib/ruby_llm/provider.rb, line 333
def configuration_requirements
  []
end

Returns the configuration keys that must be set before the provider is usable. The base implementation returns an empty array.

def self.configuration_requirements
  %i[acme_api_key]
end

display_name ()

Source

# File lib/ruby_llm/provider.rb, line 313
def display_name
  to_s.split('::').last
end

Returns the human-readable provider name, derived from the class name. Override for custom branding.

files (protocol_class)

Source

# File lib/ruby_llm/provider.rb, line 389
def files(protocol_class)
  @file_protocol = protocol_class
end

Declares the protocol class that handles file uploads for the provider.

files Protocols::OpenAI::Files

local? ()

Source

# File lib/ruby_llm/provider.rb, line 352
def local?
  false
end

Returns whether the provider talks to a locally hosted service. The base implementation returns false. Local providers such as Ollama return true.

protocol (name, protocol_class, batches: nil)

Source

# File lib/ruby_llm/provider.rb, line 378
def protocol(name, protocol_class, batches: nil)
  @default_protocol = name.to_sym if protocols.empty?
  protocols[name.to_sym] = protocol_class
  batch_protocol(name, batches) if batches
end

Registers protocol_class under name. The first registered protocol becomes the provider’s default. Pass batches: with a module of batch operations to enable the batch API for that protocol.

protocol :chat_completions, ChatCompletions
protocol :responses, Protocols::Responses, batches: Protocols::Responses::Batches

providers ()

Source

# File lib/ruby_llm/provider.rb, line 436
def providers
  @providers ||= {}
end

Returns the global registry of providers, a hash mapping slug symbols to provider classes.

Source

# File lib/ruby_llm/provider.rb, line 412
def register(name, provider_class)
  provider_class.slug = name.to_s
  providers[name.to_sym] = provider_class
  RubyLLM::Configuration.register_provider_options(provider_class.configuration_options + [:"#{name}_protocol"])
end

Registers provider_class under the slug name, making it available to RubyLLM.chat and the other top-level helpers. Stamps the class’s slug, adds it to ::providers, and defines a Configuration accessor for each of its configuration options.

RubyLLM::Provider.register :acme, RubyLLM::Providers::Acme

resolve_registry_id (model_id, _models)

Source

# File lib/ruby_llm/provider.rb, line 430
def resolve_registry_id(model_id, _models)
  model_id
end

Resolves model_id to the id the registry stores it under for this provider. Defaults to the id unchanged; providers whose catalog ids differ from their request ids (Bedrock’s region prefixes) override it.

slug ()

Source

# File lib/ruby_llm/provider.rb, line 307
def slug
  @slug ||= to_s.split('::').last.downcase
end

Returns the provider slug, a short lowercase string that identifies the provider and prefixes its configuration keys. Set by ::register, or derived from the class name.

Public Instance Methods

api_base ()

Source

# File lib/ruby_llm/provider.rb, line 54
def api_base
  raise NotImplementedError
end

Returns the base URL that relative endpoint paths resolve against. The base implementation raises NotImplementedError, so every subclass must define it.

def api_base
  @config.acme_api_base || 'https://api.acme.ai/v1'
end

headers ()

Source

# File lib/ruby_llm/provider.rb, line 65
def headers
  {}
end

Returns the headers merged into every request. The default is an empty hash. Override to supply authentication.

def headers
  { 'Authorization' => "Bearer #{@config.acme_api_key}" }
end

name ()

Source

# File lib/ruby_llm/provider.rb, line 76
def name
  self.class.display_name
end

Returns the human-readable provider name, delegating to ::display_name.

protocol_for (_model, **)

Source

# File lib/ruby_llm/provider.rb, line 102
def protocol_for(_model, **)
  default_protocol
end

Returns the protocol class to use for model. Override to route between registered protocols per model or request operation. An explicit protocol: override on the chat or the provider’s <slug>_protocol configuration option takes precedence over this hook.

def protocol_for(model, **)
  model.id.match?(/audio|realtime/) ? protocols[:chat_completions] : super
end

slug ()

Source

# File lib/ruby_llm/provider.rb, line 70
def slug
  self.class.slug
end

Returns the provider slug, delegating to ::slug.