Rhythm 2.0 Specifications

Appearance

CON-PFM-LLM-001AI Request

Markdown

CON-PFM-LLM-001

AI Request

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-LLM-01
Owned by
MOD-PFM-LLM
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
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.

Design

Specified by
DOM-PFM-LLM-001

KindKey conceptProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

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.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Definition
An AI request records one model conversation performed for a Rhythm feature, including its attribution, outcome and charge.
Synonyms
invocationmodel callAI call

Relationships

ToStatementProvenance
CON-PFM-LLM-002Requests reference the published routing and model-price versions used for accounting.observed
services-platform:modules/llm/db/llm-invocations.table.ts
CON-PFM-LLM-003Admitted requests reserve credits and normally settle against a monthly allowance period.observed
services-platform:modules/llm/services/persistence/allowance-periods.ts
CON-PFM-LLM-004Terminal request records contribute to the daily usage aggregates.observed
services-platform:modules/llm/services/reconciliation/rollup-settled-invocations.ts

Lifecycle

StateMeaningHow it changes
EstimatedThe initial record contains its calculated reservation.Admission either reserves capacity or refuses the request.
Held and sentCapacity is reserved and provider dispatch has begun.The conversation reaches a completion or error outcome.
SettledThe request has a terminal accounting record. Normal settlement releases its reservation.A later correction changes the period through a separate record.
RefusedAdmission stopped the request before provider dispatch.A later request undergoes a new admission decision.

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software