qfa.adapters.usage_repository#

SQLAlchemy-backed usage repository.

Reads aggregated LLM-call statistics from the llm_calls table declared in qfa.adapters.db. The repository exposes two views:

Per-invocation — one entry per distinct call_id, so a single REST API call that fans out to N LLM calls counts once.
Per-LLM-call (llm_call_stats) — one entry per raw LLM call attempt.

Both views are produced from the same row set in one SELECT per view, using a Postgres CTE (for per-invocation) plus CUBE(tenant_id, operation) — which yields the four grouping-sets rollup cells (tenant, operation) / (tenant) / (operation) / () in a single round-trip.

Internally, both views share one query builder, one row parser, and one pivot — only the SQL source differs (raw llm_calls vs a CTE pre-aggregated by call_id). The duality is expressed once as a view: Literal["llm_call", "invocation"] parameter rather than carried through as parallel code paths.

Classes

SqlAlchemyUsageRepository(session_factory)

Usage repository backed by SQLAlchemy and PostgreSQL.

class qfa.adapters.usage_repository.SqlAlchemyUsageRepository(session_factory: Callable[[...], AsyncSession])[source]#

Bases: UsageRepositoryPort

Usage repository backed by SQLAlchemy and PostgreSQL.

Parameters:: session_factory (Callable[..., AsyncSession]) – Factory for creating async database sessions.

async record_call(record: LLMCallRecord) → None[source]#: Insert a single LLM call attempt record.

async get_usage_stats_for_one_tenant(tenant_id: str, from_: datetime | None = None, to: datetime | None = None) → TenantUsageStats[source]#

Per-invocation and per-LLM-call stats for one tenant.

Single-tenant SELECT pair grouped by both tenant and operation. Returns a zero TenantUsageStats when no rows match the window.

async get_all_usage_by_tenant(from_: datetime | None = None, to: datetime | None = None) → list[TenantUsageStats][source]#: Per-tenant + grand-total stats with per-operation breakdown.

async get_all_usage_by_operation(from_: datetime | None = None, to: datetime | None = None) → list[OperationUsageStats][source]#: Per-operation + grand-total stats with per-tenant breakdown.