Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-001Run AI requests with consistent attribution and accounting

Markdown

CAP-PFM-LLM-001

Run AI requests with consistent attribution and accounting

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-LLM-01
Exercised by
FAS-PFM-LLM-01-01, FAS-PFM-LLM-01-02, FAS-PFM-LLM-01-03, FAS-PFM-LLM-01-04, FAS-PFM-LLM-01-05
Key concepts
CON-PFM-LLM-001, CON-PFM-LLM-002, CON-PFM-LLM-003
Actors
ACT-PFM-032, ACT-PFM-034, ACT-PFM-012
Journeys
JNY-PFM-LLM-001
Depends on
CAP-PFM-LLM-005, CAP-PFM-LLM-007
Related
CAP-PFM-LLM-002, CAP-PFM-LLM-003, CAP-PFM-LLM-004, CAP-PFM-LLM-013, CAP-PFM-LLM-018, CAP-PFM-LLM-019
Open questions
OQ-PFM-LLM-003
Proved by
ATS-PFM-LLM-001

Implementation

Executable suites
TST-PFM-LLM-018, TST-PFM-LLM-020, TST-PFM-LLM-061, TST-PFM-LLM-063, TST-PFM-LLM-075, TST-PFM-LLM-076, TST-PFM-LLM-086

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Run AI requests with consistent attribution and accounting ​

Purpose ​

Give consuming features a shared request boundary that records admission, model use and settlement.

How It Works ​

A feature requests an operation from the published catalog and supplies its conversation and tools. Platform resolves the routing and price before creating a usage record. It then checks organization restrictions and asks the allowance ledger to admit the work. An admitted request captures redacted evidence and enters the model conversation. When that conversation returns, Platform calculates its charge and releases its hold. Missing usage and provider failure have distinct settlement treatments. The feature receives an answer or a bounded outcome and decides how to present it. Cleanup and recovery have interruption gaps that the findings describe. The product should bring Jazz AI’s general replies within the same accounting boundary.

Relationships ​

  • Publish AI operation definitions and historical prices supplies the prerequisite behavior for this outcome.
  • Admit AI work against the organization’s monthly allowance supplies the prerequisite behavior for this outcome.

The Formal Contract

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

Outcomes
Requests carry organization, application, feature and person attribution.Normal completion records an outcome and a usage-based charge.Admission refusals use a defined set of reasons.
Surfaces
apijob
Preconditions
A published catalog entry identifies the requested operation.
Postconditions
Normal settlement or refusal releases the reservation and retains request history.
Constraints
General Jazz AI replies bypass the Platform request boundary; that gap remains a finding.
Intent sources
services-platform:docs/proposals/llm-observability/11-decisions.md#D-5

Controls

42 controls apply, from the corpus control catalogue.

TC-AI-001 TC-AI-002 TC-AI-003 TC-AI-004 TC-AI-006 TC-AI-007 TC-AVL-001 TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Business Rules

13 rules, 10 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01must prove
Proposed
An undeclared operation or a routing without a published model price is rejected before creating a request or reserving credits.
✓ The query generator's declared operation runs.✗ A feature naming an undeclared operation is refused with nothing recorded.
proved by ATS-PFM-LLM-001-01, ATS-PFM-LLM-001-14
validationserviceobserved
services-platform:modules/llm/services/catalog/catalog-authority.ts:resolveLlmOperation
02must prove
Proposed
Platform creates the request record before reserving credits or contacting the model, giving later recovery a record to inspect.
proved by ATS-PFM-LLM-001-02, ATS-PFM-LLM-001-13
invariantservicedocumented
services-platform:docs/llm.md#The order of the steps, which is the design
03must prove
Proposed
Settlement uses reported usage when available, charges the reservation estimate when an attempt succeeds without any reported usage, and releases the hold when no usage is spent; interruptions can leave unresolved accounting.
✓ A request whose model reported usage is charged that usage at the published rate.✗ A request to a model that never answered is charged nothing.
proved by ATS-PFM-LLM-001-03, ATS-PFM-LLM-001-12, ATS-PFM-LLM-001-15, TST-PFM-LLM-018, TST-PFM-LLM-020
calculationserviceobserved
services-platform:modules/llm/services/execution/run-operation.ts:settleInvocation
04must prove
Proposed
Normal state changes compare the current state with the expected state, while settlement can close any nonterminal request; settled and refused requests reject a second settlement.
proved by ATS-PFM-LLM-001-04, ATS-PFM-LLM-001-21, TST-PFM-LLM-061
lifecycleserviceobserved
services-platform:modules/llm/services/persistence/invocations.ts:markInvocationSettled
05must prove
Proposed
Request attribution uses the caller context and published application and feature routing; a service’s asserted beneficiary is retained without independent verification.
proved by ATS-PFM-LLM-001-05
invariantserviceobserved
services-platform:modules/llm/services/persistence/invocations.ts:createInvocation
06must prove
Proposed
Customer-relevant refusals use fixed codes and statuses: allowance and concurrency refusals are rate limits, disabled operations are conflicts, provider timeout, unavailability and refusal indicate temporary service failure, and depleted Rhythm provider credit is a server error.
proved by ATS-PFM-LLM-001-06, ATS-PFM-LLM-001-16, ATS-PFM-LLM-001-17, ATS-PFM-LLM-001-18, ATS-PFM-LLM-001-20, TST-PFM-LLM-020, TST-PFM-LLM-075
policyservice, apiobserved
services-platform:modules/llm/services/metering/llm-metering-errors.ts
07must prove
Proposed
Conversation budget endings return as outcomes for the consuming feature to interpret rather than throwing a metering error.
proved by ATS-PFM-LLM-001-07, ATS-PFM-LLM-001-11, TST-PFM-LLM-020
policyservicetest
services-platform:modules/llm/tests/integration/lifecycle/run-operation.integration.spec.js#returns rather than throwing
08must prove
Proposed
Provider failure messages are replaced with Rhythm wording that identifies the operation and request, allowing staff to locate the usage record.
proved by ATS-PFM-LLM-001-08
policyserviceobserved
services-platform:modules/llm/services/execution/run-operation.ts:providerFailure
09must prove
Proposed
Platform’s provider-boundary guard rejects extra SDK importers, direct provider-host calls and prohibited provider SDK imports during verification.
proved by ATS-PFM-LLM-001-09, ATS-PFM-LLM-001-19, TST-PFM-LLM-086
invariantservicetest
services-platform:tests/unit/llm-provider-boundary.spec.ts#refuses an import of the openai sdk even in the adapter
10must prove
Proposed
Absent model credentials produce a configuration refusal that is distinct from allowance and provider refusals.
proved by ATS-PFM-LLM-001-10, TST-PFM-LLM-063
validationservice, apitest
services-platform:modules/llm/tests/unit/runtime/anthropic-credentials.spec.ts#answers llm_not_configured in the body, so a console says "nobody configured this" and not "try again"
11
Proposed
The consuming feature receives and validates the model’s final answer; the runtime does not apply that answer as domain state.
origin: services-platform:docs/compliance/exceptions.md#EX-AI-001
policyservicedocumented
services-platform:docs/llm.md#What is deliberately not here
12
Proposed
Depleted Rhythm provider credit has an internal classification but the shared response mapper returns a generic server error without that code.
origin: services-platform:docs/debt/llm-server-error-code-not-in-body.md
policyapidocumented
services-platform:docs/llm.md#The code, which is the part a program reads
13
Proposed
Allowance refusals and provider refusals contribute to separate operational measures.
proved by ATS-PFM-LLM-001-22, TST-PFM-LLM-076
policyservicedocumented
services-platform:docs/llm.md#Metrics

Scenarios

IdGivenWhenThenProvenance
01A priced AI operation receives a request.The shared request boundary completes it.The record retains attribution and the reported charge; its reservation is released.test
services-platform:modules/llm/tests/integration/lifecycle/run-operation.integration.spec.js#records the invocation as settled on the actual usage
02The provider fails on every attempt.The retry policy is exhausted.The request returns an availability failure and releases its reservation without charging usage.test
services-platform:modules/llm/tests/integration/lifecycle/run-operation.integration.spec.js#charges nothing, because the provider never answered: there is no call to settle at an estimate

Edge Cases

IdGivenWhenThenProvenance
03The provider supplies no usage figures.Settlement uses the fallback estimate.The request records an estimated credit charge and an unknown money amount.test
services-platform:modules/llm/tests/integration/lifecycle/run-operation.integration.spec.js#reports no money figure, which would be a guess

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