llm_conductor 1.8.3 → 1.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 669ae889bc5b65b4455617425a5c3628a66ed21741eca0930c78652f4b8bfbad
-  data.tar.gz: 396219406bf2db7236c223cc36200dc1be2739d6a87ab6cc50ccdc75be7482ff
+  metadata.gz: ae52774bedf1066c7a420926f11404840691b648189698d0a8ba6ba9a3c60aa1
+  data.tar.gz: 320524f99596447ffe77593901cb15a0b97143c6611225726371b8bedf25b1fc
 SHA512:
-  metadata.gz: 9e71aaa12abdf4c1bf1d750f4e28b41508d5e0b999d8373858e5ad0a16d8ea7f24c059553e59b5b38377b262bd5e6963f0a424b745d9f58e064d4135d4c05779
-  data.tar.gz: 2ab40251e03a5b8eb01bb6d7cfdbe0bac4b1137768b4c42b991da8649ec146698d17e012d076aa102643e37ddaa94951552e8e0c8f80b68ac14fd7875f7e8cdd
+  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,6 +107,28 @@ 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 |
@@ -332,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
@@ -343,6 +371,7 @@ 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

@@ -14,6 +14,15 @@ Learn how to fine-tune LLM generation with parameters like `temperature`, `top_p
 **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:
 - Sending images with text prompts

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/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/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/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.3'
+  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.3
+  version: 1.8.4
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2026-08-25 00:00:00.000000000 Z
+date: 2026-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -169,6 +169,7 @@ 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
@@ -182,6 +183,7 @@ 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
@@ -189,6 +191,7 @@ files:
 - 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