NAME

LLM::Data::Pipeline::RetryPolicy - Exponential-backoff retry budget for pipeline steps

SYNOPSIS

use LLM::Data::Pipeline::RetryPolicy;

my $policy = LLM::Data::Pipeline::RetryPolicy.new(
	max-attempts => 4,      # try up to 4 times
	base-delay   => 2.0,    # 2s, then 4s, then 8s …
	max-delay    => 60.0,   # … capped at 60s
	jitter       => 0.5,    # plus up to 0.5s of noise
);

$policy.delay-for(1);       # ~2.0  (2 * 2**0 + jitter)
$policy.delay-for(2);       # ~4.0
$policy.delay-for(3);       # ~8.0
$policy.exhausted(3);       # False — one attempt left
$policy.exhausted(4);       # True

# Wire it into a Runner as the default policy for every plain step:
my $runner = LLM::Data::Pipeline::Runner.new(:step-retry($policy));

DESCRIPTION

A RetryPolicy is a small value object describing how many times a step may be attempted and how long to wait between attempts. It is intentionally simple and side-effect-free: delay-for and exhausted are the only behavior.

Deliberately slower than the inference layer

This is the second retry layer. Beneath a pipeline step, an LLM::Data::Inference::Task already runs its own per-call backoff and backend fallback chain, retrying fast against alternate models. By the time a failure escapes that chain and reaches the step, the fast-retry budget is spent — so the Runner's policy defaults to a much longer backoff (base-delay of 5s rather than sub-second) to avoid hammering an upstream that has already signalled sustained trouble. Treat it as the outer, patient ring around the inner, eager one.

The backoff formula

delay-for(attempt) = min(max-delay, base-delay * 2 ** (attempt - 1)) + rand * jitter

attempt is 1-based (the delay before the first retry is delay-for(1)). The cap applies only to the exponential term; jitter is added afterwards, so a result may slightly exceed max-delay. Set jitter to 0 for a fully deterministic schedule (useful in tests with a virtual clock).

AUTHOR

Matt Doughty <[email protected]>

COPYRIGHT AND LICENSE

Copyright 2026 Matt Doughty

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.