---
id: CON-PFM-LLM-003
name: AI Allowance
feature: FEAT-PFM-LLM-03
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 allowance is the organization’s monthly credit budget and the limits, temporary capacity and
  corrections that determine how it can use that budget.
owned_by: MOD-PFM-LLM
synonyms:
  - AI credits
  - monthly allowance
not_to_be_confused_with:
  - 'Application access, which does not follow from available credits.'
  - The provider account balance used by Rhythm.
facets:
  - name: Monthly period
    meaning: 'A local-calendar month retains its base allowance, charged credits and running holds.'
    used_for: Evaluating admission and keeping separate monthly accounts.
  - name: Credit
    meaning: Credits measure customer allowance usage at one hundredth of a cent of list price.
    used_for: Reporting capacity without disclosing money.
  - name: Hold
    meaning: >-
      A calculated reservation protects admission capacity until settlement, without guaranteeing a worst-case
      measured charge.
    used_for: Keeping simultaneous admission within available capacity.
  - name: Thresholds and notices
    meaning: Once-per-month crossings record charged usage at 80% and 100% and support administrator emails.
    used_for: Tracking warnings and delivery outcomes.
  - name: Limits
    meaning: 'Organization controls set the AI switch, recurring allowance, disabled operations and concurrency cap.'
    used_for: Changing subsequent admission with an accountable reason.
  - name: Extra capacity
    meaning: Time-limited credits or operation exemptions apply until expiry or revocation.
    used_for: Providing temporary relief without rewriting the base configuration.
  - name: Correction
    meaning: A signed adjustment records a change to a month’s charged totals and its reason.
    used_for: Correcting accounting through a retained record.
  - name: Ceilings
    meaning: 'Global ceilings cap effective allowance, grant amount and grant duration.'
    used_for: Constraining management authority.
  - name: Status
    meaning: 'Live committed usage and access switches produce within, warned, stopped or disabled status.'
    used_for: Showing allowance pressure separately from notice delivery.
relationships:
  - to: CON-PFM-LLM-001
    statement: Admission reserves credit capacity before dispatch; settlement records the resulting charge.
    provenance: observed
    source: 'services-platform:modules/llm/services/persistence/allowance-periods.ts:authorizeCredits'
  - to: CON-PFM-LLM-004
    statement: Live allowance positions supply the organization status shown in reports.
    provenance: observed
    source: 'services-platform:modules/llm/services/usage-reports/usage-status.ts'
lifecycle:
  - state: Within
    meaning: Committed credits remain below the warning boundary.
    how_it_changes: 'Reservations, charges, grants and corrections can change the position.'
  - state: Warned
    meaning: Committed credits reach the warning band; notice delivery depends on charged-usage crossings.
    how_it_changes: Further activity or control changes move the position.
  - state: Hard stopped
    meaning: 'Committed credits reach the allowance, so ordinary new admission stops.'
    how_it_changes: 'A grant, limit increase, correction or reset can restore capacity.'
  - state: Disabled
    meaning: Organization or AI controls prevent use.
    how_it_changes: An authorized control change restores enabled status.
acted_on_by:
  - CAP-PFM-LLM-007
  - CAP-PFM-LLM-008
  - CAP-PFM-LLM-009
  - CAP-PFM-LLM-010
  - CAP-PFM-LLM-011
  - CAP-PFM-LLM-013
  - CAP-PFM-LLM-014
  - CAP-PFM-LLM-015
  - CAP-PFM-LLM-017
visible_to:
  - ACT-PFM-007
  - ACT-PFM-033
  - ACT-PFM-004
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/llm.md (Money, Limits, Overrides,
    Adjustments, Notices); docs/proposals/llm-observability/11-decisions.md (D-3, D-4, D-6, D-7);
    docs/milestones/plans/PLAT-M1-plan.md; modules/llm/llm.settings.ts; db/llm-allowance-periods.table.ts,
    llm-tenant-limits.table.ts, llm-allowance-overrides.table.ts, llm-allowance-adjustments.table.ts,
    llm-usage-threshold-crossings.table.ts.
  - 'react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/console/hq/tenant-ai-usage-card.tsx.'
supersedes: []
---

# AI Allowance

## What It Is

The AI allowance is the organization’s shared account for model work during a month of its own calendar. Its base is either the configured allowance or the Platform default. The first relevant request creates the period when needed, so a new month does not require a scheduled reset of the previous account. Earlier periods remain available for review and correction.

The account separates charged credits from credits held for work still running. Before admitting a request, the ledger checks both amounts together with the new reservation and any temporary capacity active at that moment. This lets concurrent requests make one atomic affordability decision. Completing a request replaces its hold with the settled charge. The reservation is calculated from estimates and a declared ceiling; it is not an absolute promise about final measured spend.

## What It Is Not

An allowance is not an application licence, a feature permission or Rhythm’s supplier credit balance. A person still needs the consuming feature’s authority. Exhausting the customer allowance differs from the supplier saying that Rhythm’s own account has no balance. A warned dashboard status also does not prove that a warning email has been delivered: status counts committed usage, while crossings count charged usage.

## How It Is Used

Customer administrators need allowance figures to anticipate interruptions and understand renewal. Support staff inspect them when a request is refused. Authorized Rhythm managers can change recurring limits, grant temporary relief or correct charges, with reasons retained in the audit trail. Lowering a limit changes subsequent admission but preserves already running work. Good support compares the refused request’s estimate with remaining capacity rather than assuming that any positive balance admits another request.

## Its Facets

**Monthly period.** The local month keeps base, charged and held amounts together while preserving prior months.

**Credit.** The customer sees a capacity unit rather than the internal dollar cost of model usage.

**Hold.** A reservation prevents another request from spending capacity already committed to running work.

**Thresholds and notices.** Crossings record charged usage once at each threshold and support tracked, bounded delivery attempts.

**Limits.** Recurring allowance, switches and concurrency settings control new work and distinguish defaults from explicit configuration.

**Extra capacity.** Grants have start and end instants and can be revoked. Operation exemptions and extra credits solve different admission restrictions.

**Correction.** Signed changes retain their own record rather than rewriting the original request charge.

**Ceilings.** Global bounds constrain effective capacity, individual grants and their windows even for authorized managers.

**Status.** Live balance and access state supply the displayed classification independently of past crossings.

## How It Relates

AI operations determine reservations and operation identities. AI requests make the holds and settlements that move the account. AI usage reads its current position and historical periods, while the security audit store retains management attribution and reasons. The notification infrastructure delivers administrator emails; the allowance does not itself define every future notification responsibility.

## What It Could Become

The product should choose one coherent meaning of allowance exhaustion across admission, dashboard status and pause notices. It should also confirm the interim Administrator-role recipient policy while responsibilities are being developed. Refunds to missing periods, interrupted settlement and replay of management writes need stronger handling before staff rely on the disabled console controls. These decisions should preserve separate records for limits, grants and corrections.