cadrumo.adapters.outbound.llm.client module

Async-first public LLM client.

Coordinates LLMRequest inputs, LLMCache lookup/write-through, UsageRecorder accounting, and concrete LLMProvider adapters before returning an LLMResponse.

transport_retry_permitted(exc)

Whether exc may be retried by re-sending the identical request.

Derived from the error taxonomy, never listed here. Every CadrumoError subclass is required to carry a registered ErrorCode, and that record already declares retryable for the operator-facing envelope. Reading the answer from there means a new failure class cannot be silently omitted from a retry set: it cannot exist at all without declaring the answer, because the registry bind refuses an unregistered subclass at class-creation time. A hand-kept set is the shape that has already shipped in this repository carrying half its members.

Anything that is not a registered error is NOT retryable. That is the fail-closed direction: an exception leaking from a dependency has made no statement about whether re-sending is safe, and inventing one for it is how a contention or consent refusal would end up retried by accident.

Parameters:

exc (BaseException) – The exception raised by the provider adapter.

Return type:

bool

Returns:

True only when the taxonomy declares this failure class retryable.

class LLMRetryPolicy(**data)

Bases: BaseModel

The typed, bounded retry policy applied to one transport dispatch.

Data on the client rather than behaviour scattered through the adapters, so the answer to “how many times, how long, and for which failures” is one readable record instead of four vendor-specific loops.

Scoped by the taxonomy, not by this model. Which failures are eligible is transport_retry_permitted()’s answer, read from the registered error code; this model only decides how often and how long. That separation is deliberate: the eligibility question has exactly one right answer for the whole process, while the timing is a deployment tuning knob.

Variables:

• max_attempts – Total attempts including the first. One disables retrying.

• initial_backoff_s – The first backoff, doubling per subsequent attempt.

• max_backoff_s – Ceiling on a single backoff, before jitter.

• budget_s – Total wall-clock ceiling across every attempt and every wait. A bounded budget, not merely a bounded count: a retry schedule whose waits grow can otherwise outlive the operator’s patience while technically respecting its attempt limit.

Parameters:

data (Any)

max_attempts: int

initial_backoff_s: float

max_backoff_s: float

budget_s: float

backoff_for(attempt, *, retry_after_s=None)

Return the wait before the attempt following attempt.

Exponential from initial_backoff_s, capped at max_backoff_s, then jittered into the upper half of that interval. Jitter is not decoration: without it, a batch that failed together retries together, and the synchronised burst is itself a plausible cause of the next failure.

A server-supplied Retry-After wins whenever it asks for LONGER than the computed backoff. It is never allowed to shorten the wait, because a vendor’s hint about its own rate window says nothing about this machine’s recovery.

Parameters:

• attempt (int) – The 1-based number of the attempt that just failed.

• retry_after_s (float | None) – A server-supplied delay hint, when the failure carried one.

Return type:

float

Returns:

Seconds to wait before the next attempt.

class LLMClient(*, settings=None, cache=None, usage_recorder=None, run_telemetry_recorder=None, consent_ledger=None, prompt_registry=None, retry_policy=None, hardware_profile=None, runtime_residents=None, runtime_residents_measured=True, caller='cadrumo.adapters.outbound.llm.client', prompt_id='adhoc')

Bases: object

Public async-first LLM completion entry point.

Parameters:

• settings (Settings | None) – Optional Settings override used for provider selection and defaults.

• cache (LLMCache | None) – Optional LLMCache implementation override.

• usage_recorder (UsageRecorder | None) – Optional UsageRecorder override.

• run_telemetry_recorder (LLMRunTelemetryRecorder | None) – Optional LLMRunTelemetryRecorder override.

• prompt_registry (PromptRegistry | None) – Optional PromptRegistry override.

• retry_policy (LLMRetryPolicy | None) – Optional LLMRetryPolicy override governing how often and how long a transient transport failure is re-sent. Which failures qualify is not tunable here – that is the error taxonomy’s answer, read through transport_retry_permitted().

• hardware_profile (HardwareProfile | None) – Optional measured HardwareProfile used for the headroom check instead of probing this machine. Injecting the MEASUREMENT rather than the verdict keeps the real decision function on the path: a post-quiesce reading exercises the same comparison, margin and attribution production runs.

• runtime_residents (tuple[RuntimeResident, ...] | None) – Optional resident set standing in for a live read of the runtime.

• runtime_residents_measured (bool) – False states the resident set could not be read, which is a different fact from a measured-empty one and reaches the fail-closed arm rather than the shortfall arm. The two are indistinguishable from the refusal alone, so a case that means to prove one must say which.

• caller (str) – Stable caller identifier recorded in usage logs.

• prompt_id (str) – Stable prompt identifier recorded in usage logs.

• consent_ledger (EvidenceConsentLedger | None)

async complete(request)

Complete a prompt request.

Parameters:

request (LLMRequest) – Structured LLMRequest.

Return type:

LLMResponse

Returns:

A LLMResponse enriched with cache and cost metadata.

Raises:

Exception – Re-raised after logging when the LLM provider adapter fails.