--- id: CON-PFM-LLM-004 name: AI Usage feature: FEAT-PFM-LLM-04 product_area: platform module: llm revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- AI usage is the reported account of model activity, cost and outcomes, combining request history with daily aggregates and live allowance positions. owned_by: MOD-PFM-LLM synonyms: - AI spend - AI Usage page not_to_be_confused_with: - 'Allowance capacity, which controls prospective admission.' - 'A general record audit, which has a wider scope than AI control history.' facets: - name: Daily figures meaning: 'Daily aggregates retain activity, cost, usage and timing across organization and routing dimensions.' used_for: Supplying system-wide reporting. - name: Window meaning: >- UTC reporting windows cover the current month or recent thirty or ninety days with a preceding comparison. used_for: Comparing usage over time. - name: Utilisation and status meaning: Live committed capacity yields the utilization percentage and allowance state. used_for: Identifying organizations approaching or reaching their allowance. - name: Trend and breakdowns meaning: Grouped series and totals show which product and model dimensions drive usage. used_for: Explaining spending patterns. - name: Request directory meaning: A filtered organization history opens individual requests without their content. used_for: Locating customer-reported work. - name: AI control history meaning: 'AI audit events retain limit, grant, correction and content-access actions.' used_for: Reviewing accountable administrative changes. - name: Reports meaning: 'Query datasets and prepared recipes expose permitted request, task and daily usage fields.' used_for: Answering reporting questions with existing query tools. relationships: - to: CON-PFM-LLM-001 statement: Aggregates summarize terminal request history while the directory exposes individual metadata. provenance: observed source: 'services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts' - to: CON-PFM-LLM-003 statement: Live credit positions determine organization utilization and status. provenance: observed source: 'services-platform:modules/llm/services/usage-reports/tenant-positions.ts' acted_on_by: - CAP-PFM-LLM-010 - CAP-PFM-LLM-011 - CAP-PFM-LLM-017 visible_to: - ACT-PFM-033 - ACT-PFM-004 - ACT-PFM-007 evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (The daily rollup, The HQ surface, Reporting); modules/llm/services/usage-reports/*; db/llm-usage-daily.table.ts, llm-usage-daily-query.view.ts, llm-invocations-query.view.ts; docs/proposals/llm-observability/06-reporting-and-analytics.md. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: app/(console)/hq/aiUsage/**; components/console/hq/ai-usage/**; components/console/hq/tenant-ai-usage-card.tsx. supersedes: [] --- # AI Usage ## What It Is AI usage is the account staff consult when they need to understand what model work has happened and what it costs. It combines several views rather than being one balance. Individual requests explain a particular event. Executions explain a larger task. Daily aggregates support system-wide comparisons, and live allowance figures show an organization’s present capacity pressure. Reading them together lets support move from a broad concern to the specific work behind it. Daily reporting assigns a closed request to the UTC day on which it starts, even if it settles later. Reconciliation rebuilds affected day totals and advances a progress watermark. Running work is absent from those settled daily figures but its held credits can already affect the live allowance position. That distinction explains why a dashboard’s allowance status and its historical spend chart answer different questions. ## What It Is Not Usage is not the allowance itself, an invoice from the model provider or captured conversation content. Reported dollars use declared list prices rather than supplier-bill reconciliation. An AI control audit trail explains administrative actions but does not replace every other record’s history. A request-directory permission likewise does not authorize a sensitive prompt read. ## How It Is Used Rhythm staff use the system-wide view to find expensive or constrained organizations and compare models or features. They follow an organization into its card and request history to diagnose a customer’s question. Customer administrators use their narrower organization service in credits and percentages, with internal model and commercial detail withheld. An unavailable report section should be treated as missing evidence rather than zero usage. Healthy investigation checks the reporting window, the rollup progress and the live account before drawing conclusions. ## Its Facets **Daily figures.** Aggregates retain requests, outcomes, credits, cents, model usage and timing by their organization and routing dimensions. **Window.** Reporting periods use UTC days and include an equal-length preceding period for comparison. **Utilisation and status.** Live charged and held credits determine capacity pressure and are not frozen at a previously recorded crossing. **Trend and breakdowns.** Trends keep the ten largest series and collect the remainder as Other, while breakdowns explain dimension totals. **Request directory.** Filters and stable pagination help staff find an individual request without exposing its body. **AI control history.** The relevant audit events explain who changed capacity or accessed evidence and why. **Reports.** Existing query tools expose scoped datasets and prepared recipes for staff and organization administrators. ## How It Relates Requests supply the activity and settlement facts. The allowance supplies current utilization and restriction state. Operations supply feature and model attribution and historical versions. Security owns the underlying audit store and permission evaluation; Queries owns the reporting engine. The console hosts these views without owning the facts they report. ## What It Could Become The product should complete the customer dashboard and verify its end-to-end figures against HQ. Early-warning signals, provider-outage protection and raw-record retention remain future work rather than properties of today’s reports. Product also needs to decide how reporting at UTC boundaries should be explained beside local-calendar allowance months. A complete inventory of screens and tests establishes coverage locations, while acceptance still needs proof of customer outcomes.