[RFC] Add retryable_exceptions filter to retry policies

[vasudev13]

Motivation

Both built-in policies retry on any exception. This means a ValueError from a malformed response or a KeyError in parsing logic burns through all attempts even though retrying will never help — only transient failures like network timeouts or rate limits warrant a retry.

Proposed Change

Add an optional retryable_exceptions parameter to both concrete policy classes. Default None preserves existing behavior, no breaking changes.

Since workflows-py is LLM-agnostic, the parameter accepts any exception type(s) the caller needs. Example -

OpenAI

from openai import RateLimitError, APITimeoutError, APIConnectionError

@step(retry_policy=ExponentialBackoffRetryPolicy(
    maximum_attempts=5,
    retryable_exceptions=(RateLimitError, APITimeoutError, APIConnectionError),
))
async def call_openai(self, ev: QueryEvent) -> ResultEvent: ...

Anthropic

from anthropic import RateLimitError, APIConnectionError

@step(retry_policy=ConstantDelayRetryPolicy(
    delay=10,
    maximum_attempts=3,
    retryable_exceptions=(RateLimitError, APIConnectionError),
))
async def call_anthropic(self, ev: QueryEvent) -> ResultEvent: ...

Gemini

from google.api_core.exceptions import ResourceExhausted, ServiceUnavailable

@step(retry_policy=ExponentialBackoffRetryPolicy(
    maximum_attempts=5,
    retryable_exceptions=(ResourceExhausted, ServiceUnavailable),
))
async def call_gemini(self, ev: QueryEvent) -> ResultEvent: ...

Implementation is ~3 lines per policy — early-return None if not isinstance(error, self.retryable_exceptions).

Questions

1. Is this in scope for the built-in policies, or is the intent that users subclass RetryPolicy for this level of control?
2. Happy to open a PR if the direction looks good — I contributed the ExponentialBackoffRetryPolicy previously so I know this surface area well.

[adrianlyjak]

Thanks for bringing this up @vasudev13. Definitely agree that the retries are pretty lacking right now.

One thing that gives me pause with this design is the detection of whether an exception is retryable ends up embedded into the retry policy. If we continue extending, or a user creates their own retry policy, each retry policy needs to re-implement this logic.

Additionally, there's not a great way to react to retries being exhausted. See #12

Part of me is worried that we'll end up rebuilding tenacity badly. I wonder if there's perhaps a way to shim that in as a dependency elegantly, while still supporting the distributed retry behavior. Will do some research here and follow up with further thoughts

[adrianlyjak]

@vasudev13 can I get your thoughts on this proposal? Separately, I noticed we have some determinism bugs in the retry path that need resolving: #455

---

Problem

RetryPolicy.next() conflates exception filtering, delay computation, and stop conditions into one method. Adding shared logic like retryable_exceptions means duplicating it across every policy or subclassing for something that should compose.

Solution

Decompose into retry, wait, and stop pieces following tenacity's API.

@step(
    retry_policy=RetryPolicy(
        retry=retry_if_exception_type(TimeoutError, RateLimitError),
        wait=wait_exponential(multiplier=1, max=60),
        stop=stop_after_attempt(5) | stop_after_delay(300),
    )
)
async def call_api(self, ev: QueryEvent) -> ResponseEvent:
    ...

API

retry conditions

retry_if_exception_type(*types: type[Exception]) -> RetryCondition
retry_if_not_exception_type(*types: type[Exception]) -> RetryCondition
retry_if_exception_message(match: str) -> RetryCondition  # regex

| = retry if any match. & = retry if all match.

wait strategies

wait_fixed(delay: float) -> WaitStrategy
wait_exponential(multiplier: float = 1, max: float = 60, exp_base: float = 2) -> WaitStrategy
wait_random(min: float = 0, max: float = 1) -> WaitStrategy
wait_exponential_jitter(initial: float = 1, max: float = 60, jitter: float = 1) -> WaitStrategy
wait_chain(*strategies: WaitStrategy) -> WaitStrategy

+ = sum delays (e.g. wait_fixed(2) + wait_random(0, 1) for base + jitter).

stop conditions

stop_after_attempt(max_attempts: int) -> StopCondition
stop_after_delay(max_seconds: float) -> StopCondition

| = stop if any fires. & = stop if all fire.

RetryPolicy

class RetryPolicy:
    def __init__(
        self,
        retry: RetryCondition | None = None,
        wait: WaitStrategy = wait_fixed(5),
        stop: StopCondition = stop_after_attempt(3),
    ) -> None: ...

    def next(self, elapsed_time: float, attempts: int, error: Exception) -> float | None:
        if self._retry is not None and not self._retry(error):
            return None
        if self._stop(elapsed_time, attempts):
            return None
        return self._wait(elapsed_time, attempts)

Backward Compatibility

• The structural RetryPolicy protocol (next() -> float | None) is unchanged. Any existing implementation still works.
• ConstantDelayRetryPolicy and ExponentialBackoffRetryPolicy stay as convenience shortcuts.
• No control loop changes. RetryPolicy.next() is the only integration point, and the new class implements it.

[vasudev13]

Thanks for the counter-proposal, @adrianlyjak — this is a better design than what I originally suggested. Decomposing into retry, wait, and stop primitives solves the duplication concern cleanly, and it gives users composability without us having to anticipate every filtering pattern upfront.

On the tenacity question: I'd lean against pulling it in as a dependency. The API surface here is small enough that reimplementing the core primitives is straightforward, and it keeps workflows-py dependency-light. The main value tenacity brings is battle-tested edge cases — but since next() remains the sole integration point, we could always add a thin from_tenacity() adapter later for users who already depend on it, without baking it into the core.

On backward compat: The proposal looks clean. One minor thought — it might be worth having ConstantDelayRetryPolicy and ExponentialBackoffRetryPolicy delegate to RetryPolicy internally rather than remaining as separate implementations.

Something like:

class ConstantDelayRetryPolicy(RetryPolicy):
    def __init__(self, delay: float = 5, maximum_attempts: int = 3) -> None:
        super().__init__(
            wait=wait_fixed(delay),
            stop=stop_after_attempt(maximum_attempts),
        )

Keeps the old constructor signatures working, preserves isinstance checks and clean tracebacks, but eliminates duplicated logic under the hood.

On #455: I have some thoughts on the determinism bug (seeding RNG from run_id + step_name + attempt feels like the right path) — I'll drop those in that issue directly so we keep the threads focused.

Happy to pick up the implementation once you're settled on the direction.

[adrianlyjak]

On backward compat: The proposal looks clean. One minor thought — it might be worth having ConstantDelayRetryPolicy and ExponentialBackoffRetryPolicy delegate to RetryPolicy internally rather than remaining as separate implementations.

Agree.

On the tenacity question: I'd lean against pulling it in as a dependency.

I think I agree

I'm not 100% sure I like my solution yet. On the pro side, it seems like it will be intuitive: tenacity is powerful and highly adopted, so should be easy to use and for coding agents to understand how to write it. On the other hand, it might end up being over-engineered, introduce more surface area than we need, and potentially cause confusing friction with the API being "almost but not the same" as tenacity.

Happy to pick up the implementation once you're settled on the direction.

If you feel up to it. I'd like to send claude to get a basic draft up to get a better sense of the complexity here of emulating tenacity API. If you do pick it up, keep it light/draft quality so we can discuss without sinking too much effort.

[vasudev13]

Sounds good — I'll put up a light draft so we can see how the tenacity-style API feels in practice before committing to it.

My main hesitation is whether emulating tenacity's API ends up being "almost but not quite the same," which could be more confusing than a simpler bespoke design. The draft should make that easier to judge.

I'll keep scope tight — just the primitives from your earlier comment, legacy delegation, and tests. No combinators or callback hooks.

[vasudev13]

++ @adrianlyjak on #482