Add retry decorator with exponential backoff

[1234-ad]

Summary

This PR implements a retry decorator with exponential backoff to handle flaky API calls and network operations, addressing issue #27.

Changes

Core Implementation

• New file: src/agentunit/core/utils.py - Implements the @retry decorator with:
  • Configurable max retries (default: 3)
  • Exponential backoff with configurable base delay (default: 1.0s)
  • Maximum delay cap (default: 60.0s)
  • Customizable exponential base (default: 2.0)
  • Selective exception catching
  • Comprehensive logging for debugging

Module Updates

• Updated: src/agentunit/core/__init__.py - Exports the retry decorator for easy access

Testing

• New file: tests/test_retry_decorator.py - Comprehensive test suite covering:
  • Successful calls without retries
  • Retry behavior on exceptions
  • Exponential backoff verification
  • Max delay capping
  • Exception type filtering
  • Argument and metadata preservation
  • Logging verification
  • Real-world API scenarios

Documentation

• New file: examples/retry_decorator_usage.py - Practical examples demonstrating:
  • Basic usage with defaults
  • Custom retry configurations
  • Quick retries for fast operations
  • Specific exception handling
  • Integration with adapter classes

Features

✅ Exponential backoff to avoid overwhelming services
✅ Configurable retry parameters for different use cases
✅ Type hints for better IDE support
✅ Comprehensive logging for debugging
✅ Preserves function metadata and arguments
✅ Selective exception catching
✅ Well-tested with 15+ test cases
✅ Practical examples for common scenarios

Usage Example

from agentunit.core import retry

@retry(max_retries=3, base_delay=1.0, exceptions=(ConnectionError,))
def fetch_data():
    # API call that might fail
    return api.get_data()

Testing

All tests pass locally. The implementation includes:

• Unit tests for all decorator features
• Edge case handling (zero retries, max delay cap, etc.)
• Mock-based testing for timing verification
• Real-world scenario testing

Checklist

• Implementation follows project code style
• Comprehensive tests added
• Documentation/examples provided
• Type hints included
• Logging implemented
• Addresses issue Add retry decorator with exponential backoff #27

Closes #27

Summary by CodeRabbit

• New Features

  • Added a retry decorator with configurable exponential backoff to handle transient operation failures, supporting custom retry policies and selective exception handling.

• Documentation

  • Added example scripts demonstrating retry decorator usage across common scenarios including database operations, API calls, and adapter implementations.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[continue]

Learn more

---

All Green is an AI agent that automatically:

✅ Addresses code review comments

✅ Fixes failing CI checks

✅ Resolves merge conflicts

---

Unsubscribe from All Green comments

[coderabbitai]

Walkthrough

This pull request introduces a retry decorator with exponential backoff to handle transient failures in flaky operations. The decorator is implemented in the core utilities, exposed as a public API, accompanied by comprehensive tests, and demonstrated through practical examples across various scenarios.

Changes

Cohort / File(s)	Summary
Core Retry Decorator Implementation src/agentunit/core/utils.py	New retry decorator supporting configurable max_retries, base_delay, max_delay, exponential_base, and selective exception handling. Computes exponential backoff delays with caps, logs failures and retries, and raises the final exception after exhausting attempts. Preserves function type through TypeVar and cast.
Public API Exposure src/agentunit/core/__init__.py	Imports retry from .utils and adds it to __all__, making the decorator available as part of the public API.
Test Suite tests/test_retry_decorator.py	Comprehensive test coverage including success without retry, exception-triggered retries, max retry enforcement, exponential backoff calculation and verification, delay capping, selective exceptions, multiple exception types, argument and metadata preservation, zero-retry cases, logging validation on intermediate and final failures, and realistic API scenarios. Uses mocks, sleep patching, and logger patching.
Usage Examples examples/retry_decorator_usage.py	Demonstrates decorator usage across five scenarios: basic retry, custom critical operations, quick retries with tight delays, specific exception handling, and integration within an APIAdapter class. Each example simulates failures via randomization to illustrate retry behavior.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Add retry decorator with exponential backoff' is concise, clear, and directly summarizes the main change in the PR—adding a new retry decorator feature.
Description check	✅ Passed	The PR description covers the core requirements with summary, changes, features, usage examples, testing details, and a checklist. It aligns well with the template structure and provides sufficient detail.
Linked Issues check	✅ Passed	The PR satisfies all coding requirements from issue #27: retry decorator created in utils.py with configurable parameters, logging implemented, decorator exported, and comprehensive tests added. Examples show reusability.
Out of Scope Changes check	✅ Passed	All changes are directly within scope of issue #27. The decorator implementation, exports, tests, and examples all serve the stated objective of adding retry functionality.
Docstring Coverage	✅ Passed	Docstring coverage is 88.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/agentunit/core/utils.py (1)

15-21: Consider narrower default exception catching.

The default exceptions=(Exception,) will catch all exceptions including programming errors (AttributeError, TypeError, etc.) which typically shouldn't be retried. Consider defaulting to network-related exceptions like (ConnectionError, TimeoutError, OSError) or documenting that users should specify appropriate exceptions for their use case.

Suggested improvement

 def retry(
     max_retries: int = 3,
     base_delay: float = 1.0,
     max_delay: float = 60.0,
     exponential_base: float = 2.0,
-    exceptions: tuple[type[Exception], ...] = (Exception,),
+    exceptions: tuple[type[Exception], ...] = (ConnectionError, TimeoutError, OSError),
 ) -> Callable[[F], F]:
     """
     Decorator that retries a function with exponential backoff on failure.

     This decorator is useful for handling flaky API calls or network operations
     that may fail temporarily. It implements exponential backoff to avoid
     overwhelming the service with rapid retry attempts.

     Args:
         max_retries: Maximum number of retry attempts (default: 3).
         base_delay: Initial delay between retries in seconds (default: 1.0).
         max_delay: Maximum delay between retries in seconds (default: 60.0).
         exponential_base: Base for exponential backoff calculation (default: 2.0).
-        exceptions: Tuple of exception types to catch and retry (default: (Exception,)).
+        exceptions: Tuple of exception types to catch and retry (default: network-related exceptions).

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1cb0d78 and f4d0168.

📒 Files selected for processing (4)

• examples/retry_decorator_usage.py
• src/agentunit/core/__init__.py
• src/agentunit/core/utils.py
• tests/test_retry_decorator.py

🧰 Additional context used

🧬 Code graph analysis (4)

src/agentunit/core/utils.py (1)

src/agentunit/comparison/statistics.py (1)

• min (50-51)

tests/test_retry_decorator.py (1)

src/agentunit/core/utils.py (1)

• retry (15-85)

src/agentunit/core/__init__.py (1)

src/agentunit/core/utils.py (1)

• retry (15-85)

examples/retry_decorator_usage.py (1)

src/agentunit/core/utils.py (1)

• retry (15-85)

🔇 Additional comments (3)

src/agentunit/core/__init__.py (1)

10-10: LGTM! Clean public API exposure.

The retry decorator is correctly imported and exposed in __all__, following the existing module patterns.

Also applies to: 13-21

tests/test_retry_decorator.py (1)

1-194: LGTM! Comprehensive test coverage.

The test suite thoroughly covers all key scenarios including success without retry, retry behavior, exponential backoff validation, max delay capping, exception filtering, argument/metadata preservation, logging verification, and realistic use cases. The tests are well-structured with appropriate mocking and fast execution times.

examples/retry_decorator_usage.py (1)

1-172: LGTM! Excellent examples demonstrating diverse use cases.

The example file provides clear, practical demonstrations of the retry decorator across multiple scenarios: basic usage, custom configurations for critical operations, quick retries, specific exception handling, and integration with adapter classes. The code is well-documented and runnable, serving as effective documentation for users.