Reusable Decorators for AI Request Handling

Service classes (Lesson 1) centralize what gets called on the OpenAI SDK. But several concerns apply uniformly to almost every SDK call regardless of what it does: retrying on transient failures, logging how long a call took, and recording that a call happened at all. Writing this logic inside every method quickly turns a five-line method into thirty lines of retry loops and try/except blocks. Python decorators let you write this cross-cutting logic once and apply it declaratively to any method that needs it.

What a Decorator Is

A decorator is a function that takes another function (or method) as input and returns a new function that wraps it, typically adding behavior before and/or after the original call:

import time


def timed(func):
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.3f}s")
        return result
    return wrapper


@timed
def slow_add(a: int, b: int) -> int:
    time.sleep(0.1)
    return a + b


print(slow_add(2, 3))

The @timed syntax above def slow_add(...) is equivalent to writing slow_add = timed(slow_add) immediately after the function is defined. Every call to slow_add(2, 3) actually calls wrapper(2, 3), which calls the original slow_add internally, times it, and returns its result. This is why decorators are the right tool for cross-cutting concerns: the behavior added by wrapper — timing, in this case — applies uniformly to any function decorated with @timed, without that function's own code needing to know timing exists.

Preserving Function Metadata with functools.wraps

The wrapper function above has a subtle problem: slow_add.__name__ now returns "wrapper", not "slow_add", because wrapper is what actually got assigned to the name slow_add. This breaks introspection, debugging output, and documentation tools that rely on a function's name and docstring. The fix is functools.wraps:

import functools
import time


def timed(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.3f}s")
        return result
    return wrapper

@functools.wraps(func) copies func.__name__, func.__doc__, and other metadata onto wrapper, so slow_add.__name__ correctly reports "slow_add" even after decoration. Every decorator you write should use functools.wraps — omitting it is one of the most common decorator bugs, and it silently breaks tools (debuggers, API documentation generators, some testing frameworks) that inspect function metadata.

A Retry Decorator for Transient SDK Failures

Network calls to any external API, including the OpenAI SDK, occasionally fail for transient reasons — a dropped connection, a temporary rate limit. Retrying a failed call a small number of times, with a short pause between attempts, is a common and reasonable strategy, and it is exactly the kind of logic that should not be duplicated inside every service method:

import functools
import time


def retry(max_attempts: int = 3, delay_seconds: float = 1.0):
    def decorator(func):
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            last_error = None
            for attempt in range(1, max_attempts + 1):
                try:
                    return func(*args, **kwargs)
                except Exception as error:
                    last_error = error
                    if attempt < max_attempts:
                        time.sleep(delay_seconds)
            raise last_error
        return wrapper
    return decorator

Notice this decorator takes its own arguments (max_attempts, delay_seconds), which means it needs an extra layer of nesting: retry(...) returns decorator, and decorator(func) returns wrapper. This three-level structure (retry → decorator → wrapper) is the standard shape for any decorator that accepts configuration arguments.

Applying it to a service method:

class SummarizerService:
    def __init__(self, client, model: str = "gpt-5.6-terra") -> None:
        self._client = client
        self._model = model

    @retry(max_attempts=3, delay_seconds=0.5)
    def summarize(self, text: str) -> str:
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
        )
        return response.output_text

Every call to summarize now automatically retries up to three times if the underlying client raises an exception, without a single retry-related line inside the method's own body.

A Logging Decorator

Similarly, logging that a call happened — and with what arguments, and how it ended — is best expressed as a decorator rather than manual print or logging calls inside every method:

import functools
import logging

logger = logging.getLogger(__name__)


def log_call(func):
    @functools.wraps(func)
    def wrapper(*args, **kwargs):
        logger.info("calling %s", func.__name__)
        try:
            result = func(*args, **kwargs)
        except Exception:
            logger.exception("%s raised an exception", func.__name__)
            raise
        logger.info("%s completed successfully", func.__name__)
        return result
    return wrapper

Stacking Multiple Decorators

Decorators can be combined, and order matters — decorators closest to the function run "first" (innermost), and are wrapped by the ones above them:

class SummarizerService:
    def __init__(self, client, model: str = "gpt-5.6-terra") -> None:
        self._client = client
        self._model = model

    @log_call
    @retry(max_attempts=3, delay_seconds=0.5)
    def summarize(self, text: str) -> str:
        response = self._client.responses.create(
            model=self._model,
            input=f"Summarize:\n\n{text}",
        )
        return response.output_text

Reading from the function outward: retry wraps summarize directly, and log_call wraps the retrying version. So each retry attempt happens inside a single "calling summarize" log entry — log_call logs once per external call to summarize, not once per internal retry attempt. Swapping the order (@retry above @log_call) would instead log once per individual retry attempt, since log_call would then be the inner decorator, re-executed on every retry.

When to Use a Decorator vs. When Not To

Decorators are the right tool when a concern applies uniformly, without exceptions, across many call sites, and does not need to know anything about the specific business logic being wrapped — retrying, timing, logging, and simple caching are classic examples. They are the wrong tool when the logic needs to inspect or transform the business-specific result in a way specific to one method, or when the "cross-cutting" behavior actually differs meaningfully between call sites — in that case, ordinary composition (calling a helper function explicitly) is clearer than hiding conditional logic inside a generic-looking decorator.

Testing Decorated Methods

Decorators complicate testing only if they are not designed carefully. Because retry and log_call both use functools.wraps and only add behavior around the original call, tests can inject a fake client exactly as in earlier lessons, and verify the decorated behavior directly:

class FlakyFakeResponsesAPI:
    def __init__(self, fail_times: int, output_text: str) -> None:
        self._fail_times = fail_times
        self._calls = 0
        self._output_text = output_text

    def create(self, **kwargs):
        self._calls += 1
        if self._calls <= self._fail_times:
            raise ConnectionError("simulated transient failure")
        return type("FakeResponse", (), {"output_text": self._output_text})()


class FlakyFakeClient:
    def __init__(self, fail_times: int, output_text: str) -> None:
        self.responses = FlakyFakeResponsesAPI(fail_times, output_text)


def test_summarize_retries_and_succeeds_after_transient_failures() -> None:
    fake_client = FlakyFakeClient(fail_times=2, output_text="A short summary.")
    service = SummarizerService(client=fake_client)

    result = service.summarize("Some long text to summarize.")

    assert result == "A short summary."
    assert fake_client.responses._calls == 3
    print("PASS: summarize succeeds on the third attempt after two failures")


test_summarize_retries_and_succeeds_after_transient_failures()

FlakyFakeResponsesAPI deliberately raises an exception on its first two calls and succeeds on the third, letting the test verify the retry decorator's actual behavior — that it retries the configured number of times and eventually returns the successful result — without any real network calls or real delays beyond the small delay_seconds set in the decorator.

Common Mistakes

Forgetting functools.wraps. This silently corrupts __name__, __doc__, and other metadata on every decorated function, which can break logging output, debugging tools, and any code that inspects function metadata.

Retrying on every exception type indiscriminately. A bare except Exception retries even on errors that will never succeed no matter how many times you retry — such as an invalid request or an authentication failure. Catch specific, genuinely transient exception types where the SDK distinguishes them.

Hiding important behavior inside an opaque decorator stack. A method wrapped in five decorators, each silently altering timeouts, retries, and error handling, can become very difficult to reason about. Keep the decorator stack short and each decorator's purpose obvious from its name.

Best Practices

Always apply functools.wraps inside every decorator you write. This one line prevents an entire category of subtle, hard-to-diagnose bugs.

Make retry decorators configurable, with sane defaults. Accepting max_attempts and delay_seconds as parameters (rather than hardcoding them) lets different methods tune retry behavior without duplicating the decorator's logic.

Keep decorators focused on one concern each. A single decorator that retries, logs, and times a call all at once is harder to test and reuse than three small decorators stacked together.

Test decorated behavior directly, using fakes that simulate the failure mode being handled. A fake client that fails a controlled number of times before succeeding (as shown above) is the clearest way to verify retry logic actually works as intended.