Providers · 04

OpenAI Provider

The OpenAI provider connects to OpenAI’s API for GPT models.

Installation

Add the OpenAI gem to your Gemfile:

gem 'openai'

Configuration

Set your API key globally:

Riffer.configure do |config|
  config.openai.api_key = ENV['OPENAI_API_KEY']
end

Both api_key and base_url resolve in order: Riffer.config.openai.* → the OpenAI SDK’s own OPENAI_API_KEY / OPENAI_BASE_URL lookup. Leaving one unset in riffer means the SDK resolves it, so an OPENAI_BASE_URL gateway is honored without any riffer configuration.

For anything beyond the API key — timeouts, retries, proxies — supply your own OpenAI::Client:

Riffer.configure do |config|
  config.openai.client = OpenAI::Client.new(
    api_key: ENV['OPENAI_API_KEY'],
    timeout: 30,
    max_retries: 4
  )
end

The setting accepts a client instance or a no-argument Proc, resolved on every LLM call — see Configuration → Provider Clients.

For OpenAI-compatible servers (LiteLLM, vLLM, corporate gateways), configure a base_url:

Riffer.configure do |config|
  config.openai.api_key = ENV['GATEWAY_KEY']
  config.openai.base_url = 'http://localhost:4000/v1'
end

Supported Models

Use any OpenAI model in the openai/model format:

model 'openai/gpt-5.4'
model 'openai/gpt-5-mini'

Model Options

temperature

Controls randomness (0.0-2.0):

model_options temperature: 0.7

max_tokens

Maximum tokens in response:

model_options max_tokens: 4096

reasoning

Enables extended thinking (for supported models):

model_options reasoning: 'medium'  # 'low', 'medium', or 'high'

When reasoning is enabled, you’ll receive ReasoningDelta and ReasoningDone events during streaming.

The agent-level reasoning setting writes this same option by default: reasoning :low sends reasoning: 'low', and :off sends 'none'. A catalog entry can map a level differently.

Reasoning Replay

Each reasoning item in a Responses API output becomes reasoning parts on the assistant message, on both generate_text and stream_text, all tagged format: "openai-v1" and carrying the item’s id:

Reasoning item field ReasoningPart
each summary entry a :summary part with its text
each content entry a :text part with its text
encrypted_content one :encrypted part with it as data

The :encrypted part is always present, even when the response carried no encrypted_content, so the item’s id is kept. When streaming, the parts are yielded as ReasoningDone events once the item completes; summary text still arrives as ReasoningDelta events before that.

On the next request, parts sharing an id go back as one reasoning item, ahead of the assistant’s text and function calls, in their original order and unchanged. This lets reasoning models carry their reasoning across turns and tool-call loops. You don’t have to do anything as long as the assistant messages stay in the history; if you persist sessions, keep the reasoning when you store them.

With store left on (the API default), OpenAI can resolve a replayed item from its id alone. With model_options store: false, the item can only be replayed from its encrypted payload, so request it explicitly:

model_options reasoning: 'medium', store: false, include: ['reasoning.encrypted_content']

Only parts tagged openai-v1 are sent. Reasoning from other providers stays on the messages but is left out, including OpenRouter’s openai-responses-v1 parts, which are encrypted under OpenRouter’s organization rather than yours.

Enable server-side web search using OpenAI’s web_search_preview tool. Pass true to use defaults or a hash to merge with the tool definition:

# Enable with defaults
model_options web_search: true

# With custom configuration
model_options web_search: {search_context_size: "medium"}

With web search on, riffer also adds "web_search_call.action.sources" to the request’s include, keeping any entries you pass, so WebSearchDone carries the sources OpenAI searched.

Example

Riffer.configure do |config|
  config.openai.api_key = ENV['OPENAI_API_KEY']
end

class CodeReviewAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  instructions 'You are a code reviewer. Provide constructive feedback.'
  model_options temperature: 0.3, reasoning: 'medium'
end

agent = CodeReviewAgent.new
puts agent.generate("Review this code: def add(a,b); a+b; end")

Streaming

agent.stream("Explain Ruby blocks").each do |event|
  case event
  when Riffer::StreamEvents::TextDelta
    print event.content
  when Riffer::StreamEvents::ReasoningDelta
    # Extended thinking content
    print "[thinking] #{event.content}"
  when Riffer::StreamEvents::ReasoningDone
    puts "\n[reasoning complete]"
  end
end

Tool Calling

OpenAI provider converts tools to function calling format with strict mode:

class CalculatorTool < Riffer::Tool
  description "Performs basic math operations"

  params do
    required :operation, :string, enum: ["add", "subtract", "multiply", "divide"]
    required :a, :number, description: "First number"
    required :b, :number, description: "Second number"
  end

  def call(context:, operation:, a:, b:)
    result = case operation
    when "add" then a + b
    when "subtract" then a - b
    when "multiply" then a * b
    when "divide" then a / b
    end
    text(result.to_s)
  end
end

class MathAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  uses_tools [CalculatorTool]
end

Deferred Tools (experimental)

The OpenAI provider loads deferred tools natively:

class Assistant < Riffer::Agent
  model 'openai/gpt-5.4-mini'
  instructions "If you need a calendar tool you don't have, call connect_calendar first."

  uses_tools [ConnectCalendar]
  deferred_tools [ListEvents, CreateEvent]
end

A deferred tool is left out of the request’s tools. When a tool loads it, its full definition is sent in an additional_tools input item placed right after that tool’s function_call_output, and the model can call it from its next turn. tools stays the same for the whole conversation and earlier input items never change, so loading a tool keeps the prompt cache. The loading tool’s own output is empty.

Riffer rebuilds the additional_tools items from the loaded_tools on the conversation’s tool messages on every request, so a restored session, or one started on another provider, loads the same tools. A tool loaded again is sent again, after each result that loaded it: without fresh definitions, a model that reloads a tool it already has can keep calling the loading tool instead of the loaded one.

OpenAI returns a call to a loaded tool with a namespace field, and rejects a later request that replays the call without it. That namespace is always the tool’s own name as sent to OpenAI, so riffer adds it back to every replayed call to a deferred tool and never stores it. Tools, the session, callbacks and traces see an ordinary tool call.

With the gateway strategy, deferred_tools [...], strategy: :gateway, riffer sends the gateway instead of loading them natively.

Web search allows the model to search the web for up-to-date information. When enabled, the provider injects the web_search_preview tool into the request.

class SearchAgent < Riffer::Agent
  model 'openai/gpt-5-mini'
  model_options web_search: true
end

agent = SearchAgent.new
agent.stream("What's the latest Ruby release?").each do |event|
  case event
  when Riffer::StreamEvents::WebSearchStatus
    # OpenAI emits a full status sequence:
    # "in_progress" → "searching" → "open_page" → "completed"
    puts "[search: #{event.status}]"
    puts "  query: #{event.query}" if event.query
    puts "  url: #{event.url}" if event.url
  when Riffer::StreamEvents::WebSearchDone
    puts "[search complete: #{event.query}]"
  when Riffer::StreamEvents::TextDelta
    print event.content
  end
end

Note: OpenAI sources include url but not title. Each source in the sources array will have title: nil.

Message Format

The provider converts Riffer messages to OpenAI format:

Riffer Message OpenAI Role
System developer
User user
Assistant assistant
Tool function_call_output

Direct Provider Usage

provider = Riffer::Providers::OpenAI.new

response = provider.generate_text(
  prompt: "Hello!",
  model: "gpt-5-mini",
  temperature: 0.7
)

puts response.content