Introduce Retry logic for LLM clients (#592)

Author: denis-domanskii

docs/docs/prompt-api.md

@@ -8,7 +8,7 @@ The prompt-executor module provides a unified interface for executing prompts ag
 
 - **prompt-executor-model**: Core interfaces and models for executing prompts against language models
 - **prompt-executor-cached**: Caching implementation for prompt execution
-- **prompt-executor-clients**: Client implementations for various LLM providers (OpenAI, Anthropic, OpenRouter)
+- **prompt-executor-clients**: Client implementations for various LLM providers and a retry logic decorator
 - **prompt-executor-llms**: Implementations of PromptExecutor for executing prompts with LLMs
 - **prompt-executor-llms-all**: Unified access to multiple LLM providers for prompt execution
 - **prompt-executor-ollama**: Client implementation for executing prompts using Ollama, a local LLM service

prompt/prompt-executor/Module.md

@@ -1,21 +1,28 @@
 # Module prompt:prompt-executor:prompt-executor-clients
 
-A collection of client implementations for executing prompts using various LLM providers.
+A collection of client implementations for executing prompts using various LLM providers and retry logic features.
 
 ### Overview
 
 This module provides client implementations for different LLM providers, allowing you to execute prompts using various
-models with support for multimodal content including images, audio, video, and documents. The module includes the
-following sub-modules:
+models with support for multimodal content including images, audio, video, and documents. The module includes 
+**production-ready retry logic** through the `RetryingLLMClient` decorator, which adds automatic error handling and
+resilience to any client implementation.
 
-1. **prompt-executor-anthropic-client**: Client implementation for Anthropic's Claude models with image and document
-   support
+The module consists of:
+
+**Core Functionality:**
+- **LLMClient interface**: Base interface for all LLM client implementations
+- **RetryingLLMClient**: Decorator that adds retry logic with configurable policies
+- **RetryConfig**: Flexible retry configuration with predefined settings for different use cases
+
+**Provider-Specific Sub-modules:**
+1. **prompt-executor-anthropic-client**: Client implementation for Anthropic's Claude models with image and document support
 2. **prompt-executor-openai-client**: Client implementation for OpenAI's GPT models with image and audio capabilities
-3. **prompt-executor-google-client**: Client implementation for Google Gemini models with comprehensive multimodal
-   support (audio, image, video, documents)
-4. **prompt-executor-openrouter-client**: Client implementation for OpenRouter's API with image, audio, and document
-   support
-5. **prompt-executor-ollama-client**: Client implementation for local Ollama models
+3. **prompt-executor-google-client**: Client implementation for Google Gemini models with comprehensive multimodal support
+4. **prompt-executor-openrouter-client**: Client implementation for OpenRouter's API with image, audio, and document support
+5. **prompt-executor-bedrock-client**: Client implementation for AWS Bedrock with support for multiple model providers (JVM only)
+6. **prompt-executor-ollama-client**: Client implementation for local Ollama models
 
 Each client handles authentication, request formatting, response parsing, and media content encoding specific to its
 respective API requirements.
@@ -94,6 +101,30 @@ val response = client.execute(
 println(response)
 ```
 
+### Retry Logic
+
+Wrap any client with `RetryingLLMClient` to add automatic retry capabilities:
+
+```kotlin
+val baseClient = OpenAILLMClient(apiKey = System.getenv("OPENAI_API_KEY"))
+val resilientClient = RetryingLLMClient(
+    delegate = baseClient,
+    config = RetryConfig.PRODUCTION  // Or CONSERVATIVE, AGGRESSIVE, DISABLED
+)
+
+val response = resilientClient.execute(prompt, model)
+
+resilientClient.executeStreaming(prompt, model).collect { chunk ->
+    print(chunk)
+}
+```
+
+**Retry Configurations:**
+- `RetryConfig.PRODUCTION` - Recommended for production (3 attempts, balanced delays)
+- `RetryConfig.CONSERVATIVE` - Fewer retries, longer delays (3 attempts, 2s initial delay)
+- `RetryConfig.AGGRESSIVE` - More retries, shorter delays (5 attempts, 500ms initial delay)
+- `RetryConfig.DISABLED` - No retries (1 attempt)
+
 ### Multimodal Content Support
 
 All clients now support multimodal content through the unified MediaContent API:

prompt/prompt-executor/prompt-executor-clients/Module.md

@@ -22,6 +22,18 @@ kotlin {
                 api(kotlin("reflect"))
             }
         }
+        commonTest {
+            dependencies {
+                implementation(kotlin("test"))
+                implementation(libs.kotlinx.coroutines.test)
+            }
+        }
+        jvmTest {
+            dependencies {
+                implementation(kotlin("test-junit5"))
+                implementation(libs.slf4j.simple)
+            }
+        }
     }
 
     explicitApi()

prompt/prompt-executor/prompt-executor-clients/build.gradle.kts

@@ -0,0 +1,169 @@
+package ai.koog.prompt.executor.clients.retry
+
+import kotlin.time.Duration
+import kotlin.time.Duration.Companion.milliseconds
+import kotlin.time.Duration.Companion.seconds
+
+/**
+ * Configuration for retry behavior in LLM client operations.
+ *
+ * @property maxAttempts Maximum number of attempts (including initial)
+ * @property initialDelay Initial delay before first retry
+ * @property maxDelay Maximum delay between retries
+ * @property backoffMultiplier Multiplier for exponential backoff
+ * @property jitterFactor Random jitter factor (0.0 to 1.0)
+ * @property retryablePatterns Patterns to identify retryable errors
+ * @property retryAfterExtractor Optional extractor for retry-after hints
+ */
+public data class RetryConfig(
+    val maxAttempts: Int = 3,
+    val initialDelay: Duration = 1.seconds,
+    val maxDelay: Duration = 30.seconds,
+    val backoffMultiplier: Double = 2.0,
+    val jitterFactor: Double = 0.1,
+    val retryablePatterns: List<RetryablePattern> = DEFAULT_PATTERNS,
+    val retryAfterExtractor: RetryAfterExtractor? = DefaultRetryAfterExtractor
+) {
+    init {
+        require(maxAttempts >= 1) { "maxAttempts must be at least 1" }
+        require(backoffMultiplier >= 1.0) { "backoffMultiplier must be at least 1.0" }
+        require(jitterFactor in 0.0..1.0) { "jitterFactor must be between 0.0 and 1.0" }
+        require(initialDelay <= maxDelay) { "initialDelay ($initialDelay) must not be greater than maxDelay ($maxDelay)" }
+    }
+
+    public companion object {
+        /**
+         * Default retry patterns that work across all providers.
+         */
+        public val DEFAULT_PATTERNS: List<RetryablePattern> = listOf(
+            // HTTP status codes
+            RetryablePattern.Status(429), // Rate limit
+            RetryablePattern.Status(500), // Internal server error
+            RetryablePattern.Status(502), // Bad gateway
+            RetryablePattern.Status(503), // Service unavailable
+            RetryablePattern.Status(504), // Gateway timeout
+            RetryablePattern.Status(529), // Anthropic overloaded
+
+            // Error keywords
+            RetryablePattern.Keyword("rate limit"),
+            RetryablePattern.Keyword("too many requests"),
+            RetryablePattern.Keyword("overloaded"),
+            RetryablePattern.Keyword("request timeout"),
+            RetryablePattern.Keyword("connection timeout"),
+            RetryablePattern.Keyword("read timeout"),
+            RetryablePattern.Keyword("write timeout"),
+            RetryablePattern.Keyword("connection reset by peer"),
+            RetryablePattern.Keyword("connection refused"),
+            RetryablePattern.Keyword("temporarily unavailable"),
+            RetryablePattern.Keyword("service unavailable")
+        )
+
+        /**
+         * Conservative configuration - fewer retries, longer delays.
+         */
+        public val CONSERVATIVE: RetryConfig = RetryConfig(
+            maxAttempts = 3,
+            initialDelay = 2.seconds,
+            maxDelay = 30.seconds
+        )
+
+        /**
+         * Aggressive configuration - more retries, shorter delays.
+         */
+        public val AGGRESSIVE: RetryConfig = RetryConfig(
+            maxAttempts = 5,
+            initialDelay = 500.milliseconds,
+            maxDelay = 20.seconds,
+            backoffMultiplier = 1.5
+        )
+
+        /**
+         * Production configuration - balanced for production use.
+         */
+        public val PRODUCTION: RetryConfig = RetryConfig(
+            maxAttempts = 3,
+            initialDelay = 1.seconds,
+            maxDelay = 20.seconds,
+            backoffMultiplier = 2.0,
+            jitterFactor = 0.2
+        )
+
+        /**
+         * No retry - effectively disables retry logic.
+         */
+        public val DISABLED: RetryConfig = RetryConfig(maxAttempts = 1)
+    }
+}
+
+/**
+ * Pattern for identifying retryable errors.
+ */
+public sealed class RetryablePattern {
+    public abstract fun matches(message: String): Boolean
+
+    /**
+     * Matches HTTP status codes in error messages.
+     */
+    public data class Status(val code: Int) : RetryablePattern() {
+        private val patterns = listOf(
+            Regex("\\b$code\\b"),
+            Regex("status:?\\s*$code"),
+            Regex("error:?\\s*$code", RegexOption.IGNORE_CASE)
+        )
+
+        override fun matches(message: String): Boolean =
+            patterns.any { it.containsMatchIn(message) }
+    }
+
+    /**
+     * Matches keywords in error messages.
+     */
+    public data class Keyword(val keyword: String) : RetryablePattern() {
+        override fun matches(message: String): Boolean =
+            keyword.lowercase() in message.lowercase()
+    }
+
+    /**
+     * Matches using a custom regex.
+     */
+    public data class Regex(val pattern: kotlin.text.Regex) : RetryablePattern() {
+        override fun matches(message: String): Boolean =
+            pattern.containsMatchIn(message)
+    }
+
+    /**
+     * Custom matching logic.
+     */
+    public class Custom(private val matcher: (String) -> Boolean) : RetryablePattern() {
+        override fun matches(message: String): Boolean = matcher(message)
+    }
+}
+
+/**
+ * Extracts retry-after hints from error messages.
+ */
+public fun interface RetryAfterExtractor {
+    public fun extract(message: String): Duration?
+}
+
+/**
+ * Default implementation that extracts common retry-after patterns.
+ */
+public object DefaultRetryAfterExtractor : RetryAfterExtractor {
+    private val patterns = listOf(
+        Regex("retry\\s+after\\s+(\\d+)\\s+second", RegexOption.IGNORE_CASE),
+        Regex("retry-after:\\s*(\\d+)", RegexOption.IGNORE_CASE),
+        Regex("wait\\s+(\\d+)\\s+second", RegexOption.IGNORE_CASE)
+    )
+
+    override fun extract(message: String): Duration? {
+        for (pattern in patterns) {
+            pattern.find(message)?.let { match ->
+                match.groupValues.getOrNull(1)?.toLongOrNull()?.let { seconds ->
+                    return seconds.seconds
+                }
+            }
+        }
+        return null
+    }
+}