Going further · 10

Configuration

Riffer uses a centralized configuration system for provider credentials and settings.

Global Configuration

Use Riffer.configure to set up provider credentials:

Riffer.configure do |config|
  config.openai.api_key = ENV['OPENAI_API_KEY']
  config.openai.base_url = ENV['OPENAI_BASE_URL'] # Optional — gateways, proxies
  config.amazon_bedrock.region = 'us-east-1'
  config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
  config.anthropic.api_key = ENV['ANTHROPIC_API_KEY']
end

Providers take no constructor arguments — these settings are the only way to give a provider its credentials.

Credential and endpoint settings — amazon_bedrock.api_token / .region, anthropic.api_key / .base_url, azure_openai.api_key / .endpoint, gemini.api_key / .base_url, google_cloud.project_id / .location, openai.api_key / .base_url, openrouter.api_key — accept a String or nil and raise Riffer::ArgumentError naming the setting for anything else. An empty string is accepted; Amazon Bedrock treats it as unset. client is not validated (see Provider Clients).

Accessing Configuration

Access the current configuration via Riffer.config:

Riffer.config.openai.api_key
# => "sk-..."

Riffer.config.amazon_bedrock.region
# => "us-east-1"

Riffer.config.anthropic.api_key
# => "sk-ant-..."

Provider-Specific Configuration

For provider credentials and setup, see the individual Provider guides.

Provider Clients

Out of the box, each provider builds a default SDK client from its configured credentials. For anything beyond credentials — timeouts, retries, proxies, gateways — assign your own client to config.<provider>.client:

Riffer.configure do |config|
  config.openai.client = OpenAI::Client.new(
    api_key: ENV['OPENAI_API_KEY'],
    timeout: 30,
    max_retries: 4
  )
  config.gemini.client = Riffer::Providers::Gemini::Client.new(
    api_key: ENV['GEMINI_API_KEY'],
    connection: Faraday.new(request: { open_timeout: 10, read_timeout: 120 })
  )
end

Every provider accepts a client instance or a Proc returning one:

Provider Setting Default client built from credentials
OpenAI config.openai.client OpenAI::Client
Azure OpenAI config.azure_openai.client OpenAI::Client (with the Azure endpoint as base_url)
Anthropic config.anthropic.client Riffer::Providers::Anthropic::Client (riffer-owned)
Amazon Bedrock config.amazon_bedrock.client Aws::BedrockRuntime::Client
Gemini config.gemini.client Riffer::Providers::Gemini::Client (riffer-owned, see below)
Google Cloud config.google_cloud.client Riffer::Providers::GoogleCloud::Client (riffer-owned, see below)
OpenRouter config.openrouter.client OpenAI::Client (pinned to the OpenRouter endpoint)

A Proc takes no arguments and is resolved on every LLM call, never cached by riffer — memoize inside the Proc when construction is expensive. This makes the Proc the right tool for:

  • Fork safety (Puma clustered, Sidekiq swarm): a client built at boot holds sockets that break across fork; build (and cache) per process instead.
  • Expiring credentials (Azure AD tokens, STS-vended keys): re-resolve before they go stale.
Riffer.configure do |config|
  # Fork-safe shared client: one per process, built on first use after fork.
  config.anthropic.client = -> {
    ClientRegistry.anthropic_for(Process.pid)
  }

  # Re-resolved before the token goes stale.
  config.azure_openai.client = -> {
    OpenAI::Client.new(api_key: AzureAd.current_token, base_url: ENV['AZURE_OPENAI_ENDPOINT'])
  }
end

Because the Proc receives no arguments, it can only vary the client by process-wide state — it cannot route per agent or per request. Client selection is a global concern; to talk to different accounts or endpoints from different agents, register a provider subclass with its own config (see Multiple Configurations).

A configured client always wins over configured credentials: once config.<provider>.client is set, the credential members are unused, since riffer no longer builds the client.

Falling through to the SDK

A credential you leave unset in riffer is omitted from the default client rather than passed as nil, so each vendor SDK still applies its own resolution. OPENAI_API_KEY / OPENAI_BASE_URL and the AWS chains — region from AWS_REGION / AWS_DEFAULT_REGION / shared config, credentials from the environment, the shared credentials file, or an instance/task IAM role — all work with no riffer configuration at all.

Two providers deliberately opt out: OpenRouter and AzureOpenAI borrow OpenAI::Client to reach a different vendor, so they always pass their credential and endpoint explicitly. Falling through would let the OpenAI SDK pick up OPENAI_API_KEY / OPENAI_BASE_URL and send an OpenAI credential to openrouter.ai or your Azure endpoint. With nothing configured they raise instead — set config.openrouter.api_key / OPENROUTER_API_KEY, or config.azure_openai.api_key and .endpoint / AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT.

The Anthropic provider uses no vendor SDK. Riffer reads ANTHROPIC_API_KEY and ANTHROPIC_BASE_URL itself when config.anthropic.api_key / .base_url are unset, and raises Riffer::ArgumentError when no key is found. Its client, Riffer::Providers::Anthropic::Client, takes headers: and a connection: (see Connections and Anthropic).

The Gemini provider has no vendor SDK, so riffer ships its own transport, Riffer::Providers::Gemini::Client, built on Riffer::HTTP::Client (see Connections). Its key falls back to GEMINI_API_KEY when config.gemini.api_key is unset, and raises Riffer::ArgumentError when neither is set. Anything implementing its two-method contract (post, post_stream) can be assigned to config.gemini.client — see Gemini.

The Google Cloud providers (google_cloud for Gemini, anthropic_vertex for Claude) share their own Agent Platform transport: Riffer::Providers::GoogleCloud::Client, also built on Riffer::HTTP::Client, is bound to one project_id and location and authenticates with config.google_cloud.credentials, or Application Default Credentials when unset. The default "global" location has no data-residency guarantee; see Google Cloud → Locations and Data Residency for pinning a location and for reaching several locations from one process.

Connections

Clients built on Riffer::HTTP::Client send requests through a Faraday connection. The default uses Faraday’s net_http adapter with a 10-second open timeout, a 600-second read timeout and no retries. To change any of that, pass your own connection as connection:. Riffer’s defaults don’t carry over to a connection you pass in, so set its timeouts yourself, in the form its adapter reads them. Riffer requests absolute URLs and sets the auth headers on each request, so the connection needs no url:.

To send extra headers, pass headers: to the client, or set them on the connection. Either way they go on every request and replace riffer’s auth and version headers of the same name. A replaced auth header is sent as-is, never refreshed. Riffer always sets content-type, accept and accept-encoding itself.

For example, to retry rate limits and server errors with faraday-retry:

# Gemfile: gem "faraday-retry"
require "faraday/retry"

connection = Faraday.new(request: { open_timeout: 10, read_timeout: 300 }) do |f|
  f.request :retry,
    max: 2,
    methods: [:post],
    retry_statuses: [429, 500, 502, 503, 504, 529]
end

Retrying a streaming request is only safe before any data has arrived. If a retry restarts a stream that already yielded chunks, riffer raises Riffer::Error rather than yield them twice.

Streaming is tested with the default net_http adapter.

Errors

  • A non-success status raises Riffer::APIError (a Riffer::Error). status holds the HTTP status (nil for an error event inside a stream) and body the raw response text.
  • Transport failures are raised as Faraday’s own errors, such as Faraday::TimeoutError and Faraday::ConnectionFailed (both Faraday::Errors).

MCP (deprecated)

config.mcp is deprecated and will be removed with MCP client support in a future release; each line that sets credentials or discovery_runner reports a deprecation. See MCP → Moving off MCP.

Optional settings for MCP server integrations:

Option Description
credentials Optional callable for per-run tools/call HTTP headers: ->(manifest:, matched_tags:, context:) { Hash or nil }. Raises Riffer::ArgumentError unless nil or it responds to #call.
discovery_runner Riffer::Runner instance for tool discovery (default Runner::Sequential.new). Raises Riffer::ArgumentError for anything that isn’t a Riffer::Runner instance.
Riffer.configure do |config|
  config.mcp.credentials = lambda do |manifest:, matched_tags:, context:|
    {"Authorization" => "Bearer #{token_for(context)}"}
  end
end

See MCP for registration, tags, and agent use_mcp.

Evals (deprecated)

config.evals is deprecated and will move out of riffer into the riffer-evals gem along with evals. Reading it reports a deprecation.

Riffer.configure do |config|
  config.evals.judge_model = "anthropic/claude-opus-4-5-20251101"
end

judge_model is the default model evaluators use as the judge when they don’t set their own. It must be a provider/model string or nil (the default); anything else raises Riffer::ArgumentError. See Evals.

Tool Runtime

Configure the default tool runtime for all agents:

Riffer.configure do |config|
  config.tool_runtime = Riffer::Tools::Runtime::Threaded
end
Value Description
Riffer::Tools::Runtime subclass Instantiated automatically (e.g., Riffer::Tools::Runtime::Inline, Riffer::Tools::Runtime::Threaded)
Riffer::Tools::Runtime instance Custom runtime with specific options
Proc Dynamic resolution

Per-agent configuration overrides this global default. See Advanced Tool Configuration — Tool Runtime for details.

Skills

Skills-related global configuration lives under config.skills.

Default activation tool

Override the tool the LLM calls to activate a skill. Defaults to Riffer::Skills::ActivateTool:

Riffer.configure do |config|
  config.skills.default_activate_tool = MyCustomActivateTool
end

Per-agent override is available inside the skills block via activate_tool MyCustomActivateTool. See Skills — Custom Activation Tool.

Default backend

Set an app-wide default skills backend. Used by any agent that declares a skills block without specifying its own backend:

Riffer.configure do |config|
  config.skills.default_backend = Riffer::Skills::FilesystemBackend.new(".skills")
end

Accepts a Riffer::Skills::Backend instance or a Proc that receives context and returns a backend. Defaults to nil — agents that don’t set their own backend get no skills, matching pre-existing behavior. Per-agent backends override this default.

Tracing

Tracing-related global configuration lives under config.tracing. Riffer emits spans only through the backend you assign to config.tracing.backend — there is no auto-detection. OpenTelemetry is a built-in backend you opt into explicitly with Riffer::Tracing::Otel.build; with no backend set every span is a silent no-op, and riffer carries no OTEL gem dependency either way.

Riffer.configure do |config|
  config.tracing.enabled = ENV.fetch("RIFFER_TRACING_ENABLED", "true")
  # Opt into OpenTelemetry (uses the global tracer provider):
  config.tracing.backend = Riffer::Tracing::Otel.build
end
Option Description
enabled The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or 'true'/'false'/'1'/'0'. Defaults to true.
capture_messages Opt-in capture of full message content on LLM-call spans (gen_ai.input.messages, gen_ai.output.messages, gen_ai.system_instructions) as GenAI-semconv JSON. Defaults to false — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.
backend The backend riffer routes spans through. Assign Riffer::Tracing::Otel.build (pass provider: to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (in_span / current_context / with_context) to route into a non-OTEL system (e.g. Datadog APM). Defaults to nil — a no-op. Raises Riffer::ArgumentError unless the value is nil or responds to all of in_span, current_context, and with_context. See Tracing → Routing to a non-OpenTelemetry backend.

File Downloads

File-attachment-download policy lives under config.files. Before an LLM call, riffer resolves every Riffer::Messages::User::FilePart attached to a user message against the provider’s own capability — some providers accept a URL as-is, some need the bytes inline, and some can’t take an attachment at all. See Messages — File Parts for FilePart itself and its sha256: field.

Riffer.configure do |config|
  config.files.allow_downloads = true
  config.files.max_bytes = 5_000_000
  config.files.max_per_message = 4
end

Per file, riffer applies this policy, in order:

  1. Already inline data — nothing to download. If sha256: was given, it’s verified against the existing bytes regardless of any other setting below.
  2. Provider can’t accept the file at all — raises Riffer::FileUnsupportedError.
  3. Provider accepts a URL as-is — passed straight through, untouched, unless sha256: was given, in which case riffer downloads and verifies anyway (a caller who set sha256: is asking for integrity verification, not a passthrough).
  4. Provider needs the bytes inline — riffer downloads the file, verifying sha256: if given.

Every download in step 3 or 4 is gated by allow_downloads; with it false (the default), reaching either of those steps raises Riffer::FileDownloadsDisabledError instead of fetching anything. This means upgrading to a riffer version with this feature never starts downloading arbitrary URLs on your behalf — you have to opt in.

Option Description
allow_downloads Whether riffer may download a FilePart’s URL. Accepts booleans or 'true'/'false'/'1'/'0'. Defaults to false.
max_bytes Maximum size, in bytes, of a downloaded file; the download is aborted once the streamed body exceeds this, independent of (and regardless of a missing/lying) content-length header. Defaults to 3_500_000.
timeout Open and read timeout, in seconds, for a single download attempt. Defaults to 60.
max_per_message Maximum number of files allowed on a single user message; checked against each message as originally authored, before consecutive messages are merged. nil (default) means uncapped.
runner A Riffer::Runner instance that resolves every file across a call’s messages. Defaults to Riffer::Runner::Sequential.new; assign Riffer::Runner::Threaded.new (or Riffer::Runner::Fibers.new inside a fiber-based host) to resolve multiple files concurrently.
downloader The object that fetches a URL’s bytes; must respond to #call(url, max_bytes:, timeout:) returning the raw (not base64-encoded) file content. Riffer caches it as base64 or raw bytes, whichever the provider actually needs, rather than producing both. Defaults to Riffer::Files::Downloader.new, which fetches over HTTPS only, following up to 3 redirects. Assign your own to add logging/metrics, or to fetch from a non-HTTPS store (e.g. s3://).

A file that fails resolution raises a Riffer::FileError subclass — Riffer::FileUnsupportedError, Riffer::FileDownloadsDisabledError, Riffer::TooManyFilesError, Riffer::FileChecksumMismatchError, Riffer::FileTooLargeError, Riffer::FileDownloadError, or Riffer::FileEncodingError — so callers can rescue Riffer::FileError for any attachment problem, or a specific subclass to handle one case.

Model Catalog

List JSON catalog files that hold per-model reasoning mappings and pricing. Riffer ships no catalog, so without one, reasoning uses each provider’s default mapping, and calls carry no cost unless the deprecated config.pricing prices the model.

Riffer.configure do |config|
  config.catalog_files = ["config/riffer/models.json"]
end
Option Description
catalog_files Array of paths (Strings or Pathnames), loaded in order; later files override earlier ones. Built at the end of Riffer.configure.

See Model Catalog for the file format, lookup, layering, and validation.

Pricing (deprecated)

config.pricing is deprecated and will be removed in a future release. Move rates into a catalog file; each line that calls set reports a deprecation. Riffer still reads these rates as a fallback, and catalog pricing wins when both price a model.

# before
Riffer.configure do |config|
  config.pricing.set("anthropic/claude-sonnet-4-6", input: 3.0, output: 15.0)
end
{ "version": 1, "models": { "anthropic/claude-sonnet-4-6": { "pricing": { "input": 3.0, "output": 15.0 } } } }

set takes a provider/model id or an array of ids, plus input:, output:, and optional cache_read: and cache_write: rates per million tokens. The rates and cost formula are the same as catalog pricing.

Deprecations

A deprecated riffer call reports itself at least one release before it is removed. The report names the line in your code that made the call:

riffer: config.pricing is deprecated and will be removed in a future version; move rates into a catalog file listed in config.catalog_files (see docs/CATALOG.md). Called from config/initializers/riffer.rb:4.

config.deprecations decides what happens:

Riffer.configure do |config|
  config.deprecations = ->(event) { Rails.logger.warn(event.to_s) }
end
Value Description
:warn (default) Prints the report to stderr with Kernel.warn, once per deprecation per calling line.
:raise Raises Riffer::DeprecationError on every call, so a test suite fails on each test that makes one. See Testing — Deprecations.
:silence Reports nothing.
A callable Called with a Riffer::Deprecation::Event once per deprecation per calling line. The event has id, message and location ("path:line"); to_s is the report.

Any other value raises Riffer::ArgumentError.

Future flags

config.future lets you turn on new behaviour before it becomes the default, so you can try it and adapt ahead of the breaking release that switches it on for everyone:

Riffer.configure do |config|
  config.future.some_flag = true
end

A flag accepts booleans, 'true'/'false'/'1'/'0', 1/0, or nil (which turns an opt-in flag off); any other value raises Riffer::ArgumentError. Setting a flag Riffer doesn’t know raises NoMethodError.

A flag goes through three stages:

  1. Opt-in. The flag is off by default, and setting it to true turns the new behaviour on.
  2. Default. A breaking release makes the new behaviour the default. The flag always reads as on, and setting it reports a deprecation saying it’s no longer needed and can be removed.
  3. Removed. A release later the flag is gone, and setting it raises NoMethodError.
Flag Stage Description
(none)   Riffer has no future flags yet.

Message ID Strategy

Opt in to stable identifiers on every message for logging, persistence, or replay:

Riffer.configure do |config|
  config.message_id_strategy = :uuidv7
end
Value Description
:none (default) No id is generated; message.id returns nil and :id is omitted from to_h.
:uuid UUIDv4 via SecureRandom.uuid.
:uuidv7 Time-ordered UUIDv7 via SecureRandom.uuid_v7 (Ruby 3.3+).

When the strategy is not :none, every Riffer::Messages::Base instance — user prompts, system instructions, assistant responses, and tool results — gets an auto-generated id at construction time. IDs are included in message.to_h when present and omitted when nil. Provider API payloads are unaffected; the id stays on the Ruby side.

When constructing a Riffer::Agent::Session from persisted history with the strategy enabled, supply ids on every seeded message yourself — Riffer never fabricates identifiers for pre-existing history. Messages built via the Riffer::Messages::* constructors auto-generate ids per the strategy, so as long as those constructors are used at message-creation time, ids flow through.

See Messages — IDs for more details.

Agent-Level Configuration

Override global configuration at the agent level:

model_options

Pass options to each LLM request:

class MyAgent < Riffer::Agent
  model 'openai/gpt-5-mini'

  # These options are sent with every generate/stream call
  model_options temperature: 0.7, reasoning: 'medium'
end

reasoning

Set how much the model thinks before it answers, with one setting that works on every provider:

class MyAgent < Riffer::Agent
  model 'anthropic/claude-sonnet-4-6'
  reasoning :low # :off, :low, :medium, :high, :xhigh, or :max
end

Riffer maps the level to the provider’s own params, from a catalog entry or the provider’s default. model_options are deep-merged over those params and win. See Agents — reasoning.

Common Model Options

OpenAI

Option Description
temperature Sampling temperature (0.0-2.0)
max_tokens Maximum tokens in response
top_p Nucleus sampling parameter
reasoning Reasoning effort level (low, medium, high)
web_search Enable web search (true or config hash)
class MyAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  model_options temperature: 0.7, reasoning: 'medium'
end

Amazon Bedrock

Options are passed through to the Bedrock Converse API.

Option Description
inference_config Hash with max_tokens, temperature, top_p, stop_sequences
additional_model_request_fields Hash for model-specific params (e.g., top_k for Claude)
class MyAgent < Riffer::Agent
  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
  model_options inference_config: {temperature: 0.7, max_tokens: 4096}
end

Anthropic

Option Description
max_tokens Maximum tokens in response
thinking Extended thinking config hash (Claude 3.7+)
output_config Output config hash (e.g. effort)
web_search Enable web search (true or config hash)
class MyAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options max_tokens: 4096
end

# With extended thinking (Claude 3.7+)
class ReasoningAgent < Riffer::Agent
  model 'anthropic/claude-haiku-4-5-20251001'
  model_options thinking: {type: "enabled", budget_tokens: 10000}
end

# With an output effort level
class EffortAgent < Riffer::Agent
  model 'anthropic/claude-opus-5'
  model_options output_config: {effort: "high"}
end

Environment Variables

Recommended pattern for managing credentials:

# config/initializers/riffer.rb (Rails)
# or at application startup

Riffer.configure do |config|
  config.openai.api_key = ENV.fetch('OPENAI_API_KEY') { raise 'OPENAI_API_KEY not set' }

  if ENV['BEDROCK_REGION']
    config.amazon_bedrock.region = ENV['BEDROCK_REGION']
    config.amazon_bedrock.api_token = ENV['BEDROCK_API_TOKEN']
  end
end

Multiple Configurations

Provider credentials and clients are global, resolved per process. For different environments, branch at boot:

Riffer.configure do |config|
  config.openai.client = if Rails.env.production?
    OpenAI::Client.new(api_key: ENV['PRODUCTION_OPENAI_KEY'], max_retries: 4)
  else
    OpenAI::Client.new(api_key: ENV['DEV_OPENAI_KEY'], timeout: 10)
  end
end

When a single process has to reach two different accounts or endpoints, give the second one its own provider class and config, then register it under its own identifier:

class InternalOpenAI < Riffer::Providers::OpenAI
  InternalConfig = Struct.new(:api_key, :base_url, :client)

  def self.config
    @config ||= InternalConfig.new(ENV.fetch('INTERNAL_OPENAI_KEY'), ENV.fetch('INTERNAL_GATEWAY'))
  end

  private

  def global_client
    self.class.config.client
  end

  def build_client
    ::OpenAI::Client.new(api_key: self.class.config.api_key, base_url: self.class.config.base_url)
  end
end

Riffer::Providers::Repository.register(:internal_openai) { InternalOpenAI }

Agents then select it by model prefix (model 'internal_openai/gpt-5-mini'), and the two accounts never interfere. What can vary per agent is the model and the generation parameters:

class ProductionAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
end

class DevelopmentAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  model_options temperature: 0.0 # Deterministic for testing
end