Rhythm 2.0 Specifications

Appearance

CAP-PFM-LLM-005Publish AI operation definitions and historical prices

Markdown

CAP-PFM-LLM-005

Publish AI operation definitions and historical prices

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-LLM-02
Exercised by
FAS-PFM-LLM-02-01, FAS-PFM-LLM-02-02, FAS-PFM-LLM-02-03, FAS-PFM-LLM-02-04, FAS-PFM-LLM-02-05
Key concepts
CON-PFM-LLM-002
Actors
ACT-PFM-034, ACT-PFM-033, ACT-PFM-012
Related
CAP-PFM-LLM-001, CAP-PFM-LLM-002, CAP-PFM-LLM-010
Proved by
ATS-PFM-LLM-005

Implementation

Executable suites
TST-PFM-LLM-009, TST-PFM-LLM-011, TST-PFM-LLM-023, TST-PFM-LLM-040, TST-PFM-LLM-041, TST-PFM-LLM-042, TST-PFM-LLM-043, TST-PFM-LLM-055, TST-PFM-LLM-056, TST-PFM-LLM-058, TST-PFM-LLM-059, TST-PFM-LLM-060

KindCapabilityProduct areaPlatformModuleAI Requests, Usage and the Jazz AI TeammateRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Publish AI operation definitions and historical prices ​

Purpose ​

Make each operation’s model choices and cost calculations inspectable without rewriting past requests.

How It Works ​

Engineers declare an operation’s routing, prompt and budgets together with model rates. Publication validates the entire declaration set before appending changed versions. An unchanged deploy preserves existing histories. Reverting a declaration creates another historical version rather than erasing the intervening one. Requests retain the versions under which they run. Credit and money calculations use different rounding because they serve different purposes. An unknown usage dimension is surfaced without inventing its price. Rhythm staff can inspect the current catalog and recent versions, while engineers remain responsible for choosing accurate rates.

Relationships ​

The Formal Contract

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

Outcomes
Published declarations connect operations with priced models.Routing and price changes append historical versions.HQ readers can inspect current and earlier catalog versions.
Surfaces
jobapiconsole
Postconditions
Published versions reflect the deployed catalog declarations.

Controls

36 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-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-005 TC-CHG-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-IAM-003 TC-LOG-001 TC-LOG-005 TC-MON-001 TC-PI-001 TC-PI-003 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
hq.llm-usage.readapiglobal

Business Rules

10 rules, 7 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
The reservation is the rounded per-turn estimate multiplied by permitted turns and limited to the operation’s declared credit ceiling.
proved by ATS-PFM-LLM-005-01, ATS-PFM-LLM-005-10, TST-PFM-LLM-058
calculationserviceobserved
services-platform:modules/llm/catalog/pricing.ts
02must prove
Proposed
Publication rejects the whole catalog for unpriced routing, inconsistent timeouts, duplicate operations or rates, unknown applications, empty features, zero estimates or invalid prices, writing no versions.
proved by ATS-PFM-LLM-005-02, ATS-PFM-LLM-005-12, TST-PFM-LLM-023, TST-PFM-LLM-060
validationserviceobserved
services-platform:modules/llm/services/catalog/materialize-catalog.ts
03must prove
Proposed
An unchanged declaration adds no version, a changed declaration appends one, and reverting appends another version with the earlier content digest.
proved by ATS-PFM-LLM-002-12, ATS-PFM-LLM-005-03, ATS-PFM-LLM-005-14, ATS-PFM-LLM-005-16, TST-PFM-LLM-023, TST-PFM-LLM-042, TST-PFM-LLM-056
lifecycleservice, databaseobserved
services-platform:modules/llm/services/catalog/materialize-catalog.ts
04must prove
Proposed
Published routing and rate versions reject updates and deletions by both application and publishing roles.
proved by ATS-PFM-LLM-005-04, ATS-PFM-LLM-005-15, TST-PFM-LLM-011, TST-PFM-LLM-043
invariantdatabasetest
services-platform:modules/llm/tests/integration/db/llm-catalog-tables.integration.spec.js#refuses an update by the owner, who publishes the versions, so no deploy can rewrite one
05must prove
Proposed
A request retains its original rate version when prices change; only subsequent requests resolve the newer version.
proved by ATS-PFM-LLM-001-14, ATS-PFM-LLM-005-05, ATS-PFM-LLM-005-11, ATS-PFM-LLM-005-13, TST-PFM-LLM-040, TST-PFM-LLM-041
calculationservice, databasetest
services-platform:modules/llm/tests/integration/services/persistence/rate-versions.integration.spec.js#leaves the old version at the old price, because an invocation settled under it still names it
06must prove
Proposed
Usage costs are summed at per-million rates before one division, with credits rounded upward and cents rounded to nearest.
proved by ATS-PFM-LLM-005-06, ATS-PFM-LLM-005-09, TST-PFM-LLM-058
calculationserviceobserved
services-platform:modules/llm/catalog/pricing.ts
07
Proposed
One credit represents one hundredth of a cent, and model input, output, cache-read and cache-write units have declared credit and cent prices per million.
calculationservicedocumented
services-platform:docs/llm.md#Money
08must prove
Proposed
Unpriced usage dimensions contribute no charge and remain visible under their provider names for later pricing decisions.
proved by ATS-PFM-LLM-005-07, ATS-PFM-LLM-005-17, TST-PFM-LLM-055, TST-PFM-LLM-058, TST-PFM-LLM-059
calculationservicetest
services-platform:modules/llm/tests/unit/catalog/classify-usage-dimensions.spec.ts#reports it as unpriced rather than filtering it out
09
Proposed
Engineers choose and deploy model prices; Rhythm does not reconcile those declarations with the provider’s actual bill.
policyservicedocumented
services-platform:docs/llm.md#What is declared, and what is published
10
Proposed
The HQ catalog and rates show each key’s current version and up to nineteen preceding versions.
proved by ATS-PFM-LLM-005-08, TST-PFM-LLM-009
policyapiobserved
services-platform:modules/llm/aws/api/llm-usage.routes.ts

Scenarios

IdGivenWhenThenProvenance
01An engineer changes an operation’s prompt version.Catalog publication runs.A new routing version becomes current without a new unchanged price version.test
services-platform:modules/llm/tests/integration/services/catalog/materialize-catalog.integration.spec.js#leaves the new prompt version in force
02A declaration names an unpriced model.Publication validates the catalog.Validation reports the operation and issue without changing the active catalog.test
services-platform:modules/llm/tests/integration/services/catalog/materialize-catalog.integration.spec.js#names the issue and the operation, so the failed deploy says what to fix

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