--- id: CON-PFM-LLM-001 name: AI Request feature: FEAT-PFM-LLM-01 product_area: platform module: llm revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- An AI request records one model conversation performed for a Rhythm feature, including its attribution, outcome and charge. owned_by: MOD-PFM-LLM synonyms: - invocation - model call - AI call not_to_be_confused_with: - 'A provider attempt, which is one exchange within the request.' - 'An AI task, which can group several requests.' - 'A staff conversation, which can contain multiple model requests.' facets: - name: Attempt meaning: 'A provider attempt carries one turn’s operational result, including any retry.' used_for: 'Inspecting retries, latency and reported usage.' - name: AI task meaning: An execution groups the model requests made by one larger piece of work. used_for: 'Reviewing a task’s combined cost, duration and result.' - name: Outcome and settlement meaning: Conversation outcome describes how work ended; settlement describes how its cost is accounted for. used_for: Separating an incomplete answer from a missing or measured charge. - name: Refusal figures meaning: A refused request retains the allowance and restriction figures used for that decision. used_for: Explaining an earlier refusal without substituting today’s balance. - name: Captured content meaning: Redacted request and response bodies have capture statuses and a ninety-day evidence retention policy. used_for: Investigating model behavior through a controlled content read. - name: Attribution meaning: 'Caller context and published routing identify the organization, application, feature and access type.' used_for: Connecting usage to the work and caller that generated it. relationships: - to: CON-PFM-LLM-002 statement: Requests reference the published routing and model-price versions used for accounting. provenance: observed source: 'services-platform:modules/llm/db/llm-invocations.table.ts' - to: CON-PFM-LLM-003 statement: Admitted requests reserve credits and normally settle against a monthly allowance period. provenance: observed source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts' - to: CON-PFM-LLM-004 statement: Terminal request records contribute to the daily usage aggregates. provenance: observed source: 'services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts' lifecycle: - state: Estimated meaning: The initial record contains its calculated reservation. how_it_changes: Admission either reserves capacity or refuses the request. - state: Held and sent meaning: Capacity is reserved and provider dispatch has begun. how_it_changes: The conversation reaches a completion or error outcome. - state: Settled meaning: The request has a terminal accounting record. Normal settlement releases its reservation. how_it_changes: A later correction changes the period through a separate record. - state: Refused meaning: Admission stopped the request before provider dispatch. how_it_changes: A later request undergoes a new admission decision. acted_on_by: - CAP-PFM-LLM-001 - CAP-PFM-LLM-002 - CAP-PFM-LLM-003 - CAP-PFM-LLM-004 - CAP-PFM-LLM-007 - CAP-PFM-LLM-009 - CAP-PFM-LLM-011 - CAP-PFM-LLM-012 - CAP-PFM-LLM-016 - CAP-PFM-LLM-018 visible_to: - ACT-PFM-033 - ACT-PFM-004 - ACT-PFM-007 evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md; modules/llm/db/llm-invocations.table.ts, llm-invocation-attempts.table.ts, llm-executions.table.ts; services/execution/run-operation.ts, with-llm-execution.ts; services/metering/refusal-snapshot.ts; services/evidence/*. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/hq/ai-usage/request/*, ai-usage-execution-detail.tsx. supersedes: [] --- # AI Request ## What It Is An AI request is the continuing account of one conversation between a Rhythm feature and a model. Staff do not create the account directly. They ask a feature to do something, such as describe a query, and that feature invokes a declared operation. Platform creates a usage record before it asks the allowance ledger to admit the work. A refused request therefore still has a record even though it never reaches a model. The request carries the operation and pricing versions it uses, its organization and caller attribution, the conversation’s progress and its eventual outcome. A support representative can use that account to distinguish a feature switched off from a provider failure or a conversation that simply runs out of turns. The charge is a related but separate fact: a failed conversation can still consume billable usage, while a supplier that never answers can leave nothing to charge. ## What It Is Not A request is broader than a single provider message. One conversation may take several turns, and a turn may retry. It is also smaller than a user task when that task makes several conversations. A Jazz AI chat is a staff-facing history whose exchanges can use metered query interpretation, an unmetered general reply, or local directory rules. Those histories do not imply that every visible reply has a Platform request. ## How It Is Used Engineers use the shared request boundary when adding an AI feature. The feature supplies tools and determines whether a proposed answer is acceptable. Platform handles admission, model execution and accounting. Support staff inspect request history when a customer reports a refusal or an unexpectedly costly task. Good diagnosis reads both outcome and settlement rather than assuming that an answer, a failure and a charge always move together. Captured content requires additional authority beyond an ordinary usage read. ## Its Facets **Attempt.** Each retained provider attempt explains a turn or retry through operational fields, not conversation text. The retention bound can make the attempt list incomplete, which the request marks explicitly. **AI task.** An execution supplies the larger unit of work and collects request settlements into task totals. **Outcome and settlement.** The conversation can answer, stop at a limit, be refused or fail. Accounting can use measured usage, an estimate or a release. **Refusal figures.** Stored decision-time numbers let staff explain the original refusal separately from present admission. **Captured content.** Evidence preserves redacted bodies when capture succeeds and keeps their storage separate from routine reporting. **Attribution.** Organization, feature and caller context make usage traceable without treating a service’s asserted beneficiary as independently verified. ## How It Relates The AI operation supplies the published routing and rate versions. The AI allowance admits the request and receives its charge. AI usage aggregates closed requests for reporting and provides the directory through which support finds them. The consuming feature owns the meaning and application of the final answer. ## What It Could Become The product should strengthen interrupted-request recovery before describing settlement as unconditional. The runtime can leave a hold before its cleanup block begins, and terminal request and allowance writes can diverge across a process interruption. Product also needs to decide how general teammate replies enter this accounting boundary. These changes should preserve the distinction between a conversation’s result, its evidence and its charge.