koog-agents-optimization/ai.koog.agents.optimization.common.retries

Package-level declarations

Types

data class AttemptMetrics(val elapsedTime: Duration, val consumption: LLMConsumptionOrNA)

Metrics the retry wrapper collects after each attempt (success or failure). The caller supplies them via retryWith's collectAttemptMetrics callback — typically by reading consumptionTracker.collectAndClear() and a captured TimeMark.elapsedNow().

DelayStrategy

enum DelayStrategy : Enum<DelayStrategy>

Per-attempt wait-time growth strategy applied to transient-failure retries.

FailedAttempt

@Serializable

data class FailedAttempt(val attemptIndex: Int, val failure: AnalyzedFailure, val elapsedTime: Duration, val consumption: LLMConsumptionOrNA, val delayBeforeAttempt: Duration)

A single failed attempt that preceded the final attempt of a retried operation.

RetriesOutcome

sealed class RetriesOutcome<out A>

Outcome of a single retryWith invocation; describes the whole retry sequence, not a single retry attempt. The leaf-record constructors consume this to build their Completed / Failed records.

RetryPolicy

class RetryPolicy(val maxAttempts: Int, val strategy: DelayStrategy = DelayStrategy.EXPONENTIAL, val baseDelaySeconds: Double = 10.0, val maxDelaySeconds: Double = 300.0, val unknownFailurePolicy: UnknownFailurePolicy = UnknownFailurePolicy.CONSERVATIVE)

Runtime policy consumed by the retry wrapper. Translates an observed failure into "should we retry now?" + "if so, wait how long?".

UnknownFailurePolicy

enum UnknownFailurePolicy : Enum<UnknownFailurePolicy>

How the retry policy treats failures of TransiencyLevel.UNKNOWN transiency (i.e. the recognizer couldn't classify the exception).

Functions

retryWith

suspend fun <A> retryWith(policy: RetryPolicy, operationLabel: () -> String, logger: KLogger, analyzeFailure: (exception: Exception) -> AnalyzedFailure, collectAttemptMetrics: () -> AttemptMetrics, onAttemptStarting: (attemptIndex: Int) -> Unit = {}, onAbort: (abort: ExecutionAbortException, previousAttempts: List<FailedAttempt>, abortedAttemptMetrics: AttemptMetrics) -> Unit = { _, _, _ -> }, block: suspend (attemptIndex: Int) -> A): RetriesOutcome<A>

Runs block up to policy.maxAttempts + 1 times (one initial attempt plus up to maxAttempts retries), capturing per-attempt metrics via collectAttemptMetrics and applying retry / delay decisions per policy.