qfa.adapters.tracking_llm

LLM port decorator that records every call attempt for usage tracking.

Classes

TrackingLLMAdapter(inner, usage_repo)

Decorator over an inner LLMPort that records every call attempt.

class qfa.adapters.tracking_llm.TrackingLLMAdapter(inner: LLMPort, usage_repo: UsageRepositoryPort)

Bases: LLMPort

Decorator over an inner LLMPort that records every call attempt.

Reads tenant + operation from current_call_context. Persists one LLMCallRecord per attempt (success or failure). Recording errors are logged but never raised, so a misbehaving usage repository never breaks an analysis. Connection-class transient errors (OperationalError, InterfaceError) are retried up to 3 times with exponential backoff capped at 0.5s per wait — worst-case added latency under a sustained DB outage is ~0.3s of waits plus 3 fast-failing connection attempts (typically <1s total). Non-transient errors (IntegrityError, ProgrammingError, etc.) skip the retry path and are logged immediately.

Parameters:

• inner (LLMPort) – The wrapped LLM adapter.

• usage_repo (UsageRepositoryPort) – Repository used to persist call records.

async complete(system_message: str, user_message: str, tenant_id: str, response_model: type[T_Response], timeout: float = 20.0) → LLMResponse

Run the inner complete and record the attempt.

Raises:

MissingCallScopeError – When current_call_context is unset; indicates a wiring bug (the orchestrator forgot to enter call_scope).