riffer 0.40.0 → 0.41.0

data/docs/providers/GEMINI.md

@@ -12,15 +12,38 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+## HTTP Client
+
+Gemini has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client`. The provider builds one from the configured `api_key` by default; construct your own to tune the HTTP knobs and assign it to `config.gemini.client`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'gemini/gemini-2.5-flash-lite'
-  provider_options api_key: ENV['GEMINI_API_KEY']
+Riffer.configure do |config|
+  config.gemini.client = Riffer::Providers::Gemini::Client.new(
+    api_key: ENV['GEMINI_API_KEY'],
+    read_timeout: 120
+  )
 end
 ```
 
+| Option          | Default                                     | Description                            |
+| --------------- | ------------------------------------------- | -------------------------------------- |
+| `api_key`       | `nil`                                       | Sent as the `x-goog-api-key` header    |
+| `base_url`      | `https://generativelanguage.googleapis.com` | API origin (proxies, regional mirrors) |
+| `open_timeout`  | `10`                                        | Connection-open timeout in seconds     |
+| `read_timeout`  | `60`                                        | Read timeout in seconds                |
+| `write_timeout` | `nil`                                       | Write timeout in seconds               |
+| `proxy_address` | `nil`                                       | HTTP proxy host                        |
+| `proxy_port`    | `nil`                                       | HTTP proxy port                        |
+
+The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
+The class is a default implementation, not a required base: any object implementing the two-method contract works, e.g. a Faraday-based or instrumented transport.
+
+| Method                                  | Contract                                                                                                                      |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `post(path, body)`                      | POST `body` as JSON to `path`; return the parsed response `Hash` (symbol keys); raise `Riffer::Error` on a non-success status |
+| `post_stream(path, body) { \|chunk\| }` | POST `body` as JSON to `path`; yield raw response body chunks; raise `Riffer::Error` on a non-success status                  |
+
 ## Supported Models
 
 Use Gemini model IDs in the `gemini/model` format:
@@ -62,7 +85,7 @@ model_options topP: 0.9
 ### Basic Generation
 
 ```ruby
-provider = Riffer::Providers::Gemini.new(api_key: ENV['GEMINI_API_KEY'])
+provider = Riffer::Providers::Gemini.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/OPENAI.md

@@ -20,12 +20,28 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+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`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['CUSTOM_API_KEY']
+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](../CONFIGURATION.md#provider-clients).
+
+For OpenAI-compatible servers (LiteLLM, vLLM, corporate gateways), configure a `base_url`:
+
+```ruby
+Riffer.configure do |config|
+  config.openai.api_key = ENV['GATEWAY_KEY']
+  config.openai.base_url = 'http://localhost:4000/v1'
 end
 ```
 
@@ -185,7 +201,7 @@ The provider converts Riffer messages to OpenAI format:
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::OpenAI.new(api_key: ENV['OPENAI_API_KEY'])
+provider = Riffer::Providers::OpenAI.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/OPENROUTER.md

@@ -24,16 +24,21 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+The `api_key` resolves in order: `Riffer.config.openrouter.api_key` → `ENV['OPENROUTER_API_KEY']`.
+
+For anything beyond the API key — timeouts, retries, proxies — supply your own `OpenAI::Client` pinned to the OpenRouter endpoint:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'openrouter/anthropic/claude-sonnet-4.6'
-  provider_options api_key: ENV['MY_OR_KEY']
+Riffer.configure do |config|
+  config.openrouter.client = OpenAI::Client.new(
+    api_key: ENV['OPENROUTER_API_KEY'],
+    base_url: 'https://openrouter.ai/api/v1',
+    timeout: 60
+  )
 end
 ```
 
-The `api_key` resolves in order: keyword arg → `Riffer.config.openrouter.api_key` → `ENV['OPENROUTER_API_KEY']`.
+The setting accepts a client instance or a no-argument `Proc`, resolved on every LLM call — see [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
 
 ## Supported Models
 
@@ -229,7 +234,7 @@ User messages with files become multi-part content (`image_url` for images, `fil
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::OpenRouter.new(api_key: ENV['OPENROUTER_API_KEY'])
+provider = Riffer::Providers::OpenRouter.new
 
 response = provider.generate_text(
   prompt: 'Hello!',

data/docs/providers/PROVIDERS.md

@@ -30,6 +30,21 @@ class MyAgent < Riffer::Agent
 end
 ```
 
+## Credentials and Clients
+
+Every credential comes from configuration: `Riffer::Providers::OpenAI.new` takes no arguments.
+
+| Provider       | Configured credentials                                            |
+| -------------- | ----------------------------------------------------------------- |
+| OpenAI         | `config.openai.api_key`, `config.openai.base_url`                 |
+| Azure OpenAI   | `config.azure_openai.api_key`, `config.azure_openai.endpoint`     |
+| Anthropic      | `config.anthropic.api_key`                                        |
+| Amazon Bedrock | `config.amazon_bedrock.api_token`, `config.amazon_bedrock.region` |
+| Gemini         | `config.gemini.api_key`                                           |
+| OpenRouter     | `config.openrouter.api_key`                                       |
+
+Out of the box, each provider builds an SDK client from these credentials. Everything else — timeouts, retries, proxies, custom auth — is configured by assigning your own client (an instance, or a `Proc` resolved on every LLM call) to `Riffer.config.<provider>.client`. See [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
 ## Provider Interface
 
 All providers inherit from `Riffer::Providers::Base` and implement:
@@ -39,7 +54,7 @@ All providers inherit from `Riffer::Providers::Base` and implement:
 Generates a response synchronously:
 
 ```ruby
-provider = Riffer::Providers::OpenAI.new(api_key: "...")
+provider = Riffer::Providers::OpenAI.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/lib/riffer/agent/config.rb

@@ -16,9 +16,6 @@ class Riffer::Agent::Config
   # The configured instructions.
   attr_reader :instructions #: (String | Proc)?
 
-  # Options passed to the provider client.
-  attr_accessor :provider_options #: Hash[Symbol, untyped]
-
   # Options passed to generate_text/stream_text.
   attr_accessor :model_options #: Hash[Symbol, untyped]
 
@@ -50,7 +47,6 @@ class Riffer::Agent::Config
   #    ?identifier: String?,
   #    ?model: (String | Proc)?,
   #    ?instructions: (String | Proc)?,
-  #    ?provider_options: Hash[Symbol, untyped],
   #    ?model_options: Hash[Symbol, untyped],
   #    ?structured_output: Riffer::Params?,
   #    ?max_steps: Numeric?,
@@ -64,7 +60,6 @@ class Riffer::Agent::Config
     identifier: nil,
     model: nil,
     instructions: nil,
-    provider_options: {},
     model_options: {},
     structured_output: nil,
     max_steps: DEFAULT_MAX_STEPS,
@@ -74,7 +69,6 @@ class Riffer::Agent::Config
     skills_config: nil,
     guardrails: { before: [], after: [] }
   )
-    @provider_options = provider_options
     @model_options = model_options
     @max_steps = max_steps
     @tools_config = tools_config

data/lib/riffer/agent/serializer.rb

@@ -37,7 +37,6 @@ module Riffer::Agent::Serializer
       model: "#{agent.provider_name}/#{agent.model_name}",
       instructions: agent.instruction_message&.content,
       model_options: config.model_options,
-      provider_options: config.provider_options,
       max_steps: encode_max_steps(config.max_steps),
       structured_output: config.structured_output&.to_json_schema(strict: false),
       tools: agent.tools.map { |tool_class| tool_descriptor(tool_class) },
@@ -96,7 +95,6 @@ module Riffer::Agent::Serializer
       identifier: hash[:identifier],
       model: hash[:model],
       instructions: hash[:instructions],
-      provider_options: hash[:provider_options] || {},
       model_options: hash[:model_options] || {},
       structured_output: decode_structured_output(hash[:structured_output]),
       max_steps: decode_max_steps(hash),

data/lib/riffer/agent.rb

@@ -57,14 +57,6 @@ class Riffer::Agent
     value.nil? ? config.instructions : (config.instructions = value)
   end
 
-  # Gets or sets provider options passed to the provider client.
-  #
-  #--
-  #: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
-  def self.provider_options(options = nil)
-    options.nil? ? config.provider_options : (config.provider_options = options)
-  end
-
   # Gets or sets model options passed to generate_text/stream_text.
   #
   #--
@@ -408,7 +400,7 @@ class Riffer::Agent
     provider_class = Riffer::Providers::Repository.find(@provider_name)
     raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless provider_class
 
-    provider_class.new(**@config.provider_options)
+    provider_class.new
   end
 
   #--

data/lib/riffer/config.rb

@@ -3,12 +3,12 @@
 
 # Configuration for the Riffer framework.
 class Riffer::Config
-  AmazonBedrock = Struct.new(:api_token, :region)
-  Anthropic = Struct.new(:api_key)
-  AzureOpenAI = Struct.new(:api_key, :endpoint)
-  Gemini = Struct.new(:api_key, :open_timeout, :read_timeout)
-  OpenAI = Struct.new(:api_key)
-  OpenRouter = Struct.new(:api_key)
+  AmazonBedrock = Struct.new(:api_token, :region, :client)
+  Anthropic = Struct.new(:api_key, :client)
+  AzureOpenAI = Struct.new(:api_key, :endpoint, :client)
+  Gemini = Struct.new(:api_key, :client)
+  OpenAI = Struct.new(:api_key, :base_url, :client)
+  OpenRouter = Struct.new(:api_key, :client)
   Evals = Struct.new(:judge_model)
   Mcp = Struct.new(:credentials, :discovery_runner)
 

data/lib/riffer/evals/judge.rb

@@ -6,7 +6,6 @@ require "json"
 # Executes LLM-as-judge evaluations, using tool calling internally to get
 # structured output from the judge model.
 class Riffer::Evals::Judge
-  # @rbs @provider_options: Hash[Symbol, untyped]
   # @rbs @provider_instance: Riffer::Providers::Base?
   # @rbs @provider_name: String?
   # @rbs @model_name: String?
@@ -33,15 +32,14 @@ class Riffer::Evals::Judge
 
   # Raises Riffer::ArgumentError unless +model+ is "provider/model" format.
   #--
-  #: (model: String, ?provider_options: Hash[Symbol, untyped]) -> void
-  def initialize(model:, provider_options: {})
+  #: (model: String) -> void
+  def initialize(model:)
     provider_name, model_name = model.split("/", 2)
     unless [provider_name, model_name].all? { |part| part.is_a?(String) && !part.strip.empty? }
       raise Riffer::ArgumentError, "Invalid model string: #{model}"
     end
 
     @model = model
-    @provider_options = provider_options
   end
 
   # Evaluates an input/output pair using the configured LLM.
@@ -92,7 +90,7 @@ class Riffer::Evals::Judge
       provider_class = Riffer::Providers::Repository.find(provider_name)
       raise Riffer::ArgumentError, "Provider not found: #{provider_name}" unless provider_class
 
-      provider_class.new(**@provider_options)
+      provider_class.new
     end
   end
 

data/lib/riffer/providers/amazon_bedrock.rb

@@ -37,28 +37,40 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   end
 
   #--
-  #: (?api_token: String?, ?region: String?, **untyped) -> void
-  def initialize(api_token: nil, region: nil, **)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "aws-sdk-bedrockruntime"
-
-    api_token ||= Riffer.config.amazon_bedrock.api_token
-    region ||= Riffer.config.amazon_bedrock.region
-
-    @client = if api_token && !api_token.empty?
-                Aws::BedrockRuntime::Client.new(
-                  region: region,
-                  token_provider: Aws::StaticTokenProvider.new(api_token),
-                  auth_scheme_preference: ["httpBearerAuth"],
-                  **,
-                )
-              else
-                Aws::BedrockRuntime::Client.new(region: region, **)
-              end
   end
 
   private
 
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.amazon_bedrock.client
+  end
+
+  # Compacted so an unset region stays absent: the AWS SDK resolves +AWS_REGION+
+  # and the shared config only for a missing argument, and raises
+  # +Aws::Errors::MissingRegionError+ on an explicit nil.
+  #--
+  #: () -> untyped
+  def build_client
+    api_token = Riffer.config.amazon_bedrock.api_token
+    region = Riffer.config.amazon_bedrock.region
+
+    if api_token && !api_token.empty?
+      Aws::BedrockRuntime::Client.new(**{
+        region: region,
+        token_provider: Aws::StaticTokenProvider.new(api_token),
+        auth_scheme_preference: ["httpBearerAuth"],
+      }.compact)
+    else
+      Aws::BedrockRuntime::Client.new(**{ region: region }.compact)
+    end
+  end
+
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def build_request_params(messages, model, options)
@@ -137,7 +149,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.converse(**params)
+    client.converse(**params)
   end
 
   #--
@@ -227,7 +239,7 @@ class Riffer::Providers::AmazonBedrock < Riffer::Providers::Base
       tool_call: nil,
     } #: Hash[Symbol, untyped]
 
-    @client.converse_stream(**params) do |stream|
+    client.converse_stream(**params) do |stream|
       stream.on_event do |event|
         case event
         when Aws::BedrockRuntime::Types::ContentBlockStartEvent

data/lib/riffer/providers/anthropic.rb

@@ -30,17 +30,28 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (?api_key: String?, **untyped) -> void
-  def initialize(api_key: nil, **)
-    super()
+  #: () -> void
+  def initialize
+    super
     depends_on "anthropic"
+  end
 
-    api_key ||= Riffer.config.anthropic.api_key
+  private
 
-    @client = ::Anthropic::Client.new(api_key: api_key, **)
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.anthropic.client
   end
 
-  private
+  # Compacted for the same reason as the other providers: never hand an SDK an
+  # explicit nil credential, so its own +ANTHROPIC_API_KEY+ resolution stays
+  # reachable regardless of how that SDK distinguishes nil from absent.
+  #--
+  #: () -> untyped
+  def build_client
+    ::Anthropic::Client.new(**{ api_key: Riffer.config.anthropic.api_key }.compact)
+  end
 
   #--
   #: (Array[Riffer::Messages::Base], String?, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
@@ -97,7 +108,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   #--
   #: (Hash[Symbol, untyped]) -> untyped
   def execute_generate(params)
-    @client.messages.create(**params)
+    client.messages.create(**params)
   end
 
   #--
@@ -193,7 +204,7 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
 
     # Workaround for anthropics/anthropic-sdk-ruby#182: force identity
     # encoding so Net::HTTP/Zlib doesn't buffer SSE chunks until EOF.
-    stream = @client.messages.stream(
+    stream = client.messages.stream(
       **params,
       request_options: { extra_headers: { "accept-encoding" => "identity" } },
     )

data/lib/riffer/providers/azure_open_ai.rb

@@ -2,8 +2,8 @@
 # rbs_inline: enabled
 
 # Azure OpenAI provider for GPT models hosted on Azure. Requires the +openai+
-# gem. Credentials resolve from kwargs, then config, then
-# +AZURE_OPENAI_API_KEY+ / +AZURE_OPENAI_ENDPOINT+.
+# gem. Credentials resolve from config, then +AZURE_OPENAI_API_KEY+ /
+# +AZURE_OPENAI_ENDPOINT+.
 class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
   # The GenAI semconv well-known provider name.
   #--
@@ -12,15 +12,23 @@ class Riffer::Providers::AzureOpenAI < Riffer::Providers::OpenAI
     "azure.ai.openai"
   end
 
+  private
+
+  #--
+  #: () -> untyped
+  def global_client
+    Riffer.config.azure_openai.client
+  end
+
+  # Deliberately not compacted: this borrows the OpenAI SDK to talk to Azure, so
+  # omitting an unset argument would let the SDK fall back to +OPENAI_API_KEY+
+  # and +OPENAI_BASE_URL+ — sending Azure traffic, and an OpenAI credential, to
+  # whatever those name. Passing nil raises in the SDK instead.
   #--
-  #: (**untyped) -> void
-  def initialize(**options)
-    api_key = options.fetch(:api_key) do
-      Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
-    end
-    base_url = options.fetch(:base_url) do
-      Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
-    end
-    super(api_key: api_key, base_url: base_url, **options.except(:api_key, :base_url))
+  #: () -> untyped
+  def build_client
+    api_key = Riffer.config.azure_openai.api_key || ENV.fetch("AZURE_OPENAI_API_KEY", nil)
+    base_url = Riffer.config.azure_openai.endpoint || ENV.fetch("AZURE_OPENAI_ENDPOINT", nil)
+    ::OpenAI::Client.new(api_key: api_key, base_url: base_url)
   end
 end

data/lib/riffer/providers/base.rb

@@ -10,6 +10,7 @@ require "json"
 class Riffer::Providers::Base
   # @rbs @current_tools: Array[singleton(Riffer::Tool)]
   # @rbs @current_model: String?
+  # @rbs @client: untyped
 
   WIRE_SEPARATOR = "__" #: String
 
@@ -105,6 +106,33 @@ class Riffer::Providers::Base
     Riffer::Helpers::Dependencies.depends_on(gem_name)
   end
 
+  # Returns the client for the current LLM call. A configured client wins,
+  # resolved on every call so a Proc can vary the client by process or
+  # credential lifetime; otherwise the provider builds one from the configured
+  # credentials, memoized for the life of the provider.
+  #--
+  #: () -> untyped
+  def client
+    configured = global_client
+    return Riffer::Helpers::CallOrValue.resolve(configured) if configured
+
+    @client ||= build_client
+  end
+
+  # Returns the consumer-configured client for this provider; nil when none is
+  # configured, and for providers that take no configuration at all.
+  #--
+  #: () -> untyped
+  def global_client
+    nil
+  end
+
+  #--
+  #: () -> untyped
+  def build_client
+    raise NotImplementedError, "Subclasses must implement #build_client"
+  end
+
   #--
   #: (String) -> String
   def encode_tool_name(name)

data/lib/riffer/providers/gemini/client.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "json"
+require "net/http"
+require "uri"
+
+# HTTP transport for the Gemini REST API. Riffer builds one from the
+# configured +api_key+ by default; construct your own to tune the HTTP knobs
+# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
+# implementing +post+ and +post_stream+ with these contracts works there —
+# the class is a default implementation, not a required base.
+#
+#   Riffer.configure do |config|
+#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
+#       api_key: ENV["GEMINI_API_KEY"],
+#       read_timeout: 120
+#     )
+#   end
+class Riffer::Providers::Gemini::Client
+  # @rbs @api_key: String?
+  # @rbs @base_url: String
+  # @rbs @open_timeout: Integer
+  # @rbs @read_timeout: Integer
+  # @rbs @write_timeout: Integer?
+  # @rbs @proxy_address: String?
+  # @rbs @proxy_port: Integer?
+
+  DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com" #: String
+  DEFAULT_OPEN_TIMEOUT = 10 #: Integer
+  DEFAULT_READ_TIMEOUT = 60 #: Integer
+
+  #: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
+  def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, open_timeout: DEFAULT_OPEN_TIMEOUT,
+                 read_timeout: DEFAULT_READ_TIMEOUT, write_timeout: nil,
+                 proxy_address: nil, proxy_port: nil)
+    @api_key = api_key
+    @base_url = base_url
+    @open_timeout = open_timeout
+    @read_timeout = read_timeout
+    @write_timeout = write_timeout
+    @proxy_address = proxy_address
+    @proxy_port = proxy_port
+  end
+
+  # POSTs a JSON body to an API path and returns the parsed response hash.
+  # Raises Riffer::Error when the API responds with a non-success status.
+  #--
+  #: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+  def post(path, body)
+    uri = URI("#{@base_url}/#{path}")
+    response = start_http(uri) { |http| http.request(build_request(uri, body)) }
+    handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+    JSON.parse(response.body, symbolize_names: true)
+  end
+
+  # POSTs a JSON body to an API path, yielding raw response body chunks as
+  # they arrive. Raises Riffer::Error when the API responds with a
+  # non-success status.
+  #--
+  #: (String, Hash[Symbol, untyped]) { (String) -> void } -> void
+  def post_stream(path, body, &block)
+    uri = URI("#{@base_url}/#{path}")
+    start_http(uri) do |http|
+      http.request(build_request(uri, body)) do |response|
+        handle_api_error!(response) unless response.is_a?(Net::HTTPSuccess)
+
+        begin
+          response.read_body(&block)
+        rescue IOError
+          # A pre-buffered body (VCR/WebMock playback) raises IOError on a
+          # streaming read; hand over the full body instead.
+          yield(response.body)
+        end
+      end
+    end
+  end
+
+  private
+
+  #--
+  #: (URI::Generic, Hash[Symbol, untyped]) -> Net::HTTP::Post
+  def build_request(uri, body)
+    request = Net::HTTP::Post.new(uri)
+    request["Content-Type"] = "application/json"
+    request["x-goog-api-key"] = @api_key
+    request.body = body.to_json
+    request
+  end
+
+  #--
+  #: [R] (URI::Generic) { (Net::HTTP) -> R } -> R
+  def start_http(uri, &)
+    host = uri.hostname #: String
+    options = {
+      use_ssl: uri.scheme == "https",
+      open_timeout: @open_timeout,
+      read_timeout: @read_timeout,
+    } #: Hash[Symbol, untyped]
+    options[:write_timeout] = @write_timeout if @write_timeout
+
+    if @proxy_address
+      Net::HTTP.start(host, uri.port, @proxy_address, @proxy_port, nil, nil, **options, &)
+    else
+      Net::HTTP.start(host, uri.port, **options, &)
+    end
+  end
+
+  #--
+  #: (Net::HTTPResponse) -> void
+  def handle_api_error!(response)
+    parsed = begin
+      JSON.parse(response.body, symbolize_names: true)
+    rescue JSON::ParserError
+      { message: response.body }
+    end
+    error_message = parsed.dig(:error, :message) || parsed[:message] || response.body
+    raise Riffer::Error, "Gemini API error (#{response.code}): #{error_message}"
+  end
+end