Wrappers

cache, retry, timeout, with_model, fallback, mock, log. Signatures, parameters, returns.

Each wrapper takes a Call and returns a new Call. Compose freely. See the wrappers guide for usage patterns.

cache

bridle.cache(
    call: Call,
    *,
    key: Callable[[Call], str] | str | None = None,
    backend: CacheBackend | None = None,
    ttl: float | None = None,
    label: str | None = None,
) -> Call

Memoize call.

Parameter	Type	Description
`call`	`Call`	The call to memoize.
`key`	`str \| Callable \| None`	Fixed string, callable taking the inner `Call`, or None for the default deterministic key.
`backend`	`CacheBackend \| None`	Override the active backend. Defaults to the one set via `bridle.set_cache`, or an in-memory cache.
`ttl`	`float \| None`	Seconds to live. None means no expiry.
`label`	`str \| None`	Trace label. Defaults to `"cache"`.

The default key hashes kind | schema fingerprint | prompt | context | tools fingerprint. Two calls with the same five parts share a key across processes.

Trace events: cache_hit on key found, cache_miss on miss (and again with write_error if a write fails).

retry

bridle.retry(
    call: Call,
    *,
    attempts: int = 3,
    on: type[BaseException] | tuple[...] = BridleError,
    backoff: float | Callable[[int], float] | None = None,
    label: str | None = None,
) -> Call

Re-evaluate call when it raises a matching exception. Each attempt clones the inner call.

Parameter	Type	Description
`call`	`Call`	The call to retry.
`attempts`	`int`	Total attempts. Must be positive. Default 3.
`on`	exception type or tuple	What to catch. Default `BridleError`.
`backoff`	`float \| Callable[[int], float] \| None`	Fixed seconds, or a callable taking the 0-based attempt index.
`label`	`str \| None`	Trace label. Defaults to `"retry"`.

Trace events: retry per attempt with attempt number, remaining count, and error string.

Raises: the last error from the inner call after all attempts exhausted.

timeout

bridle.timeout(
    call: Call,
    *,
    seconds: float,
    label: str | None = None,
) -> Call

Abort call if it takes longer than seconds. Implemented with a single-thread executor and a copied contextvars.Context.

Parameter	Type	Description
`call`	`Call`	The call to bound.
`seconds`	`float`	Wall-clock deadline.
`label`	`str \| None`	Trace label. Defaults to `"timeout"`.

Raises: bridle.TimeoutError on deadline. The underlying work continues until the SDK's own cancellation kicks in.

with_model

bridle.with_model(
    call: Call,
    model: str,
    *,
    label: str | None = None,
) -> Call

Override the model for call. Highest-precedence layer of model resolution.

Parameter	Type	Description
`call`	`Call`	The call to override.
`model`	`str`	Model id passed to the active model client.
`label`	`str \| None`	Trace label. Defaults to `"with_model[<model>]"`.

fallback

bridle.fallback(
    call: Call,
    *alternates: Call,
    label: str | None = None,
) -> Call

Try call; on BridleError, try each alternate in order. The first to resolve wins.

Parameter	Type	Description
`call`	`Call`	Primary candidate.
`*alternates`	`Call`	Subsequent candidates, tried in order.
`label`	`str \| None`	Trace label. Defaults to `"fallback"`.

Trace events: retry per failed candidate with reason: "fallback", candidate index, remaining count.

Raises: the last BridleError if every candidate failed.

mock

bridle.mock(
    call: Call,
    value: Any,
    *,
    label: str | None = None,
) -> Call

Replace call's dispatch with a constant. The wrapper's call_start and call_end still fire, so trace assertions on shape remain valid.

Parameter	Type	Description
`call`	`Call`	The call whose dispatch to short-circuit.
`value`	`Any`	The constant returned in place of the inner work.
`label`	`str \| None`	Trace label. Defaults to `"mock"`.

log

bridle.log(
    call: Call,
    *,
    level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO",
    logger_name: str = "bridle",
    label: str | None = None,
) -> Call

Stream the active trace's events to a Python logger for call's subtree.

Parameter	Type	Description
`call`	`Call`	The subtree to log.
`level`	log level literal	Logging level for emitted events. Default `"INFO"`.
`logger_name`	`str`	Logger name. Default `"bridle"`.
`label`	`str \| None`	Trace label. Defaults to `"log"`.

Each event is logged as bridle.<kind> call_kind=<...> label=<...> error=<...>.

Wrappers

cache

retry

timeout

with_model

fallback

mock

log

Wrappers guide

Caching guide

Errors

Cache backends

On this page