Rhythm 2.0 Specifications

Appearance

DOM-PFM-LLM-001AI Request

Markdown

DOM-PFM-LLM-001

AI Request

Markdown
  • DocumentDraft
  • ImplementationObserved

Planning

Specified by
CON-PFM-LLM-001

Design

Owned by
SVC-PFM-LLM-llm

KindDomain objectProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

AI Request ​

What It Models ​

An AI request records one model conversation for a consuming feature. Support uses it to inspect attribution, provider attempts, outcome and charge. Its task groups related requests, while captured evidence holds redacted conversation bodies separately.

Identity and Attributes ​

The runtime creates the identifier before admission. It copies published routing and price references and derives attribution from the caller context. A local month key identifies the allowance period even before that period exists. Outcome and settlement are independent: unsuccessful work can incur a charge, and an estimate settlement has no known monetary cost. Task records retain their declared feature, subject, caller, timing and accumulated settlements.

Relationships ​

The request refers to operation versions and an allowance month. An optional task association comes from the exact context supplied by the execution wrapper. Derived reporting groups closed requests by their start day. The consuming feature retains responsibility for validating and applying the answer.

Invariants ​

Normal status changes require an expected current status. Settlement excludes requests already settled or refused and increments task totals in its own transaction. That protection does not make allowance movements atomic with request changes. Attempt storage has a retention-count limit, while evidence references have database checks.

How It Is Stored and Shared ​

Platform stores requests, attempts and tasks under organization-scoped access. HQ detail routes enter the selected organization; the reporting reader uses the daily aggregate instead. Customer reports omit conversation bodies and sensitive bookkeeping. Private object storage holds redacted bodies under the organization prefix with a ninety-day lifecycle policy; workspace removal deletes those versions after dependent records.

Open Design Questions ​

A hold can commit before its amount is recorded on the request, and settlement can commit before the month receives its charge. Recovery does not repair terminal requests with incomplete period accounting. Product must decide how stale requests should be charged and whether asserted beneficiary attribution needs verification.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-PFM-LLM-002many requests to one routing version and one rate versionThe operation catalogue owns its definitions; related records keep references.no
DOM-PFM-LLM-003many requests to one monthly allowance periodThe allowance owns period accounting and configuration; linked records consume those figures.no
DOM-PFM-LLM-004many requests summarised into many daily usage rowsReporting derives its values without owning the underlying records.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-PFM-LLM-001-01
The runtime creates the request before reserving credits or contacting a provider.
serviceobserved
services-platform:modules/llm/services/execution/run-operation.ts:runOperation
INV-DOM-PFM-LLM-001-02
Normal status writes compare the expected state, and a competing change produces a no-op.
service, databaseobserved
services-platform:modules/llm/db/llm-invocations.table.ts:LLM_INVOCATION_TRANSITIONS
INV-DOM-PFM-LLM-001-03
Settlement changes the request and task totals once; period accounting remains separate and cleanup can still release credits after a competing settlement.
service, databaseobserved
services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled
INV-DOM-PFM-LLM-001-04
Estimate settlement omits cents, while release records zero credits and cents.
service, databaseobserved
services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled
INV-DOM-PFM-LLM-001-05
Admission refusal records its reason and snapshot without dispatching or taking a hold.
serviceobserved
services-platform:modules/llm/services/persistence/invocations.ts:markInvocationRefused
INV-DOM-PFM-LLM-001-06
The runtime derives routing and feature attribution from published configuration.
serviceobserved
services-platform:modules/llm/services/execution/run-operation.ts:runOperation
INV-DOM-PFM-LLM-001-07
Only the exact task-scoped context attaches a request to an execution.
serviceobserved
services-platform:modules/llm/services/execution/execution-scope.ts:llmExecutionIdOf
INV-DOM-PFM-LLM-001-08
Attempt rows contain operational metadata; counts beyond sixty-four mark truncation without storing more rows.
service, databaseobserved
services-platform:modules/llm/db/llm-invocation-attempts.table.ts:MAX_ATTEMPTS_PER_INVOCATION
INV-DOM-PFM-LLM-001-09
A captured body requires a non-null storage key.
databaseobserved
services-platform:db/migrations/0048_llm.sql:llm_invocations_request_payload_key_check
INV-DOM-PFM-LLM-001-10
Request settlement increments task totals in the same transaction.
service, databaseobserved
services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled
INV-DOM-PFM-LLM-001-11
Documented organization row policy restricts request and attempt access to the selected organization.
databasedocumented
services-platform:docs/llm.md#The tables
INV-DOM-PFM-LLM-001-12
Stored request failure classifications use a closed vocabulary, and caller errors use Rhythm’s wording.
serviceobserved
services-platform:modules/llm/db/llm-invocations.table.ts:LLM_INVOCATION_ERROR_CLASSIFICATIONS

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