llm_conductor 1.8.2 → 1.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8a13bccd45a0d886de6bc88a531724a2e929912d21564f5c50296c000c28476a
-  data.tar.gz: 1838b42538d448dc2373b1e7e9180b92b1f97fe87dfd8b50b18a164ac992ffae
+  metadata.gz: ae52774bedf1066c7a420926f11404840691b648189698d0a8ba6ba9a3c60aa1
+  data.tar.gz: 320524f99596447ffe77593901cb15a0b97143c6611225726371b8bedf25b1fc
 SHA512:
-  metadata.gz: aeac7323ebde9d6327f9e536876d42f951d5e042f37888f6d0cb0dc64aaa50fd820c94cf4788a6ebde8b9e27423d67872f99a87c6ff6400f910cb07fbf37cfbc
-  data.tar.gz: 20dcb4c95317a32eaa033bbf0dadfdfa3aef5934818fbc491fd13b9e467edbe5a2b332d3234ee9f7b7181900a0a35294d356417c759c5cb736a476592ac670cf
+  metadata.gz: 5b2d29f7a17e40c0fc12162ebda9057575b9db4576e4b62dbf3223be201ca82c12e39ca946cf5d85344e435d7039838562fdf2f9b97e3355ee831ee62c06d209
+  data.tar.gz: 41dfa8fd00c686a9d032a6d47f4953a401e2cb8e306c315f69d016277bc2b163950a660fdba0a483518c802905fe36ec349833c631c5de9e7019ec909bd8b98a

data/.rubocop.yml

@@ -40,8 +40,6 @@ Metrics/MethodLength:
   Max: 15
   Exclude:
     - 'lib/llm_conductor/prompts.rb'
-    - 'lib/llm_conductor/clients/openrouter_client.rb'
-    - 'lib/llm_conductor/clients/zai_client.rb'
     - 'lib/llm_conductor/client_factory.rb'
     - 'lib/llm_conductor/eval/**/*'
     - 'examples/*.rb'
@@ -101,8 +99,6 @@ Metrics/BlockLength:
 Metrics/AbcSize:
   Exclude:
     - 'lib/llm_conductor/prompts.rb'
-    - 'lib/llm_conductor/clients/openrouter_client.rb'
-    - 'lib/llm_conductor/clients/zai_client.rb'
     - 'lib/llm_conductor/eval/**/*'
     - 'examples/*.rb'
 
@@ -117,16 +113,12 @@ Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/llm_conductor.rb'
     - 'lib/llm_conductor/prompts.rb'
-    - 'lib/llm_conductor/clients/openrouter_client.rb'
-    - 'lib/llm_conductor/clients/zai_client.rb'
     - 'lib/llm_conductor/eval/**/*'
     - 'examples/*.rb'
 
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/llm_conductor/prompts.rb'
-    - 'lib/llm_conductor/clients/openrouter_client.rb'
-    - 'lib/llm_conductor/clients/zai_client.rb'
     - 'lib/llm_conductor/eval/**/*'
 
 Layout/LineLength:

data/README.md

@@ -9,6 +9,7 @@ A unified Ruby interface for multiple Language Model providers from [Ekohe](http
 - 🖼️ **Vision Support** - Send images alongside text (OpenAI, Anthropic, OpenRouter, Z.ai, Gemini)
 - 🔧 **Custom Parameters** - Fine-tune with temperature, top_p, and more
 - 💰 **Cost Tracking** - Automatic token counting and cost estimation
+- ♻️ **Automatic Retries** - Exponential backoff with jitter on rate limits and transient errors
 - ⚡ **Smart Configuration** - Environment variables or code-based setup
 - 📊 **Model Evaluation** - Compare models/vendors on cost, latency, tokens & LLM-judged quality (opt-in)
 
@@ -91,7 +92,11 @@ export ZAI_API_KEY=your-key-here
 ```ruby
 LlmConductor.configure do |config|
   config.default_model = 'gpt-4o-mini'
-  
+
+  # Retries on transient failures (see "Retries & Rate Limits" below)
+  config.max_retries = 3   # total attempts, including the first
+  config.retry_delay = 1.0 # seconds; seeds the exponential backoff
+
   config.openai(api_key: ENV['OPENAI_API_KEY'])
   config.anthropic(api_key: ENV['ANTHROPIC_API_KEY'])
   config.gemini(api_key: ENV['GEMINI_API_KEY'])
@@ -102,13 +107,35 @@ LlmConductor.configure do |config|
 end
 ```
 
+### Retries & Rate Limits
+
+Transient provider failures are retried automatically for **every** provider — the
+policy lives in `BaseClient`, driven by the two settings above.
+
+```ruby
+config.max_retries = 3   # TOTAL attempts, not extra ones. 1 disables retrying.
+config.retry_delay = 1.0 # first retry after ~1s, the next after ~2s (doubling)
+```
+
+**Retried**: `429`, `500`, `502`, `503`, `504`, `408`, and connection/read timeouts.
+**Not retried**: `400`, `401`, `403`, `404`, `422` and TLS errors — a malformed
+request or a bad credential is identical on attempt two, so it surfaces immediately.
+
+Backoff is exponential with additive jitter, so a retry never fires sooner than
+configured but concurrent workers do not retry in lockstep. A `Retry-After` header
+takes precedence when the provider sends one. With `config.logger` set, each retry
+logs one line (attempt, status, delay — never the API key).
+
+Retries ride out short spikes; they do not survive a sustained quota outage.
+See the **[Retries & Rate Limits Guide](docs/retries.md)** for the full policy.
+
 ## Supported Providers
 
 | Provider | Auto-Detect | Vision | Custom Params |
 |----------|-------------|--------|---------------|
 | OpenAI (GPT) | ✅ `gpt-*` | ✅ | 🔜 |
 | Anthropic (Claude) | ✅ `claude-*` | ✅ | 🔜 |
-| Google (Gemini) | ✅ `gemini-*` | ✅ | 🔜 |
+| Google (Gemini) | ✅ `gemini-*` | ✅ | ✅ |
 | Groq | ✅ `llama/mixtral` | ❌ | 🔜 |
 | Ollama | ✅ (default) | ❌ | ✅ |
 | OpenRouter | 🔧 Manual | ✅ | 🔜 |
@@ -150,6 +177,20 @@ response = LlmConductor.generate(
 )
 ```
 
+### Fast Gemini Calls (Minimal Thinking)
+
+```ruby
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_level: 'minimal' }
+)
+```
+
+Sent to Gemini as `generationConfig.thinkingConfig.thinkingLevel`. See
+[Custom Parameters](docs/custom-parameters.md#gemini-thinking-configuration).
+
 ### Vision Analysis
 
 ```ruby
@@ -318,6 +359,7 @@ See [`examples/model_eval_usage.rb`](examples/model_eval_usage.rb) for a complet
 ## Documentation
 
 - **[Custom Parameters Guide](docs/custom-parameters.md)** - Temperature, top_p, and more
+- **[Retries & Rate Limits Guide](docs/retries.md)** - Backoff, jitter and which statuses are retried
 - **[Vision Support Guide](docs/vision-support.md)** - Using images with LLMs
 - **[Model Evaluation](#model-evaluation-opt-in)** - Compare models on cost, latency & LLM-judged quality
 - **[Examples](examples/)** - Working code examples for all providers
@@ -328,6 +370,8 @@ Check the [examples/](examples/) directory for comprehensive examples:
 
 - `simple_usage.rb` - Basic text generation
 - `ollama_params_usage.rb` - Custom parameters with Ollama
+- `gemini_thinking_usage.rb` - Gemini thinking configuration (`thinkingConfig`)
+- `retry_config_usage.rb` - Retry configuration and the resulting backoff curve
 - `gpt_vision_usage.rb` - Vision with OpenAI
 - `claude_vision_usage.rb` - Vision with Anthropic
 - `gemini_vision_usage.rb` - Vision with Gemini

data/config/initializers/llm_conductor.rb

@@ -8,6 +8,10 @@ LlmConductor.configure do |config|
   config.default_model = 'gpt-5-mini'
   config.default_vendor = :openai
   config.timeout = 30
+  # Retries on transient failures (429/5xx, connection & read timeouts).
+  # max_retries is the TOTAL attempt budget including the first call, so 3 means
+  # one call plus at most two retries. retry_delay seeds an exponential backoff
+  # (~1s, ~2s, ~4s ...) with jitter. See docs/retries.md.
   config.max_retries = 3
   config.retry_delay = 1.0
   # Use Ruby's built-in Logger class directly

data/docs/README.md

@@ -11,8 +11,17 @@ Learn how to fine-tune LLM generation with parameters like `temperature`, `top_p
 - Provider-specific parameters
 - Best practices and use cases
 
-**Currently supported**: Ollama  
-**Coming soon**: OpenAI, Anthropic, Gemini, Groq, OpenRouter, Z.ai
+**Currently supported**: Ollama, Gemini (including Gemini 3.x `thinkingConfig`)  
+**Coming soon**: OpenAI, Anthropic, Groq, OpenRouter, Z.ai
+
+### [Retries & Rate Limits](retries.md)
+How `max_retries` and `retry_delay` drive automatic retries. Includes:
+- Which statuses are retried, and which deliberately are not
+- The exponential backoff formula and its jitter
+- `Retry-After` handling
+- What retries fix, and what they do not
+
+**Applies to**: every provider — the policy lives in `BaseClient`
 
 ### [Vision Support](vision-support.md)
 Complete guide to using vision/multimodal capabilities. Includes:

data/docs/custom-parameters.md

@@ -149,6 +149,13 @@ Below are common parameters supported by Google Gemini via `generationConfig`. F
 | `max_output_tokens` | `maxOutputTokens` | Integer | Alias for max_tokens |
 | `candidate_count` | `candidateCount` | Integer | Number of candidates to return |
 | `stop_sequences` | `stopSequences` | Array | Stop sequences that end generation |
+| `thinking_config` | `thinkingConfig` | Hash | Gemini 3.x thinking controls (see below) |
+| `thinking_level` | `thinkingConfig.thinkingLevel` | String | Thinking depth: `'minimal'`, `'low'`, `'high'` |
+| `thinking_budget` | `thinkingConfig.thinkingBudget` | Integer | Token budget for thinking (`0` disables it) |
+| `include_thoughts` | `thinkingConfig.includeThoughts` | Boolean | Return the thought summary alongside the answer |
+
+Unsupported keys are skipped and logged as a warning through
+`LlmConductor.configuration.logger` — they are never dropped silently.
 
 ### Gemini Usage Examples
 
@@ -170,6 +177,36 @@ response = LlmConductor.generate(
 )
 ```
 
+### Gemini Thinking Configuration
+
+Gemini 3.x models think before answering. Cutting that budget down is the single
+biggest latency lever available on the fast models, so the thinking controls are
+exposed through the same `params` hash:
+
+```ruby
+# Fastest path — minimal thinking (flat convenience key)
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_level: 'minimal', temperature: 0.0 }
+)
+
+# Nested form — mirrors the API shape, accepts snake_case or camelCase
+response = LlmConductor.generate(
+  model: 'gemini-3.5-flash-lite',
+  prompt: 'Extract the company name from: ...',
+  vendor: :gemini,
+  params: { thinking_config: { thinking_level: 'minimal', thinking_budget: 0 } }
+)
+```
+
+Both forms are merged into the request as:
+
+```json
+{ "generationConfig": { "thinkingConfig": { "thinkingLevel": "minimal" } } }
+```
+
 ## Ollama Parameters Reference
 
 Below are common parameters supported by Ollama. For a complete list, see the [Ollama documentation](https://github.com/ollama/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values).
@@ -348,7 +385,8 @@ Always refer to your provider's documentation for supported parameters.
 
 Currently, custom parameters are fully supported for:
 - ✅ **Ollama**
-- ✅ **Google (Gemini)** — maps snake_case Ruby keys to camelCase `generationConfig`
+- ✅ **Google (Gemini)** — maps snake_case Ruby keys to camelCase `generationConfig`,
+  including `thinkingConfig` for Gemini 3.x thinking controls
 
 Coming soon:
 - 🔜 OpenAI (GPT)
@@ -364,6 +402,8 @@ Coming soon:
 1. Check parameter spelling (case-sensitive)
 2. Verify your provider supports the parameter
 3. Check parameter value types (integer vs float vs string)
+4. Set `config.logger` — Gemini logs a warning for every param it cannot map,
+   e.g. `Skipping generationConfig param :reasoning_effort: no Gemini API mapping.`
 
 ### Unexpected Output
 
@@ -379,7 +419,9 @@ Coming soon:
 
 ## Examples
 
-See the complete example file: [examples/ollama_params_usage.rb](examples/ollama_params_usage.rb)
+See the complete example files:
+- [examples/ollama_params_usage.rb](../examples/ollama_params_usage.rb)
+- [examples/gemini_thinking_usage.rb](../examples/gemini_thinking_usage.rb)
 
 ## Resources
 

data/docs/retries.md

@@ -0,0 +1,130 @@
+# Retries & Rate Limits Guide
+
+Transient provider failures — a rate limit, an overloaded region, a dropped
+connection — are retried automatically, with exponential backoff seeded from your
+configuration.
+
+## 🚀 Quick Reference
+
+```ruby
+LlmConductor.configure do |config|
+  config.max_retries = 3   # total attempts, including the first one
+  config.retry_delay = 1.0 # seconds; seeds the exponential backoff
+  config.logger = Logger.new($stdout) # optional: one warn line per retry
+end
+```
+
+| Setting | Default | Meaning |
+|---------|---------|---------|
+| `max_retries` | `3` | **Total attempts**, not extra ones. `3` = one call plus at most two retries. `1` (or `0`) disables retrying. |
+| `retry_delay` | `1.0` | Seconds before the first retry. Each further retry doubles it. |
+
+### What gets retried
+
+| Failure | Retried | Why |
+|---------|---------|-----|
+| `429 Too Many Requests` | ✅ | Rate limit / saturated quota pool — the next attempt may land |
+| `500`, `502`, `503`, `504` | ✅ | Server-side overload or a bad gateway hop |
+| `408 Request Timeout` | ✅ | Same as a timeout, expressed as a status |
+| Connection & read timeouts | ✅ | `Faraday::ConnectionFailed`, `Faraday::TimeoutError`, `Net::ReadTimeout`, `Net::OpenTimeout`, `Errno::ECONNRESET` |
+| `400`, `401`, `403`, `404`, `422` | ❌ | A malformed request or a bad credential is identical on attempt two |
+| TLS/SSL errors | ❌ | A certificate problem does not resolve itself |
+| Anything else | ❌ | Surfaces on the first attempt, unchanged |
+
+---
+
+## Overview
+
+`Configuration` has declared `max_retries` and `retry_delay` for a long time, but
+until 1.8.4 nothing read them: `OpenrouterClient` and `ZaiClient` each carried
+their own hardcoded loop, and `GeminiClient` had no retry at all — a single Vertex
+429 became an immediate, user-visible error.
+
+The policy now lives in one place, `LlmConductor::Clients::Concerns::Retryable`,
+mixed into `BaseClient`. Every provider request — `generate` and
+`generate_simple` alike — goes through it, so the two configuration knobs mean the
+same thing everywhere.
+
+## Backoff
+
+```
+delay = min(retry_delay * 2 ** (attempt - 1), 30.0)
+delay += delay * 0.25 * rand   # jitter
+```
+
+With the defaults (`retry_delay = 1.0`, `max_retries = 3`):
+
+| Attempt | Fails with | Waits |
+|---------|------------|-------|
+| 1 | 429 | ~1.0–1.25s |
+| 2 | 429 | ~2.0–2.5s |
+| 3 | 429 | — raises / returns an error `Response` |
+
+The jitter is **additive**, so a retry never fires sooner than you configured; its
+purpose is to stop a fleet of concurrent workers from retrying in lockstep against
+the same shared quota pool. The computed backoff is capped at 30 seconds so a
+generous `retry_delay` cannot park a worker for minutes.
+
+## Retry-After
+
+When a provider sends a `Retry-After` header, it replaces the computed backoff.
+Both formats are understood — a delay in seconds (`Retry-After: 7`) and an
+HTTP-date (`Retry-After: Wed, 26 Aug 2026 10:20:00 GMT`). The value is capped at
+60 seconds: past that, failing fast and letting the caller decide beats blocking a
+worker. An unparseable value is ignored and the computed backoff is used instead.
+
+## Logging
+
+With a logger configured, each retry emits exactly one `warn` line:
+
+```
+[LlmConductor::Clients::GeminiClient] transient HTTP 429 on attempt 1/3; retrying in 1.07s
+```
+
+The line deliberately carries only the class/status, the attempt and the delay.
+The exception's message and response body carry the request URL, and for Gemini's
+generative-language endpoint that URL embeds the API key as a query parameter — so
+neither is ever logged.
+
+## What retries do *not* fix
+
+Retries ride out **short spikes**: a burst of 429s while a shared quota pool
+drains, a region hiccup, a dropped connection. They do not survive a **sustained**
+quota outage — if the pool stays saturated for minutes, every attempt inside the
+budget fails and the error surfaces exactly as it did before, just later. For that
+you need capacity changes on the provider side (a dedicated quota, a different
+region or model), a queue that can defer the work, or a fallback vendor.
+
+## Errors after the budget is exhausted
+
+Nothing changes about how failures reach you. `generate` and `generate_simple`
+still return a `Response`, and the last error is reported on it:
+
+```ruby
+response = LlmConductor.generate(model: 'gemini-2.5-flash', prompt: 'Hi', vendor: :gemini)
+
+unless response.success?
+  puts response.metadata[:error]       # e.g. "the server responded with status 429"
+  puts response.metadata[:error_class] # e.g. "Faraday::TooManyRequestsError"
+end
+```
+
+## Per-provider notes
+
+- **Gemini** — gemini-ai re-raises Faraday 5xx as `Gemini::Errors::RequestError`,
+  keeping the original in `#request`; 429s arrive as a bare
+  `Faraday::TooManyRequestsError`. Both shapes are recognised.
+- **OpenRouter** — previously retried 502 only, five times, on a hardcoded
+  `2**n` backoff. It now uses your configuration, and covers rate limits and
+  timeouts as well as 502.
+- **Z.ai** — its Faraday stack has no `raise_error` middleware, so HTTP errors
+  come back as a normal response with an error body rather than a raised
+  exception. The retry policy never sees them. This predates 1.8.4 (the hardcoded
+  `rescue Faraday::ServerError` there was dead code for the same reason) and is
+  left for a separate change, since adding the middleware would change what Z.ai
+  callers observe on failure.
+
+## Example
+
+See [`examples/retry_config_usage.rb`](../examples/retry_config_usage.rb) for a
+runnable walkthrough of the knobs and the resulting backoff.

data/examples/gemini_thinking_usage.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Gemini thinking configuration (generationConfig.thinkingConfig).
+#
+# Gemini 3.x models think before answering. Trimming that budget is the biggest
+# latency lever on the fast models, so llm_conductor exposes it through params:
+#
+#   params: { thinking_level: 'minimal' }                       # flat convenience key
+#   params: { thinking_config: { thinking_level: 'minimal' } }  # nested, mirrors the API
+#
+# Both reach the API as generationConfig.thinkingConfig.thinkingLevel.
+#
+#   GEMINI_API_KEY=... ruby examples/gemini_thinking_usage.rb
+#   GEMINI_API_KEY=... MODEL=gemini-3.5-flash-lite ruby examples/gemini_thinking_usage.rb
+
+require_relative '../lib/llm_conductor'
+require 'logger'
+
+MODEL = ENV['MODEL'] || 'gemini-2.5-flash'
+PROMPT = 'Name the capital of France. Answer with one word.'
+
+LlmConductor.configure do |config|
+  config.gemini(api_key: ENV.fetch('GEMINI_API_KEY'))
+  # With a logger configured, any param the client cannot map is reported
+  # instead of being dropped silently.
+  config.logger = Logger.new($stdout)
+end
+
+CASES = {
+  'no thinking config' => {},
+  'flat thinking_level' => { thinking_level: 'minimal' },
+  'nested thinking_config' => { thinking_config: { thinking_level: 'minimal' } },
+  'thinking_budget: 0' => { thinking_config: { thinking_budget: 0 } },
+  'unmapped param (expect a warning)' => { reasoning_effort: 'high' }
+}.freeze
+
+CASES.each do |label, params|
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = LlmConductor.generate(model: MODEL, prompt: PROMPT, vendor: :gemini, params:)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+  if response.success?
+    puts "[#{label}] #{elapsed.round(2)}s — #{response.output.to_s.strip}"
+  else
+    puts "[#{label}] FAILED — #{response.metadata[:error]}"
+  end
+end

data/examples/retry_config_usage.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Retry configuration (config.max_retries / config.retry_delay).
+#
+# Transient provider failures — a 429 from a saturated quota pool, a 503 from an
+# overloaded region, a dropped connection — are retried with exponential backoff
+# seeded from retry_delay, up to max_retries *total* attempts (so the default of 3
+# means one call plus at most two retries).
+#
+# Statuses that will not change on a second identical request (400, 401, 403, 404,
+# 422) are never retried; they surface on the first attempt.
+#
+#   GEMINI_API_KEY=... ruby examples/retry_config_usage.rb
+#
+# The last section needs no API key: it prints the backoff curve so you can see
+# what a given retry_delay actually costs before you set it in production.
+
+require_relative '../lib/llm_conductor'
+require 'logger'
+
+MODEL = ENV['MODEL'] || 'gemini-2.5-flash'
+PROMPT = 'Name the capital of France. Answer with one word.'
+
+LlmConductor.configure do |config|
+  config.gemini(api_key: ENV['GEMINI_API_KEY']) if ENV['GEMINI_API_KEY']
+
+  # Total attempts, including the first. Set to 1 to disable retrying.
+  config.max_retries = 3
+
+  # Seconds before the first retry; each further retry doubles it.
+  config.retry_delay = 1.0
+
+  # With a logger configured, every retry emits one warn line naming the attempt,
+  # the status and the delay. The API key is never part of it.
+  config.logger = Logger.new($stdout)
+end
+
+if ENV['GEMINI_API_KEY']
+  started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  response = LlmConductor.generate(model: MODEL, prompt: PROMPT, vendor: :gemini)
+  elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+
+  if response.success?
+    puts "OK in #{elapsed.round(2)}s — #{response.output.to_s.strip}"
+  else
+    # Reached only after the whole attempt budget is spent. Retries ride out short
+    # spikes; they do not survive a sustained quota outage.
+    puts "FAILED after #{elapsed.round(2)}s — #{response.metadata[:error]}"
+    puts "  error class: #{response.metadata[:error_class]}"
+  end
+else
+  puts 'GEMINI_API_KEY not set — skipping the live call.'
+end
+
+puts
+puts 'Backoff curve (before jitter, which only ever adds):'
+
+retryable = LlmConductor::Clients::Concerns::Retryable
+[0.25, 1.0, 5.0].each do |retry_delay|
+  delays = (1...LlmConductor.configuration.max_retries).map do |attempt|
+    [retry_delay * (2**(attempt - 1)), retryable::MAX_BACKOFF_SECONDS].min
+  end
+  total = delays.sum
+  puts format(
+    '  retry_delay=%<seed>-5s waits %<waits>-22s worst case %<total>.2fs of waiting',
+    seed: retry_delay, waits: delays.map { |d| "#{d}s" }.join(', '), total:
+  )
+end
+
+puts
+puts 'Retried:     429, 500, 502, 503, 504, 408, connection/read timeouts'
+puts 'Not retried: 400, 401, 403, 404, 422, TLS errors — see docs/retries.md'

data/lib/llm_conductor/clients/base_client.rb

@@ -3,13 +3,20 @@
 require 'tiktoken_ruby'
 require 'ollama-ai'
 require 'openai'
+require_relative 'concerns/retryable'
 
 module LlmConductor
   module Clients
     # Base client class providing common functionality for all LLM providers
     # including prompt building, token counting, and response formatting.
+    #
+    # Every provider request goes through Concerns::Retryable, so transient
+    # rate-limit/overload failures are retried according to
+    # configuration.max_retries and configuration.retry_delay. See
+    # docs/retries.md for the exact policy.
     class BaseClient
       include Prompts
+      include Concerns::Retryable
 
       attr_reader :model, :type, :params
 
@@ -22,7 +29,7 @@ module LlmConductor
       def generate(data:)
         prompt = build_prompt(data)
         input_tokens = calculate_tokens(prompt)
-        output_text = generate_content(prompt)
+        output_text = with_retries { generate_content(prompt) }
         output_tokens = calculate_tokens(output_text || '')
 
         # Logging AI request metadata if logger is set
@@ -39,7 +46,7 @@ module LlmConductor
       # Simple generation method that accepts a direct prompt and returns a Response object
       def generate_simple(prompt:)
         input_tokens = calculate_tokens(prompt)
-        output_text = generate_content(prompt)
+        output_text = with_retries { generate_content(prompt) }
         output_tokens = calculate_tokens(output_text || '')
 
         # Logging AI request metadata if logger is set

data/lib/llm_conductor/clients/concerns/gemini_generation_config.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Clients
+    module Concerns
+      # Builds Gemini's generationConfig payload from the generic snake_case +params+
+      # hash accepted by every client.
+      #
+      # The Gemini REST API expects camelCase keys inside generationConfig, and nests
+      # the Gemini 3.x thinking controls one level deeper, under
+      # generationConfig.thinkingConfig. Callers keep passing snake_case Ruby keys —
+      # the translation lives here.
+      #
+      # Keys without a mapping are skipped and reported through the configured logger
+      # instead of disappearing silently. Skipping rather than raising keeps existing
+      # callers that pass provider-agnostic params working unchanged.
+      module GeminiGenerationConfig
+        # Gemini REST API uses camelCase keys in generationConfig.
+        PARAM_KEY_MAP = {
+          temperature: :temperature,
+          top_p: :topP,
+          top_k: :topK,
+          max_tokens: :maxOutputTokens,
+          max_output_tokens: :maxOutputTokens,
+          candidate_count: :candidateCount,
+          stop_sequences: :stopSequences
+        }.freeze
+
+        # Keys nested under generationConfig.thinkingConfig (Gemini 3.x thinking
+        # controls). Accepted flat in params or inside a thinking_config hash.
+        THINKING_KEY_MAP = {
+          thinking_level: :thinkingLevel,
+          thinking_budget: :thinkingBudget,
+          include_thoughts: :includeThoughts
+        }.freeze
+
+        # Param keys carrying a nested thinkingConfig hash.
+        THINKING_CONFIG_KEYS = %i[thinking_config thinkingConfig].freeze
+
+        private
+
+        # Build Gemini generationConfig from the params hash.
+        #
+        # Thinking controls may be passed flat (thinking_level: 'minimal') or nested
+        # (thinking_config: { thinking_level: 'minimal' }); either way they end up in
+        # generationConfig.thinkingConfig, and both forms together are merged.
+        #
+        # @return [Hash, nil] generationConfig hash, or nil when nothing maps
+        def build_generation_config
+          return unless params.is_a?(Hash) && params.any?
+
+          gen_cfg = {}
+          thinking_cfg = {}
+          params.each { |key, value| assign_generation_param(key, value, gen_cfg, thinking_cfg) }
+          gen_cfg[:thinkingConfig] = thinking_cfg if thinking_cfg.any?
+          gen_cfg.any? ? gen_cfg : nil
+        end
+
+        # Route a single param into generationConfig or its nested thinkingConfig.
+        def assign_generation_param(key, value, gen_cfg, thinking_cfg)
+          if THINKING_CONFIG_KEYS.include?(key.to_sym)
+            thinking_cfg.merge!(normalize_thinking_config(value))
+          elsif (thinking_key = thinking_config_key_for(key))
+            thinking_cfg[thinking_key] = value
+          elsif (mapped = PARAM_KEY_MAP[key.to_sym])
+            gen_cfg[mapped] = value
+          else
+            warn_unmapped_param(key)
+          end
+        end
+
+        # Normalize a nested thinking_config hash to the API's camelCase keys.
+        # @param value [Hash] thinking config as given by the caller
+        # @return [Hash] camelCase thinkingConfig fragment
+        def normalize_thinking_config(value)
+          unless value.is_a?(Hash)
+            warn_unmapped_param(:thinking_config, reason: "expected a Hash, got #{value.class}")
+            return {}
+          end
+
+          value.each_with_object({}) do |(key, val), cfg|
+            mapped = thinking_config_key_for(key)
+            if mapped
+              cfg[mapped] = val
+            else
+              warn_unmapped_param(key, scope: 'thinkingConfig')
+            end
+          end
+        end
+
+        # Resolve a thinkingConfig key, accepting snake_case or the camelCase API name.
+        # @return [Symbol, nil] camelCase API key, or nil when unknown
+        def thinking_config_key_for(key)
+          sym_key = key.to_sym
+          THINKING_KEY_MAP[sym_key] || (sym_key if THINKING_KEY_MAP.value?(sym_key))
+        end
+
+        # Report a param the client cannot map. Non-fatal by design: unmapped keys are
+        # skipped, but never without a trace — configure LlmConductor.configuration.logger
+        # to surface them.
+        def warn_unmapped_param(key, scope: 'generationConfig', reason: 'no Gemini API mapping')
+          configuration.logger&.warn(
+            "[LlmConductor::Clients::GeminiClient] Skipping #{scope} param #{key.inspect}: #{reason}. " \
+            'See docs/custom-parameters.md for the supported keys.'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/concerns/retryable.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'net/http'
+require 'time'
+
+module LlmConductor
+  module Clients
+    module Concerns
+      # Shared retry policy for provider API calls.
+      #
+      # +LlmConductor::Configuration+ has always declared +max_retries+ and
+      # +retry_delay+; this concern is what makes them mean something. It is mixed
+      # into BaseClient, so every provider goes through the same policy and the two
+      # configuration knobs behave identically everywhere.
+      #
+      # Only failures that a second identical request can plausibly fix are retried:
+      # the rate-limit and overload statuses in RETRYABLE_STATUSES, plus the
+      # connection/read timeout classes in TRANSPORT_ERRORS. Everything else —
+      # notably 400/401/403/404 and any other 4xx — surfaces on the first attempt,
+      # because retrying a malformed request or a bad credential only wastes time.
+      #
+      # Backoff is exponential and seeded from +retry_delay+:
+      #
+      #   delay = min(retry_delay * 2**(attempt - 1), MAX_BACKOFF_SECONDS)
+      #   delay += delay * JITTER_RATIO * rand
+      #
+      # The jitter is additive, so a retry never fires sooner than configured, but
+      # concurrent workers hitting the same shared quota pool stop retrying in
+      # lockstep. A +Retry-After+ header, when the API sends one, replaces the
+      # computed backoff (still jittered, still capped).
+      module Retryable
+        # Statuses worth a second attempt: rate limiting and transient overload.
+        RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504].freeze
+
+        # Transport-level failures, which carry no HTTP status at all.
+        TRANSPORT_ERRORS = [
+          Faraday::ConnectionFailed,
+          Faraday::TimeoutError,
+          Faraday::NilStatusError,
+          Net::OpenTimeout,
+          Net::ReadTimeout,
+          Errno::ECONNRESET,
+          Errno::ECONNREFUSED
+        ].freeze
+
+        # Ceiling for the computed exponential backoff, so a generous retry_delay
+        # cannot park a worker for minutes.
+        MAX_BACKOFF_SECONDS = 30.0
+
+        # Ceiling for a server-supplied Retry-After. A library should not block its
+        # caller for longer than this; past it, failing fast is the better answer.
+        MAX_RETRY_AFTER_SECONDS = 60.0
+
+        # Additive jitter, as a fraction of the delay: 0.25 spreads retries over
+        # [delay, delay * 1.25).
+        JITTER_RATIO = 0.25
+
+        # All backoff waiting funnels through here. Keeping it a single module
+        # method gives tests one seam to observe instead of stubbing Kernel#sleep on
+        # every client, and leaves one place to change should a caller ever need a
+        # non-blocking scheduler.
+        def self.sleep_for(seconds)
+          sleep(seconds)
+        end
+
+        private
+
+        # Run the block, retrying transient failures per the configured policy.
+        #
+        # @yield the provider request to attempt
+        # @return [Object] the block's value
+        # @raise [StandardError] the last error, once attempts are exhausted or the
+        #   failure is not retryable
+        def with_retries
+          attempt = 0
+          max_attempts = retry_attempts
+
+          begin
+            attempt += 1
+            yield
+          rescue StandardError => e
+            raise if attempt >= max_attempts || !retryable_error?(e)
+
+            delay = retry_delay_for(e, attempt)
+            log_retry(e, attempt, max_attempts, delay)
+            Retryable.sleep_for(delay)
+            retry
+          end
+        end
+
+        # Total attempts allowed, including the first one.
+        #
+        # +max_retries+ is read as a total attempt budget (matching the hardcoded
+        # loops this concern replaced), so the default of 3 means one initial call
+        # plus at most two retries. Anything below 1 degrades to a single attempt.
+        def retry_attempts
+          [configuration.max_retries.to_i, 1].max
+        end
+
+        # @return [Boolean] whether an identical retry could plausibly succeed
+        def retryable_error?(error)
+          err = unwrap_error(error)
+          status = http_status(err)
+          return RETRYABLE_STATUSES.include?(status) unless status.nil?
+
+          TRANSPORT_ERRORS.any? { |klass| err.is_a?(klass) }
+        end
+
+        # Seconds to wait before the next attempt.
+        def retry_delay_for(error, attempt)
+          apply_jitter(retry_after_seconds(error) || backoff_seconds(attempt))
+        end
+
+        # Exponential backoff seeded from configuration.retry_delay.
+        def backoff_seconds(attempt)
+          base = configuration.retry_delay.to_f * (2**(attempt - 1))
+          [base, MAX_BACKOFF_SECONDS].min
+        end
+
+        # Spread concurrent retries without ever firing earlier than asked.
+        def apply_jitter(seconds)
+          seconds + (seconds * JITTER_RATIO * rand)
+        end
+
+        # Honour a Retry-After header when the API sends a usable one.
+        # @return [Float, nil] seconds to wait, or nil when absent/unparseable
+        def retry_after_seconds(error)
+          raw = header_value(response_headers(error), 'retry-after').to_s.strip
+          return if raw.empty?
+
+          seconds = parse_retry_after(raw)
+          seconds&.clamp(0.0, MAX_RETRY_AFTER_SECONDS)
+        end
+
+        # Retry-After is either a delay in seconds or an HTTP-date.
+        def parse_retry_after(raw)
+          return raw.to_f if raw.match?(/\A\d+(\.\d+)?\z/)
+
+          Time.httpdate(raw) - Time.now
+        rescue ArgumentError
+          nil
+        end
+
+        # Log every retry through the gem's configured logger.
+        #
+        # Deliberately reports only the class/status, attempt and delay: the
+        # exception's message and response carry the request URL, and for Gemini's
+        # generative-language endpoint that URL embeds the API key as a query param.
+        def log_retry(error, attempt, max_attempts, delay)
+          err = unwrap_error(error)
+          status = http_status(err)
+          reason = status ? "HTTP #{status}" : err.class.name
+
+          configuration.logger&.warn(
+            "[LlmConductor::Clients::#{short_class_name}] transient #{reason} " \
+            "on attempt #{attempt}/#{max_attempts}; retrying in #{format('%.2f', delay)}s"
+          )
+        end
+
+        # Some clients wrap the transport error (gemini-ai re-raises Faraday errors
+        # as Gemini::Errors::RequestError, keeping the original in #request).
+        def unwrap_error(error)
+          inner = error.respond_to?(:request) ? error.request : nil
+          inner.is_a?(StandardError) ? inner : error
+        end
+
+        # @return [Integer, nil] HTTP status, or nil for transport-level failures
+        def http_status(error)
+          error.respond_to?(:response_status) ? error.response_status : nil
+        end
+
+        # @return [Hash, nil] response headers, when the error carries a response
+        def response_headers(error)
+          err = unwrap_error(error)
+          err.respond_to?(:response_headers) ? err.response_headers : nil
+        end
+
+        # Case-insensitive header lookup that works for plain Hashes as well as
+        # Faraday's own headers object.
+        def header_value(headers, name)
+          return unless headers.respond_to?(:to_h)
+
+          _key, value = headers.to_h.find { |key, _| key.to_s.downcase == name }
+          value
+        end
+
+        def short_class_name
+          self.class.name.to_s.split('::').last
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/gemini_client.rb

@@ -5,6 +5,7 @@ require 'base64'
 require 'net/http'
 require 'uri'
 require_relative 'concerns/vision_support'
+require_relative 'concerns/gemini_generation_config'
 require_relative '../patches/gemini_vertex_api_key'
 
 module LlmConductor
@@ -13,20 +14,10 @@ module LlmConductor
     # Supports both text-only and multimodal (vision) requests
     class GeminiClient < BaseClient
       include Concerns::VisionSupport
+      include Concerns::GeminiGenerationConfig
 
       private
 
-      # Gemini REST API uses camelCase keys in generationConfig.
-      PARAM_KEY_MAP = {
-        temperature: :temperature,
-        top_p: :topP,
-        top_k: :topK,
-        max_tokens: :maxOutputTokens,
-        max_output_tokens: :maxOutputTokens,
-        candidate_count: :candidateCount,
-        stop_sequences: :stopSequences
-      }.freeze
-
       def generate_content(prompt)
         content = format_content(prompt)
         parts = build_parts_for_gemini(content)
@@ -45,20 +36,6 @@ module LlmConductor
         response.dig('candidates', 0, 'content', 'parts', 0, 'text')
       end
 
-      # Build Gemini generationConfig from params hash.
-      # Maps snake_case Ruby keys to camelCase Gemini API keys.
-      # @return [Hash, nil] generationConfig hash or nil if no mapped params
-      def build_generation_config
-        return unless params.is_a?(Hash) && params.any?
-
-        gen_cfg = {}
-        params.each do |key, value|
-          mapped = PARAM_KEY_MAP[key.to_sym]
-          gen_cfg[mapped] = value if mapped
-        end
-        gen_cfg.any? ? gen_cfg : nil
-      end
-
       # Build parts array for Gemini API from formatted content
       # Converts VisionSupport format to Gemini's specific format
       # @param content [String, Array] Formatted content from VisionSupport

data/lib/llm_conductor/clients/openrouter_client.rb

@@ -6,6 +6,10 @@ module LlmConductor
   module Clients
     # OpenRouter client implementation for accessing various LLM providers through OpenRouter API
     # Supports both text-only and multimodal (vision) requests
+    #
+    # Transient failures (502s from overloaded free-tier models, rate limits,
+    # timeouts) are retried by BaseClient's Concerns::Retryable using
+    # configuration.max_retries / configuration.retry_delay.
     class OpenrouterClient < BaseClient
       include Concerns::VisionSupport
 
@@ -14,34 +18,13 @@ module LlmConductor
       def generate_content(prompt)
         content = format_content(prompt)
 
-        # Retry logic for transient 502 errors (common with free-tier models)
-        # Free-tier vision models can be slow/overloaded, so we use more retries
-        max_retries = 5
-        retry_count = 0
-
-        begin
-          client.chat(
-            parameters: {
-              model:,
-              messages: [{ role: 'user', content: }],
-              provider: { sort: 'throughput' }
-            }
-          ).dig('choices', 0, 'message', 'content')
-        rescue Faraday::ServerError => e
-          retry_count += 1
-
-          # Log retry attempts if logger is configured
-          configuration.logger&.warn(
-            "OpenRouter API error (attempt #{retry_count}/#{max_retries}): #{e.message}"
-          )
-
-          raise unless e.response[:status] == 502 && retry_count < max_retries
-
-          wait_time = 2**retry_count # Exponential backoff: 2, 4, 8, 16, 32 seconds
-          configuration.logger&.info("Retrying in #{wait_time}s...")
-          sleep(wait_time)
-          retry
-        end
+        client.chat(
+          parameters: {
+            model:,
+            messages: [{ role: 'user', content: }],
+            provider: { sort: 'throughput' }
+          }
+        ).dig('choices', 0, 'message', 'content')
       end
 
       def client

data/lib/llm_conductor/clients/zai_client.rb

@@ -9,6 +9,9 @@ module LlmConductor
     #
     # Note: Z.ai uses OpenAI-compatible API format but with /v4/ path instead of /v1/
     # We use Faraday directly instead of the ruby-openai gem to properly handle the API path
+    #
+    # Transient failures are retried by BaseClient's Concerns::Retryable using
+    # configuration.max_retries / configuration.retry_delay.
     class ZaiClient < BaseClient
       include Concerns::VisionSupport
 
@@ -17,41 +20,28 @@ module LlmConductor
       def generate_content(prompt)
         content = format_content(prompt)
 
-        # Retry logic for transient errors (similar to OpenRouter)
-        max_retries = 3
-        retry_count = 0
-
-        begin
-          # Make direct HTTP request to Z.ai API since they use /v4/ instead of /v1/
-          response = http_client.post('chat/completions') do |req|
-            req.body = {
-              model:,
-              messages: [{ role: 'user', content: }]
-            }.to_json
-          end
-
-          # Response body is already parsed as Hash by Faraday's JSON middleware
-          response_data = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
-          response_data.dig('choices', 0, 'message', 'content')
-        rescue Faraday::ServerError => e
-          retry_count += 1
-
-          # Log retry attempts if logger is configured
-          configuration.logger&.warn(
-            "Z.ai API error (attempt #{retry_count}/#{max_retries}): #{e.message}"
-          )
-
-          raise unless retry_count < max_retries
-
-          wait_time = 2**retry_count # Exponential backoff: 2, 4, 8 seconds
-          configuration.logger&.info("Retrying in #{wait_time}s...")
-          sleep(wait_time)
-          retry
+        # Make direct HTTP request to Z.ai API since they use /v4/ instead of /v1/
+        response = http_client.post('chat/completions') do |req|
+          req.body = {
+            model:,
+            messages: [{ role: 'user', content: }]
+          }.to_json
         end
+
+        # Response body is already parsed as Hash by Faraday's JSON middleware
+        response_data = response.body.is_a?(String) ? JSON.parse(response.body) : response.body
+        response_data.dig('choices', 0, 'message', 'content')
       end
 
       # HTTP client for making requests to Z.ai API
       # Z.ai uses /v4/ in their path, not /v1/ like OpenAI, so we use Faraday directly
+      #
+      # NOTE: this stack has no `response :raise_error` middleware, so an HTTP error
+      # from Z.ai comes back as a normal response with an error body rather than a
+      # raised Faraday error. The shared retry policy therefore never sees it — the
+      # same blind spot the hardcoded `rescue Faraday::ServerError` here had. Adding
+      # the middleware would change what Z.ai callers observe on failure (an error
+      # Response instead of a nil output), so it is left for a separate change.
       def http_client
         @http_client ||= begin
           config = LlmConductor.configuration.provider_config(:zai)

data/lib/llm_conductor/configuration.rb

@@ -12,6 +12,10 @@ module LlmConductor
       @default_model = 'gpt-5-mini'
       @default_vendor = :openai
       @timeout = 30
+      # Retry policy for transient provider failures, applied to every client by
+      # LlmConductor::Clients::Concerns::Retryable. max_retries is a TOTAL attempt
+      # budget including the first call (3 = one call plus at most two retries);
+      # retry_delay seeds the exponential backoff. See docs/retries.md.
       @max_retries = 3
       @retry_delay = 1.0
       @logger = nil

data/lib/llm_conductor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmConductor
-  VERSION = '1.8.2'
+  VERSION = '1.8.4'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_conductor
 version: !ruby/object:Gem::Version
-  version: 1.8.2
+  version: 1.8.4
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2026-06-11 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,9 +169,11 @@ files:
 - config/initializers/llm_conductor.rb
 - docs/README.md
 - docs/custom-parameters.md
+- docs/retries.md
 - docs/vision-support.md
 - examples/claude_vision_usage.rb
 - examples/data_builder_usage.rb
+- examples/gemini_thinking_usage.rb
 - examples/gemini_usage.rb
 - examples/gemini_vision_usage.rb
 - examples/gpt_vision_usage.rb
@@ -181,12 +183,15 @@ files:
 - examples/openrouter_vision_usage.rb
 - examples/prompt_registration.rb
 - examples/rag_usage.rb
+- examples/retry_config_usage.rb
 - examples/simple_usage.rb
 - examples/zai_usage.rb
 - lib/llm_conductor.rb
 - lib/llm_conductor/client_factory.rb
 - lib/llm_conductor/clients/anthropic_client.rb
 - lib/llm_conductor/clients/base_client.rb
+- lib/llm_conductor/clients/concerns/gemini_generation_config.rb
+- lib/llm_conductor/clients/concerns/retryable.rb
 - lib/llm_conductor/clients/concerns/vision_support.rb
 - lib/llm_conductor/clients/gemini_client.rb
 - lib/llm_conductor/clients/gpt_client.rb