riffer 0.40.0 → 0.41.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c89776aeb032fbf837df103366fed830edcc20769cc9d4958a3a9bfa56a7803
-  data.tar.gz: 2153cf2967b9b70366987aeb9e59b215ff641bcd44668525c07d822ff9757579
+  metadata.gz: fd309de6be56bd5fbe778bbf277b9125dd63d4ce7b360c3e5e85554a944cb81d
+  data.tar.gz: 965daf888849a0386b2826af572fd95d0a7fb8a4ac6f9f91788acb0254705f8e
 SHA512:
-  metadata.gz: edfb2a10f17e1c0f6fb0630f5c2244370e01c5f32d05e9f065183da0b5b2d2cfec2453cac9a08714bd921716cd747609e4db61fb105a57769d79ab2f8988356a
-  data.tar.gz: 7d6dcdbab4be152033fcf75581252d3c9bda60c9e49825e75028d19670bae0490087ee8a90267a2af2f4fd8daabb5f370c8c2b7bb7cdcffe77a75b94a6b190ff
+  metadata.gz: deedbd28b2c79faceea167422fb69147cb2453d7e06df48c46c2eb1e601068de7b9018026675a973f6de6036373d324d5120fc43269e863dd43ce39b88ee7ea4
+  data.tar.gz: 2007cc98bd5955ae2db4776e72551d546038deea60be3e397a5838e028cd2901465f2fe9c00d944b18e4ce9508599bcd7603ad61e0e75efaa8264793461cf283

data/.agents/providers.md

@@ -5,9 +5,18 @@
 1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
 2. Implement the required hook methods (see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md) for the full API)
 3. Register in `Riffer::Providers::Repository::REPO`
-4. Add provider config to `Riffer::Config` if needed
+4. Add provider config to `Riffer::Config` if needed — a `Struct` with credential members plus a `client` member
 5. Create tests in `test/riffer/providers/your_provider_test.rb`
 
+## Constructor and client contract
+
+- Constructors take **no arguments** — define one only when the provider needs `depends_on`, and give it no parameters. Credentials live in config; never accept them as kwargs or hold them in ivars.
+- Never hold a client ivar; call the private `client` method from `execute_generate`/`execute_stream`. Base resolves: `global_client` (a client instance, or a no-argument Proc resolved on every call) → memoized `build_client`.
+- Providers hold no agent state — no context, no reference to the owning agent. Client selection is process-global by design, so a configured Proc takes no arguments.
+- Implement `build_client` (build the SDK client by reading `Riffer.config.<provider>.<credential>` directly) and override `global_client` to return `Riffer.config.<provider>.client`.
+- **Never pass an SDK an explicit nil credential.** Build the kwargs as a hash and `.compact` it, so an unset value stays _absent_: SDKs distinguish absent from nil to decide whether to read their own env vars, and an explicit nil suppresses that. Passing `base_url: nil` skips `OPENAI_BASE_URL` and pins requests to api.openai.com; passing `region: nil` makes the AWS SDK raise `MissingRegionError` even with `AWS_REGION` exported.
+- **Exception — a provider borrowing another vendor's SDK** (`OpenRouter` and `AzureOpenAI` reuse `::OpenAI::Client`) must keep its credential and endpoint concrete, nil included. Compacting there would let the OpenAI SDK fall back to `OPENAI_API_KEY` / `OPENAI_BASE_URL` and send one vendor's credential to another's endpoint. Compact a key only when the SDK's env fallback for it names the same service the provider talks to.
+
 ## Architecture
 
 The base class uses the **template method** pattern. The public methods `generate_text` and `stream_text` orchestrate the flow, delegating to hook methods that each provider implements:

data/.agents/rbs-inline.md

@@ -154,8 +154,8 @@ end
 
 ### Where stubs and stdlib deps live
 
-- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` declares the SDK-typed `@client` ivar).
-- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed ivars can't ship, so they go in `_private/riffer/providers/` (`@client`).
+- `sig/_private/` — signatures that must **not** ship. RBS **skips** `_`-prefixed directories in library mode, so consumers never load them; riffer's own `steep check` does (via the `Steepfile`). Two kinds, by predictable path: external-gem signatures are named by gem at the top level (`async.rbs`, `mcp.rbs`, `zeitwerk.rbs`, `openai.rbs`, `anthropic.rbs`, `aws-sdk-core/*` — full stubs for RBS-less gems plus arity patches for the provider SDKs); riffer's own hidden stubs mirror `lib/` under `riffer/` (e.g. `riffer/providers/anthropic.rbs` narrows the private `client` method to the SDK-typed client).
+- `sig/manual/` — hand-written riffer-only signatures that are **safe to ship**, for the few things rbs-inline can't generate _at all_ (mirroring `lib/`). In practice that's `extend self` modules (`riffer/agent/run.rbs`, `riffer/helpers/call_or_value.rbs`) and modeling an include applied dynamically (`riffer/tools/toolable.rbs`). SDK-free ivars are **not** hand-written here — declare them inline with `# @rbs` (see "Instance variables"). SDK-typed signatures can't ship, so they go in `_private/riffer/providers/` (the narrowed `client`).
 - `sig/manifest.yaml` — declares the **stdlib** RBS the shipped sigs reference (`uri`, `net-http`) so `rbs -r riffer` resolves them.
 
 ## Workflow

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.40.0"
+  ".": "0.41.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.41.0](https://github.com/janeapp/riffer/compare/riffer/v0.40.0...riffer/v0.41.0) (2026-08-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* Inference providers no longer support extra configuration parameters (e.g. timeouts). Instead, a provider client object can be defined in the riffer config directly. Credential and endpoint parameters are still supported.
+
+### Features
+
+* config-injected provider clients, retire provider_options ([#391](https://github.com/janeapp/riffer/issues/391)) ([72fa0e3](https://github.com/janeapp/riffer/commit/72fa0e32ff6cfeee29bae9e2618d001cbc387d99))
+
 ## [0.40.0](https://github.com/janeapp/riffer/compare/riffer/v0.39.0...riffer/v0.40.0) (2026-08-12)
 
 

data/README.md

@@ -45,31 +45,31 @@ puts agent.generate('Hello world')
 
 ## Documentation
 
-Comprehensive guides live at [docs.riffer.ai](https://docs.riffer.ai):
-
-- [Overview](https://docs.riffer.ai/guides/overview/) - Core concepts and architecture
-- [Getting Started](https://docs.riffer.ai/guides/getting-started/) - Installation and first steps
-- [Agents](https://docs.riffer.ai/guides/agents/) - Defining and configuring agents
-- [Agent Lifecycle](https://docs.riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
-- [Agent Loop](https://docs.riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
-- [Tools](https://docs.riffer.ai/guides/tools/) - Creating tools for agents
-- [Advanced Tools](https://docs.riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
-- [Messages](https://docs.riffer.ai/guides/messages/) - Message types and formats
-- [Stream Events](https://docs.riffer.ai/guides/stream-events/) - Streaming responses
-- [Configuration](https://docs.riffer.ai/guides/configuration/) - Framework configuration
-- [Evals](https://docs.riffer.ai/guides/evals/) - Evaluating agent quality
-- [Guardrails](https://docs.riffer.ai/guides/guardrails/) - Input/output validation
-- [Skills](https://docs.riffer.ai/guides/skills/) - Packaged agent capabilities
-- [MCP](https://docs.riffer.ai/guides/mcp/) - Integrating third-party MCP servers
-- [Serialization](https://docs.riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
-- [Tracing](https://docs.riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
-- [Providers](https://docs.riffer.ai/guides/providers/overview/) - LLM provider adapters
+Comprehensive guides live at [riffer.ai](https://riffer.ai):
+
+- [Overview](https://riffer.ai/guides/overview/) - Core concepts and architecture
+- [Getting Started](https://riffer.ai/guides/getting-started/) - Installation and first steps
+- [Agents](https://riffer.ai/guides/agents/) - Defining and configuring agents
+- [Agent Lifecycle](https://riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
+- [Agent Loop](https://riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
+- [Tools](https://riffer.ai/guides/tools/) - Creating tools for agents
+- [Advanced Tools](https://riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
+- [Messages](https://riffer.ai/guides/messages/) - Message types and formats
+- [Stream Events](https://riffer.ai/guides/stream-events/) - Streaming responses
+- [Configuration](https://riffer.ai/guides/configuration/) - Framework configuration
+- [Evals](https://riffer.ai/guides/evals/) - Evaluating agent quality
+- [Guardrails](https://riffer.ai/guides/guardrails/) - Input/output validation
+- [Skills](https://riffer.ai/guides/skills/) - Packaged agent capabilities
+- [MCP](https://riffer.ai/guides/mcp/) - Integrating third-party MCP servers
+- [Serialization](https://riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
+- [Tracing](https://riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
+- [Providers](https://riffer.ai/guides/providers/overview/) - LLM provider adapters
 
 The guide sources are in the [docs](docs/) directory.
 
 ### API Reference
 
-The full API reference is published at [docs.riffer.ai/api](https://docs.riffer.ai/api/). Preview the site locally with:
+The full API reference is published at [riffer.ai/api](https://riffer.ai/api/). Preview the site locally with:
 
 ```bash
 bin/rake docs:serve
@@ -140,7 +140,3 @@ All notable changes to this project are documented in `CHANGELOG.md`.
 ## License
 
 Licensed under the MIT License. See `LICENSE.txt` for details.
-
-## Maintainers
-
-- Jake Bottrall - https://github.com/bottrall

data/docs/AGENTS.md

@@ -128,17 +128,6 @@ end
 
 Loads tools from registered [MCP](MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
 
-### provider_options
-
-Passes options to the provider client:
-
-```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
-end
-```
-
 ### model_options
 
 Passes options to each LLM request:

data/docs/CONFIGURATION.md

@@ -9,12 +9,15 @@ Use `Riffer.configure` to set up provider credentials:
 ```ruby
 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.
+
 ## Accessing Configuration
 
 Access the current configuration via `Riffer.config`:
@@ -34,6 +37,66 @@ Riffer.config.anthropic.api_key
 
 For provider credentials and setup, see the individual [Provider guides](providers/PROVIDERS.md).
 
+### 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`:
+
+```ruby
+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'],
+    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`      | `Anthropic::Client`                                           |
+| Amazon Bedrock | `config.amazon_bedrock.client` | `Aws::BedrockRuntime::Client`                                 |
+| Gemini         | `config.gemini.client`         | `Riffer::Providers::Gemini::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.
+
+```ruby
+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](#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`, `ANTHROPIC_API_KEY`, 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 Gemini provider has no vendor SDK, so riffer ships its own transport: `Riffer::Providers::Gemini::Client` exposes `base_url`, `open_timeout`, `read_timeout`, `write_timeout`, and `proxy_address`/`proxy_port`. Anything implementing its two-method contract (`post`, `post_stream`) can be assigned to `config.gemini.client` — see [Gemini](providers/GEMINI.md).
+
 ### MCP (Model Context Protocol)
 
 Optional settings for [MCP server integrations](MCP.md):
@@ -113,10 +176,10 @@ Riffer.configure do |config|
 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.                                                                                                                  |
+| 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 `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
 ### Pricing
@@ -200,19 +263,6 @@ There is no per-call override and no customizable placeholder. Callers needing f
 
 Override global configuration at the agent level:
 
-### provider_options
-
-Pass options directly to the provider client:
-
-```ruby
-class MyAgent < Riffer::Agent
-  model 'openai/gpt-5-mini'
-
-  # Override API key for this agent only
-  provider_options api_key: ENV['CUSTOM_OPENAI_KEY']
-end
-```
-
 ### model_options
 
 Pass options to each LLM request:
@@ -305,17 +355,51 @@ end
 
 ## Multiple Configurations
 
-For different environments or use cases, use agent-level overrides:
+Provider credentials and clients are **global**, resolved per process. For different environments, branch at boot:
+
+```ruby
+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:
+
+```ruby
+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:
 
 ```ruby
 class ProductionAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['PRODUCTION_OPENAI_KEY']
 end
 
 class DevelopmentAgent < Riffer::Agent
   model 'openai/gpt-5-mini'
-  provider_options api_key: ENV['DEV_OPENAI_KEY']
-  model_options temperature: 0.0  # Deterministic for testing
+  model_options temperature: 0.0 # Deterministic for testing
 end
 ```

data/docs/SERIALIZATION.md

@@ -1,6 +1,6 @@
 # Serialization
 
-`Riffer::Agent::Serializer` turns a **resolved agent** into a self-contained, provider-neutral data hash (`to_h`) and reconstructs a **runnable agent** from that hash (`from_h`). Use it to persist agent definitions outside of code, or to transfer them across a process/service boundary.
+`Riffer::Agent::Serializer` turns a **resolved agent** into a provider-neutral data hash (`to_h`) and rebuilds an agent from that hash (`from_h`). The hash carries the agent **definition** — not the credentials or client it needs to reach a provider (see [Secrets](#secrets)). Use it to persist agent definitions outside of code, or to transfer them across a process/service boundary.
 
 You normally reach it through the delegators on `Riffer::Agent`:
 
@@ -43,7 +43,6 @@ The session is used **as-is**: the rebuilt agent does not prepend anything to it
   model:             "openai/gpt-4o",         # resolved "provider/model" string
   instructions:      "You are…",              # resolved system prompt
   model_options:     { temperature: 0.2 },
-  provider_options:  { … },                   # see the secrets warning below
   max_steps:         8,                        # integer; -1 = unlimited (see below)
   structured_output: { type: "object", … },   # JSON Schema, or null
   tools: [ { name:, description:, parameters_schema:, timeout: }, … ]
@@ -101,7 +100,9 @@ A finite integer round-trips as-is; a hash missing the key falls back to the def
 
 ## Secrets
 
-`provider_options` and `model_options` **ride on the wire as plain data** — they are part of the hash and _will_ transfer. Prefer configuring API keys via environment/global provider configuration rather than `provider_options`. **Never serialize an agent whose options carry sensitive values** — and if a serialized definition ever does, handle it as a secret (encrypt it, keep it out of logs).
+`model_options` **rides on the wire as plain data** — it is part of the hash and _will_ transfer. Keep sensitive values out of it; credentials live in global provider configuration and never serialize.
+
+The hash describes the agent, not how to authenticate as one. The destination process configures the provider itself — `config.<provider>.client`, or the credentials riffer builds a default client from. Clients resolve lazily on the first LLM call, so `from_h` succeeds in a process with no provider configuration; the `generate` is what fails. See [Configuration](CONFIGURATION.md).
 
 ## What does **not** transfer
 

data/docs/providers/AMAZON_BEDROCK.md

@@ -22,6 +22,8 @@ Riffer.configure do |config|
 end
 ```
 
+`region` resolves in order: `Riffer.config.amazon_bedrock.region` → the AWS SDK's own resolution (`AWS_REGION`, `AWS_DEFAULT_REGION`, shared config). Leaving it unset in riffer defers to the SDK rather than failing.
+
 ### Bearer Token Authentication
 
 For API token authentication:
@@ -33,15 +35,22 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+### Custom client
+
+AWS auth beyond the bearer token or default credential chain (profiles, STS, IRSA), plus retries, timeouts, and endpoints, is configured on your own `Aws::BedrockRuntime::Client`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'amazon_bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0'
-  provider_options region: 'us-west-2', api_token: ENV['BEDROCK_API_TOKEN']
+Riffer.configure do |config|
+  config.amazon_bedrock.client = Aws::BedrockRuntime::Client.new(
+    region: 'us-east-1',
+    credentials: Aws::AssumeRoleCredentials.new(role_arn: ENV['BEDROCK_ROLE_ARN'], role_session_name: 'riffer'),
+    retry_limit: 5
+  )
 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).
+
 ## Supported Models
 
 Use Bedrock model IDs in the `amazon_bedrock/model` format:
@@ -168,10 +177,7 @@ The provider converts Riffer messages to Bedrock format:
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::AmazonBedrock.new(
-  region: 'us-east-1',
-  api_token: ENV['BEDROCK_API_TOKEN']  # Optional
-)
+provider = Riffer::Providers::AmazonBedrock.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/ANTHROPIC.md

@@ -20,15 +20,19 @@ Riffer.configure do |config|
 end
 ```
 
-Or per-agent:
+For anything beyond the API key — timeouts, retries, proxies — supply your own `Anthropic::Client`:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'anthropic/claude-haiku-4-5-20251001'
-  provider_options api_key: ENV['ANTHROPIC_API_KEY']
+Riffer.configure do |config|
+  config.anthropic.client = Anthropic::Client.new(
+    api_key: ENV['ANTHROPIC_API_KEY'],
+    timeout: 60
+  )
 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).
+
 ## Supported Models
 
 Use Anthropic model IDs in the `anthropic/model` format:
@@ -224,9 +228,7 @@ The provider converts Riffer messages to Anthropic format:
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::Anthropic.new(
-  api_key: ENV['ANTHROPIC_API_KEY']
-)
+provider = Riffer::Providers::Anthropic.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/AZURE_OPENAI.md

@@ -14,9 +14,8 @@ gem 'openai'
 
 Credentials are resolved in order:
 
-1. Keyword arguments (`api_key`, `base_url`)
-2. Global config (`Riffer.config.azure_openai.api_key` / `.endpoint`)
-3. Environment variables (`AZURE_OPENAI_API_KEY` / `AZURE_OPENAI_ENDPOINT`)
+1. Global config (`Riffer.config.azure_openai.api_key` / `.endpoint`)
+2. Environment variables (`AZURE_OPENAI_API_KEY` / `AZURE_OPENAI_ENDPOINT`)
 
 ### Global config
 
@@ -27,16 +26,20 @@ Riffer.configure do |config|
 end
 ```
 
-### Per-agent
+### Custom client
+
+Azure AD token auth, timeouts, and retries are configured on your own `OpenAI::Client`. A `Proc` is the right shape for expiring AD tokens — it is resolved on every LLM call:
 
 ```ruby
-class MyAgent < Riffer::Agent
-  model 'azure_openai/gpt-5-mini'
-  provider_options api_key: ENV['AZURE_OPENAI_API_KEY'],
-                   base_url: ENV['AZURE_OPENAI_ENDPOINT']
+Riffer.configure do |config|
+  config.azure_openai.client = -> {
+    OpenAI::Client.new(api_key: AzureAd.current_token, base_url: ENV['AZURE_OPENAI_ENDPOINT'])
+  }
 end
 ```
 
+See [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
 ### Environment variables only
 
 If `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` are set, no explicit configuration is needed:
@@ -151,10 +154,7 @@ end
 ## Direct Provider Usage
 
 ```ruby
-provider = Riffer::Providers::AzureOpenAI.new(
-  api_key: ENV['AZURE_OPENAI_API_KEY'],
-  base_url: ENV['AZURE_OPENAI_ENDPOINT']
-)
+provider = Riffer::Providers::AzureOpenAI.new
 
 response = provider.generate_text(
   prompt: "Hello!",

data/docs/providers/CUSTOM_PROVIDERS.md

@@ -8,14 +8,14 @@ Extend `Riffer::Providers::Base` and implement the five required hook methods:
 
 ```ruby
 class Riffer::Providers::MyProvider < Riffer::Providers::Base
-  def initialize(**options)
-    # Initialize your client
-    @api_key = options[:api_key] || ENV['MY_PROVIDER_API_KEY']
-    @client = MyProviderClient.new(api_key: @api_key)
-  end
-
   private
 
+  # Client hook — see "Client resolution" below.
+
+  def build_client
+    MyProviderClient.new(api_key: ENV['MY_PROVIDER_API_KEY'])
+  end
+
   # Hook methods (matching base.rb order)
 
   def build_request_params(messages, model, options)
@@ -35,11 +35,11 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
   end
 
   def execute_generate(params)
-    @client.generate(**params)
+    client.generate(**params)
   end
 
   def execute_stream(params, yielder)
-    @client.stream(**params) do |chunk|
+    client.stream(**params) do |chunk|
       case chunk.type
       when :text
         yielder << Riffer::StreamEvents::TextDelta.new(chunk.content)
@@ -121,16 +121,30 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
 end
 ```
 
+## Client resolution
+
+Riffer constructs providers with `provider_class.new`, so `initialize` takes no arguments; read credentials from configuration inside `build_client`. `Riffer::Providers::Base` provides a private `client` method for your `execute_generate`/`execute_stream` to call. It resolves, in order:
+
+1. **A configured client** — whatever `global_client` returns: a client instance, or a no-argument `Proc` resolved on **every** call. Override that hook to read the client off your own configuration; it defaults to `nil`.
+2. **A memoized client** from `build_client` — implement this hook to build your SDK client from configured credentials.
+
+This gives your provider the same "works out of the box, bring your own client in production" behavior as the built-ins. See [Configuration → Provider Clients](../CONFIGURATION.md#provider-clients).
+
 ## Using depends_on
 
 For lazy loading of external gems:
 
 ```ruby
 class Riffer::Providers::MyProvider < Riffer::Providers::Base
-  def initialize(**options)
+  def initialize
+    super
     depends_on "my_provider_gem"  # Only loaded when provider is used
+  end
+
+  private
 
-    @client = ::MyProviderGem::Client.new(**options)
+  def build_client
+    ::MyProviderGem::Client.new(api_key: ENV["MY_PROVIDER_API_KEY"])
   end
 end
 ```
@@ -291,17 +305,19 @@ end
 # lib/riffer/providers/my_provider.rb
 
 class Riffer::Providers::MyProvider < Riffer::Providers::Base
-  def initialize(**options)
+  def initialize
+    super
     depends_on "my_provider_gem"
-
-    api_key = options[:api_key] || ENV["MY_PROVIDER_API_KEY"]
-    @client = ::MyProviderGem::Client.new(api_key: api_key)
   end
 
   private
 
   # Hook methods
 
+  def build_client
+    ::MyProviderGem::Client.new(api_key: ENV["MY_PROVIDER_API_KEY"])
+  end
+
   def build_request_params(messages, model, options)
     system_message = extract_system(messages)
     conversation = messages.reject { |m| m.is_a?(Riffer::Messages::System) }
@@ -323,13 +339,13 @@ class Riffer::Providers::MyProvider < Riffer::Providers::Base
   end
 
   def execute_generate(params)
-    @client.create(**params)
+    client.create(**params)
   end
 
   def execute_stream(params, yielder)
     accumulated_text = ""
 
-    @client.stream(**params) do |event|
+    client.stream(**params) do |event|
       case event.type
       when :text_delta
         accumulated_text += event.text