---
id: MOD-PFM-LLM
title: 'AI Requests, Usage and the Jazz AI Teammate'
product_area: platform
module: llm
revision: 2
status: draft
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
repositories:
  - name: services-platform
    paths:
      - modules/llm
      - 'aws/platform.service.ts (LLM_USAGE_PERMISSIONS, HQ_LLM_USAGE_PERMISSIONS, hqReaderPolicy)'
      - docs/llm.md
      - docs/llm/llm-foundation-and-generate-query.md
      - docs/milestones/PLAT-M1-ai-usage-metered-and-visible.md
      - docs/milestones/plans/PLAT-M1-plan.md
      - docs/milestones/PLAT-M2-ai-usage-hq-controls.md
      - docs/milestones/PLAT-M3-ai-usage-organization-page.md
      - docs/milestones/PLAT-M4-ai-usage-early-warning.md
      - docs/proposals/llm-observability (cited by the records)
      - docs/debt/llm-*.md
      - docs/compliance/exceptions.md (EX-AI-001 to EX-AI-003)
      - tests/unit/llm-provider-boundary.spec.ts
      - tests/unit/llm-stub-mode-config.spec.ts
  - name: react-console
    paths:
      - 'app/(console)/console/[tenantId]/agent'
      - app/api/agent
      - components/agent
      - components/console/agent-chat.tsx
      - lib/agent
      - app/(console)/hq/aiUsage
      - components/console/hq/ai-usage
      - components/console/hq/tenant-ai-usage-card.tsx
      - components/console/hq/tenant-ai-usage-section.tsx
      - lib/hq/ai-usage*.ts
      - e2e/mock/hq-ai-usage.mock.spec.ts
      - e2e/dev/hq-ai-usage.dev.spec.ts
owns:
  - 'Model request and attempt history, admission refusals and captured evidence.'
  - AI task execution records.
  - Operation routing declarations and historical model prices.
  - 'Monthly allowance periods, threshold crossings and notice state.'
  - 'Organization AI limits, capacity grants, exemptions and signed corrections.'
  - 'Daily usage aggregates, reporting views and rebuild progress.'
  - AI-control entries written through the security audit service.
  - Prototype Jazz AI projects and conversations held in the console.
does_not_own:
  - record: 'Query interpretation, query drafts, datasets and recipes.'
    owner: MOD-PFM-QRY
  - record: 'Staff grants, roles, permission evaluation and the audit store.'
    owner: MOD-PFM-SEC
  - record: Organization records and the HQ page hosting AI Usage.
    owner: MOD-PFM-SEC
  - record: Email transport and future notification channels.
    owner: MOD-PFM-NOT
  - record: Responsibilities and attention workflows.
    owner: MOD-PFM-ELG
  - record: Cross-service workspace deletion orchestration.
    owner: MOD-PFM-TNL
  - record: Licensing and application access.
    owner: MOD-PFM-OPS
  - record: Record directories assisted by Jazz AI.
    owner: MOD-PFM-MTD and the owning record modules
hosted_screens:
  - route: '/console/{tenantId}/agent'
    purpose: 'Jazz AI conversations, projects and chat.'
  - route: (every console page) Ask Jazz AI panel
    purpose: Contextual Jazz AI assistance beside registered queries and directories.
  - route: /hq/aiUsage
    purpose: Usage across organizations.
  - route: /hq/aiUsage/requests
    purpose: One organization’s request directory.
  - route: '/hq/aiUsage/requests/{tenantId}/{invocationId}'
    purpose: 'Request metadata, explanation and capture state.'
  - route: '/hq/aiUsage/executions/{tenantId}/{executionId}'
    purpose: Task execution metadata and totals.
  - route: '/hq/tenants/{id} (AI Usage card)'
    purpose: Organization usage and control history.
supersedes: []
evidence:
  - >-
    The examination report inventories Platform and console operations separately and distinguishes source
    coverage from behavioral acceptance. Every must-prove rule has an acceptance scenario or an identified
    finding; proposed scenarios do not establish approval.
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: the module, its guide and README, the four
    AI usage milestone records and the PLAT-M1 plan, the proposal chapters they cite (11-decisions,
    12-milestone-plan, README), the LLM debt notes and compliance exceptions. Code of other modules was read
    only to name a dependency.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: the Jazz AI page, panel, components, store and
    route handlers; the Rhythm HQ AI Usage pages, card, request and execution details, their library and
    specs. No acceptance inventory or journey exists for this area.
  - >-
    Testing back-fill registers the pinned suites and separates proposed experiments from executable evidence;
    unexecuted suites retain not-run results and unverified conformance.
coverage_catalog: >
  ### Coverage against the code at the pinned commit


  | Measure | Covered | Ratio |

  |---|---|---|

  | HTTP operations declared in `aws/api/llm-usage.routes.ts` (the health route from the shared factory is
  infrastructure) | 28 of 28 | 28/28 |

  | Tables (`db/*.table.ts`) and reporting views (`db/*.view.ts`), each named in a capability's evidence | 14
  of 14 | 14/14 |

  | Permission keys of the LLM usage groups in `aws/platform.service.ts` | 4 of 4 | 4/4 |

  | End-to-end specification files (`tests/e2e`) | 5 of 5 | 5/5 |

  | Integration specification files (`tests/integration`) | 42 of 42 | 42/42 |

  | Unit specification files of the module (`tests/unit`), plus the two repository-level guards | 34 of 34, 2
  of 2 | 36/36 |

  | Schedules, queues and buckets (the hourly reconciliation schedule and its dead-letter queue; the evidence
  bucket); no state machine | 3 of 3 | 3/3 |

  | Console pages and hosted cards in scope | 6 of 6 | 6/6 |

  | Acceptance inventory entries for this area | none exist | n/a |


  ### Operations by capability


  | Operation | Capability |

  |---|---|

  | `createHqTenantLlmUsageAdjustment` | `CAP-PFM-LLM-015` |

  | `explainHqTenantLlmUsageInvocation` | `CAP-PFM-LLM-012` |

  | `getHqLlmUsageBreakdown` | `CAP-PFM-LLM-010` |

  | `getHqLlmUsageCatalog` | `CAP-PFM-LLM-005` |

  | `getHqLlmUsageRates` | `CAP-PFM-LLM-005` |

  | `getHqLlmUsageSummary` | `CAP-PFM-LLM-010` |

  | `getHqLlmUsageTrend` | `CAP-PFM-LLM-010` |

  | `getHqTenantLlmUsage` | `CAP-PFM-LLM-011` |

  | `getHqTenantLlmUsageExecution` | `CAP-PFM-LLM-011` |

  | `getHqTenantLlmUsageInvocation` | `CAP-PFM-LLM-011` |

  | `getHqTenantLlmUsageInvocationEvidence` | `CAP-PFM-LLM-016` |

  | `getHqTenantLlmUsageLimits` | `CAP-PFM-LLM-011` |

  | `getLlmUsageSummary` | `CAP-PFM-LLM-017` |

  | `grantHqTenantLlmUsageOverride` | `CAP-PFM-LLM-014` |

  | `listHqLlmUsageExecutions` | `CAP-PFM-LLM-010` |

  | `listHqLlmUsageTenants` | `CAP-PFM-LLM-010` |

  | `listHqTenantLlmUsageAdjustments` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsageAudit` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsageCrossings` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsageExecutions` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsageInvocations` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsageOverrides` | `CAP-PFM-LLM-011` |

  | `listHqTenantLlmUsagePeriods` | `CAP-PFM-LLM-011` |

  | `listLlmUsageFeatures` | `CAP-PFM-LLM-017` |

  | `previewHqTenantLlmUsageLimits` | `CAP-PFM-LLM-013` |

  | `previewHqTenantLlmUsageOverride` | `CAP-PFM-LLM-014` |

  | `putHqTenantLlmUsageLimits` | `CAP-PFM-LLM-013` |

  | `revokeHqTenantLlmUsageOverride` | `CAP-PFM-LLM-014` |


  ### Tables by capability


  | Table file | Capabilities |

  |---|---|

  | `llm-invocations.table.ts` | `CAP-PFM-LLM-001`, `CAP-PFM-LLM-004` |

  | `llm-invocation-attempts.table.ts` | `CAP-PFM-LLM-002` |

  | `llm-executions.table.ts` | `CAP-PFM-LLM-003` |

  | `llm-operation-routing-versions.table.ts` | `CAP-PFM-LLM-005` |

  | `llm-model-rate-versions.table.ts` | `CAP-PFM-LLM-005` |

  | `llm-allowance-periods.table.ts` | `CAP-PFM-LLM-007` |

  | `llm-usage-threshold-crossings.table.ts` | `CAP-PFM-LLM-008` |

  | `llm-usage-daily.table.ts` | `CAP-PFM-LLM-010` |

  | `llm-rollup-watermarks.table.ts` | `CAP-PFM-LLM-010` |

  | `llm-tenant-limits.table.ts` | `CAP-PFM-LLM-013` |

  | `llm-allowance-overrides.table.ts` | `CAP-PFM-LLM-014` |

  | `llm-allowance-adjustments.table.ts` | `CAP-PFM-LLM-015` |

  | `llm-usage-daily-query.view.ts (view)` | `CAP-PFM-LLM-010` |

  | `llm-invocations-query.view.ts (view)` | `CAP-PFM-LLM-017` |


  ### Permission keys by capability


  | Permission key | Capabilities |

  |---|---|

  | `hq.llm-usage.read` | `CAP-PFM-LLM-005`, `CAP-PFM-LLM-010`, `CAP-PFM-LLM-011`, `CAP-PFM-LLM-012` |

  | `hq.llm-usage.manage` | `CAP-PFM-LLM-013`, `CAP-PFM-LLM-014`, `CAP-PFM-LLM-015` |

  | `hq.llm-usage.read-evidence` | `CAP-PFM-LLM-016` |

  | `platform.llm-usage.read` | `CAP-PFM-LLM-017` |


  ### Specification files by capability


  | Spec file (under `modules/llm/tests/`) | Capabilities |

  |---|---|

  | `e2e/allowance-warning.e2e.spec.js` | `CAP-PFM-LLM-007`, `CAP-PFM-LLM-008` |

  | `e2e/llm-adjustments-and-organization.e2e.spec.js` | `CAP-PFM-LLM-012`, `CAP-PFM-LLM-015`,
  `CAP-PFM-LLM-017` |

  | `e2e/llm-limits.e2e.spec.js` | `CAP-PFM-LLM-013` |

  | `e2e/llm-overrides.e2e.spec.js` | `CAP-PFM-LLM-014` |

  | `e2e/llm-usage.e2e.spec.js` | `CAP-PFM-LLM-005`, `CAP-PFM-LLM-010`, `CAP-PFM-LLM-011` |

  | `integration/db/llm-allowance-overrides.table.integration.spec.js` | `CAP-PFM-LLM-014` |

  | `integration/db/llm-catalog-tables.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/db/llm-executions.table.integration.spec.js` | `CAP-PFM-LLM-003` |

  | `integration/db/llm-invocations-query.view.integration.spec.js` | `CAP-PFM-LLM-017` |

  | `integration/db/llm-invocations.table.integration.spec.js` | `CAP-PFM-LLM-001` |

  | `integration/db/llm-overrides-migration.integration.spec.js` | `CAP-PFM-LLM-014` |

  | `integration/db/llm-tenant-limits.table.integration.spec.js` | `CAP-PFM-LLM-013` |

  | `integration/db/llm-usage-daily.table.integration.spec.js` | `CAP-PFM-LLM-010` |

  | `integration/lifecycle/executions.integration.spec.js` | `CAP-PFM-LLM-002`, `CAP-PFM-LLM-003`,
  `CAP-PFM-LLM-007` |

  | `integration/lifecycle/llm-ledger-concurrency.integration.spec.js` | `CAP-PFM-LLM-007` |

  | `integration/lifecycle/run-operation.integration.spec.js` | `CAP-PFM-LLM-001`, `CAP-PFM-LLM-002`,
  `CAP-PFM-LLM-004`, `CAP-PFM-LLM-007` |

  | `integration/lifecycle/tenant-limits.integration.spec.js` | `CAP-PFM-LLM-013` |

  | `integration/services/adjustments/adjust-allowance.integration.spec.js` | `CAP-PFM-LLM-015` |

  | `integration/services/catalog/materialize-catalog.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/services/evidence/evidence-access.integration.spec.js` | `CAP-PFM-LLM-016` |

  | `integration/services/explain/explain-invocation.integration.spec.js` | `CAP-PFM-LLM-012` |

  | `integration/services/limits/tenant-limits.integration.spec.js` | `CAP-PFM-LLM-013` |

  | `integration/services/maintenance/tenant-participant.integration.spec.js` | `CAP-PFM-LLM-004` |

  | `integration/services/notices/threshold-notice.integration.spec.js` | `CAP-PFM-LLM-008` |

  | `integration/services/overrides/allowance-overrides.integration.spec.js` | `CAP-PFM-LLM-011`,
  `CAP-PFM-LLM-014` |

  | `integration/services/persistence/allowance-periods.integration.spec.js` | `CAP-PFM-LLM-007`,
  `CAP-PFM-LLM-008` |

  | `integration/services/persistence/allowance-periods.queries.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/persistence/executions.integration.spec.js` | `CAP-PFM-LLM-003` |

  | `integration/services/persistence/executions.queries.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/persistence/invocations.integration.spec.js` | `CAP-PFM-LLM-001`, `CAP-PFM-LLM-004`
  |

  | `integration/services/persistence/invocations.queries.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/persistence/limits.integration.spec.js` | `CAP-PFM-LLM-013` |

  | `integration/services/persistence/limits.queries.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/persistence/overrides.integration.spec.js` | `CAP-PFM-LLM-014` |

  | `integration/services/persistence/overrides.queries.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/persistence/rate-versions.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/services/persistence/rate-versions.queries.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/services/persistence/routing-versions.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/services/persistence/routing-versions.queries.integration.spec.js` | `CAP-PFM-LLM-005` |

  | `integration/services/persistence/usage-rollups.queries.integration.spec.js` | `CAP-PFM-LLM-010` |

  | `integration/services/reconciliation/llm-execution-sweep.integration.spec.js` | `CAP-PFM-LLM-009` |

  | `integration/services/reconciliation/llm-settlement-sweep.integration.spec.js` | `CAP-PFM-LLM-009` |

  | `integration/services/reconciliation/rollup-settled-invocations.integration.spec.js` | `CAP-PFM-LLM-010` |

  | `integration/services/usage-reports/execution-leaders.integration.spec.js` | `CAP-PFM-LLM-010` |

  | `integration/services/usage-reports/platform-usage.integration.spec.js` | `CAP-PFM-LLM-010` |

  | `integration/services/usage-reports/tenant-usage.integration.spec.js` | `CAP-PFM-LLM-011` |

  | `integration/services/usage/organization-usage.integration.spec.js` | `CAP-PFM-LLM-017` |

  | `unit/aws/api/llm-usage-api-mapper.spec.ts` | `CAP-PFM-LLM-011` |

  | `unit/aws/api/llm-usage-limits-api.spec.ts` | `CAP-PFM-LLM-013` |

  | `unit/aws/api/llm-usage-permissions.spec.ts` | `CAP-PFM-LLM-010`, `CAP-PFM-LLM-016`, `CAP-PFM-LLM-017` |

  | `unit/catalog/classify-usage-dimensions.spec.ts` | `CAP-PFM-LLM-005` |

  | `unit/catalog/digest-declarations.spec.ts` | `CAP-PFM-LLM-005` |

  | `unit/catalog/llm-executions.spec.ts` | `CAP-PFM-LLM-003` |

  | `unit/catalog/pricing.spec.ts` | `CAP-PFM-LLM-005` |

  | `unit/catalog/rate-conversions.spec.ts` | `CAP-PFM-LLM-005` |

  | `unit/catalog/validate-catalog-declarations.spec.ts` | `CAP-PFM-LLM-005` |

  | `unit/db/invocation-transitions.spec.ts` | `CAP-PFM-LLM-001` |

  | `unit/llm-settings.spec.ts` | `CAP-PFM-LLM-007` |

  | `unit/runtime/anthropic-credentials.spec.ts` | `CAP-PFM-LLM-001`, `CAP-PFM-LLM-006` |

  | `unit/runtime/anthropic-provider.spec.ts` | `CAP-PFM-LLM-002`, `CAP-PFM-LLM-006` |

  | `unit/runtime/execute-with-llm-retry.spec.ts` | `CAP-PFM-LLM-002` |

  | `unit/runtime/llm-mode.spec.ts` | `CAP-PFM-LLM-006` |

  | `unit/runtime/retry-policy.spec.ts` | `CAP-PFM-LLM-002` |

  | `unit/runtime/run-tool-loop.spec.ts` | `CAP-PFM-LLM-002` |

  | `unit/runtime/stub-provider.spec.ts` | `CAP-PFM-LLM-006` |

  | `unit/services/adjustments/adjustment-request.spec.ts` | `CAP-PFM-LLM-015` |

  | `unit/services/allowance-overrides.spec.ts` | `CAP-PFM-LLM-014` |

  | `unit/services/evidence-redaction.spec.ts` | `CAP-PFM-LLM-004` |

  | `unit/services/evidence/evidence-access.spec.ts` | `CAP-PFM-LLM-016` |

  | `unit/services/explain/explain.spec.ts` | `CAP-PFM-LLM-012` |

  | `unit/services/llm-metering-errors.spec.ts` | `CAP-PFM-LLM-001` |

  | `unit/services/llm-metrics.spec.ts` | `CAP-PFM-LLM-001` |

  | `unit/services/llm-operation-disabled.spec.ts` | `CAP-PFM-LLM-013` |

  | `unit/services/refusal-snapshot.spec.ts` | `CAP-PFM-LLM-007` |

  | `unit/services/tenant-limits.spec.ts` | `CAP-PFM-LLM-013` |

  | `unit/services/threshold-notice.spec.ts` | `CAP-PFM-LLM-008` |

  | `unit/services/usage-reports/usage-status.spec.ts` | `CAP-PFM-LLM-010` |

  | `unit/services/usage-reports/usage-windows.spec.ts` | `CAP-PFM-LLM-010` |

  | `unit/services/usage/organization-usage.spec.ts` | `CAP-PFM-LLM-017` |

  | `unit/services/usage/usage-features.spec.ts` | `CAP-PFM-LLM-017` |

  | `unit/services/usage/usage-sentences.spec.ts` | `CAP-PFM-LLM-018` |

  | `tests/unit/llm-provider-boundary.spec.ts` (repository level) | `CAP-PFM-LLM-001` |

  | `tests/unit/llm-stub-mode-config.spec.ts` (repository level) | `CAP-PFM-LLM-006` |


  ### Console screens by capability


  | Route | Capabilities |

  |---|---|

  | `/console/{tenantId}/agent` | `CAP-PFM-LLM-019`, `CAP-PFM-LLM-020` |

  | `/hq/aiUsage` | `CAP-PFM-LLM-010` |

  | `/hq/aiUsage/requests` | `CAP-PFM-LLM-011` |

  | `/hq/aiUsage/requests/{tenantId}/{invocationId}` | `CAP-PFM-LLM-011`, `CAP-PFM-LLM-012`, `CAP-PFM-LLM-016`
  |

  | `/hq/aiUsage/executions/{tenantId}/{executionId}` | `CAP-PFM-LLM-011` |

  | `/hq/tenants/{id} (AI Usage card)` | `CAP-PFM-LLM-011`, `CAP-PFM-LLM-013`, `CAP-PFM-LLM-014`,
  `CAP-PFM-LLM-015` |


  ### Console conversation operations


  | Source route | Methods | Capability |

  |---|---|---|

  | `app/api/agent/projects/route.ts` | GET, POST | `CAP-PFM-LLM-019` |

  | `app/api/agent/projects/[id]/route.ts` | PATCH, DELETE | `CAP-PFM-LLM-019` |

  | `app/api/agent/conversations/route.ts` | GET, POST | `CAP-PFM-LLM-019`, `CAP-PFM-LLM-020` |

  | `app/api/agent/conversations/[id]/route.ts` | GET, PATCH, DELETE | `CAP-PFM-LLM-019` |

  | `app/api/agent/conversations/[id]/messages/route.ts` | POST | `CAP-PFM-LLM-019`, `CAP-PFM-LLM-020` |


  The console contributes ten additional method-and-route operations. The Platform integration inventory
  contains forty-two specification files and two support files; support files are not tests.
testing_tree:
  planning:
    acceptance:
      - id: FAS-PFM-LLM-01
        path: planning/acceptance/FAS-PFM-LLM-01-metered-ai-requests.md
      - id: FAS-PFM-LLM-02
        path: planning/acceptance/FAS-PFM-LLM-02-ai-catalog-and-pricing.md
      - id: FAS-PFM-LLM-03
        path: planning/acceptance/FAS-PFM-LLM-03-monthly-ai-allowance-and-notices.md
      - id: FAS-PFM-LLM-04
        path: planning/acceptance/FAS-PFM-LLM-04-rhythm-hq-ai-usage-oversight.md
      - id: FAS-PFM-LLM-05
        path: planning/acceptance/FAS-PFM-LLM-05-rhythm-hq-ai-controls.md
      - id: FAS-PFM-LLM-06
        path: planning/acceptance/FAS-PFM-LLM-06-the-organization-s-own-ai-usage.md
      - id: FAS-PFM-LLM-07
        path: planning/acceptance/FAS-PFM-LLM-07-jazz-ai-the-ai-teammate.md
  design:
    tests:
      - id: ATS-PFM-LLM-001
        path: design/tests/ATS-PFM-LLM-001-make-every-ai-request-through-one-metered-path.md
      - id: ATS-PFM-LLM-002
        path: design/tests/ATS-PFM-LLM-002-keep-an-ai-conversation-within-its-limits.md
      - id: ATS-PFM-LLM-003
        path: design/tests/ATS-PFM-LLM-003-account-for-a-multi-step-ai-task-as-one-execution.md
      - id: ATS-PFM-LLM-004
        path: design/tests/ATS-PFM-LLM-004-keep-redacted-evidence-of-every-ai-request.md
      - id: ATS-PFM-LLM-005
        path: design/tests/ATS-PFM-LLM-005-declare-and-publish-ai-operations-and-their-prices.md
      - id: ATS-PFM-LLM-006
        path: design/tests/ATS-PFM-LLM-006-prove-ai-features-without-spending.md
      - id: ATS-PFM-LLM-007
        path: design/tests/ATS-PFM-LLM-007-hold-each-organization-to-its-monthly-ai-allowance.md
      - id: ATS-PFM-LLM-008
        path: design/tests/ATS-PFM-LLM-008-warn-an-organization-s-administrators-at-80-and-100.md
      - id: ATS-PFM-LLM-009
        path: design/tests/ATS-PFM-LLM-009-recover-what-an-interrupted-ai-request-left-behind.md
      - id: ATS-PFM-LLM-010
        path: design/tests/ATS-PFM-LLM-010-see-ai-usage-and-spend-across-every-organization.md
      - id: ATS-PFM-LLM-011
        path: design/tests/ATS-PFM-LLM-011-inspect-one-organization-s-ai-usage-and-requests.md
      - id: ATS-PFM-LLM-012
        path: design/tests/ATS-PFM-LLM-012-explain-why-an-ai-request-was-refused-or-failed.md
      - id: ATS-PFM-LLM-013
        path: design/tests/ATS-PFM-LLM-013-set-what-ai-an-organization-may-use-and-how-much.md
      - id: ATS-PFM-LLM-014
        path: design/tests/ATS-PFM-LLM-014-grant-and-revoke-temporary-ai-capacity.md
      - id: ATS-PFM-LLM-015
        path: design/tests/ATS-PFM-LLM-015-correct-what-an-organization-was-charged-for-ai.md
      - id: ATS-PFM-LLM-016
        path: design/tests/ATS-PFM-LLM-016-read-a-captured-prompt-or-response-under-an-access-grant.md
      - id: ATS-PFM-LLM-017
        path: design/tests/ATS-PFM-LLM-017-let-an-organization-s-administrators-see-their-own-ai.md
      - id: ATS-PFM-LLM-018
        path: design/tests/ATS-PFM-LLM-018-tell-a-person-why-an-ai-feature-refused-them.md
      - id: ATS-PFM-LLM-019
        path: design/tests/ATS-PFM-LLM-019-converse-with-jazz-ai-and-keep-conversations-in-projects.md
      - id: ATS-PFM-LLM-020
        path: design/tests/ATS-PFM-LLM-020-change-a-query-or-a-directory-s-filters-by-asking-jazz.md
  implementation:
    tests:
      - id: TST-PFM-LLM-001
        path: implementation/tests/TST-PFM-LLM-001-e2e-dev-hq-ai-usage-dev-spec.md
      - id: TST-PFM-LLM-002
        path: implementation/tests/TST-PFM-LLM-002-e2e-mock-hq-ai-usage-mock-spec.md
      - id: TST-PFM-LLM-003
        path: implementation/tests/TST-PFM-LLM-003-lib-hq-ai-usage-format-test.md
      - id: TST-PFM-LLM-004
        path: implementation/tests/TST-PFM-LLM-004-lib-hq-ai-usage-test.md
      - id: TST-PFM-LLM-005
        path: implementation/tests/TST-PFM-LLM-005-e2e-allowance-warning-e2e-spec.md
      - id: TST-PFM-LLM-006
        path: implementation/tests/TST-PFM-LLM-006-e2e-llm-adjustments-and-organization-e2e-spec.md
      - id: TST-PFM-LLM-007
        path: implementation/tests/TST-PFM-LLM-007-e2e-llm-limits-e2e-spec.md
      - id: TST-PFM-LLM-008
        path: implementation/tests/TST-PFM-LLM-008-e2e-llm-overrides-e2e-spec.md
      - id: TST-PFM-LLM-009
        path: implementation/tests/TST-PFM-LLM-009-e2e-llm-usage-e2e-spec.md
      - id: TST-PFM-LLM-010
        path: implementation/tests/TST-PFM-LLM-010-integration-db-llm-allowance-overrides-table-integration.md
      - id: TST-PFM-LLM-011
        path: implementation/tests/TST-PFM-LLM-011-integration-db-llm-catalog-tables-integration-spec.md
      - id: TST-PFM-LLM-012
        path: implementation/tests/TST-PFM-LLM-012-integration-db-llm-executions-table-integration-spec.md
      - id: TST-PFM-LLM-013
        path: implementation/tests/TST-PFM-LLM-013-integration-db-llm-invocations-query-view-integration-spec.md
      - id: TST-PFM-LLM-014
        path: implementation/tests/TST-PFM-LLM-014-integration-db-llm-invocations-table-integration-spec.md
      - id: TST-PFM-LLM-015
        path: implementation/tests/TST-PFM-LLM-015-integration-db-llm-overrides-migration-integration-spec.md
      - id: TST-PFM-LLM-016
        path: implementation/tests/TST-PFM-LLM-016-integration-db-llm-tenant-limits-table-integration-spec.md
      - id: TST-PFM-LLM-017
        path: implementation/tests/TST-PFM-LLM-017-integration-db-llm-usage-daily-table-integration-spec.md
      - id: TST-PFM-LLM-018
        path: implementation/tests/TST-PFM-LLM-018-integration-lifecycle-executions-integration-spec.md
      - id: TST-PFM-LLM-019
        path: implementation/tests/TST-PFM-LLM-019-integration-lifecycle-llm-ledger-concurrency-integration.md
      - id: TST-PFM-LLM-020
        path: implementation/tests/TST-PFM-LLM-020-integration-lifecycle-run-operation-integration-spec.md
      - id: TST-PFM-LLM-021
        path: implementation/tests/TST-PFM-LLM-021-integration-lifecycle-tenant-limits-integration-spec.md
      - id: TST-PFM-LLM-022
        path: implementation/tests/TST-PFM-LLM-022-integration-services-adjustments-adjust-allowance.md
      - id: TST-PFM-LLM-023
        path: implementation/tests/TST-PFM-LLM-023-integration-services-catalog-materialize-catalog-integration.md
      - id: TST-PFM-LLM-024
        path: implementation/tests/TST-PFM-LLM-024-integration-services-evidence-evidence-access-integration.md
      - id: TST-PFM-LLM-025
        path: implementation/tests/TST-PFM-LLM-025-integration-services-explain-explain-invocation-integration.md
      - id: TST-PFM-LLM-026
        path: implementation/tests/TST-PFM-LLM-026-integration-services-limits-tenant-limits-integration-spec.md
      - id: TST-PFM-LLM-027
        path: implementation/tests/TST-PFM-LLM-027-integration-services-maintenance-tenant-participant.md
      - id: TST-PFM-LLM-028
        path: implementation/tests/TST-PFM-LLM-028-integration-services-notices-threshold-notice-integration.md
      - id: TST-PFM-LLM-029
        path: implementation/tests/TST-PFM-LLM-029-integration-services-overrides-allowance-overrides.md
      - id: TST-PFM-LLM-030
        path: implementation/tests/TST-PFM-LLM-030-integration-services-persistence-allowance-periods.md
      - id: TST-PFM-LLM-031
        path: implementation/tests/TST-PFM-LLM-031-integration-services-persistence-allowance-periods-queries.md
      - id: TST-PFM-LLM-032
        path: implementation/tests/TST-PFM-LLM-032-integration-services-persistence-executions-integration-spec.md
      - id: TST-PFM-LLM-033
        path: implementation/tests/TST-PFM-LLM-033-integration-services-persistence-executions-queries.md
      - id: TST-PFM-LLM-034
        path: implementation/tests/TST-PFM-LLM-034-integration-services-persistence-invocations-integration.md
      - id: TST-PFM-LLM-035
        path: implementation/tests/TST-PFM-LLM-035-integration-services-persistence-invocations-queries.md
      - id: TST-PFM-LLM-036
        path: implementation/tests/TST-PFM-LLM-036-integration-services-persistence-limits-integration-spec.md
      - id: TST-PFM-LLM-037
        path: implementation/tests/TST-PFM-LLM-037-integration-services-persistence-limits-queries-integration.md
      - id: TST-PFM-LLM-038
        path: implementation/tests/TST-PFM-LLM-038-integration-services-persistence-overrides-integration-spec.md
      - id: TST-PFM-LLM-039
        path: implementation/tests/TST-PFM-LLM-039-integration-services-persistence-overrides-queries.md
      - id: TST-PFM-LLM-040
        path: implementation/tests/TST-PFM-LLM-040-integration-services-persistence-rate-versions-integration.md
      - id: TST-PFM-LLM-041
        path: implementation/tests/TST-PFM-LLM-041-integration-services-persistence-rate-versions-queries.md
      - id: TST-PFM-LLM-042
        path: implementation/tests/TST-PFM-LLM-042-integration-services-persistence-routing-versions.md
      - id: TST-PFM-LLM-043
        path: implementation/tests/TST-PFM-LLM-043-integration-services-persistence-routing-versions-queries.md
      - id: TST-PFM-LLM-044
        path: implementation/tests/TST-PFM-LLM-044-integration-services-persistence-usage-rollups-queries.md
      - id: TST-PFM-LLM-045
        path: implementation/tests/TST-PFM-LLM-045-integration-services-reconciliation-llm-execution-sweep.md
      - id: TST-PFM-LLM-046
        path: implementation/tests/TST-PFM-LLM-046-integration-services-reconciliation-llm-settlement-sweep.md
      - id: TST-PFM-LLM-047
        path: implementation/tests/TST-PFM-LLM-047-integration-services-reconciliation-rollup-settled.md
      - id: TST-PFM-LLM-048
        path: implementation/tests/TST-PFM-LLM-048-integration-services-usage-reports-execution-leaders.md
      - id: TST-PFM-LLM-049
        path: implementation/tests/TST-PFM-LLM-049-integration-services-usage-reports-platform-usage.md
      - id: TST-PFM-LLM-050
        path: implementation/tests/TST-PFM-LLM-050-integration-services-usage-reports-tenant-usage-integration.md
      - id: TST-PFM-LLM-051
        path: implementation/tests/TST-PFM-LLM-051-integration-services-usage-organization-usage-integration.md
      - id: TST-PFM-LLM-052
        path: implementation/tests/TST-PFM-LLM-052-unit-aws-api-llm-usage-api-mapper-spec.md
      - id: TST-PFM-LLM-053
        path: implementation/tests/TST-PFM-LLM-053-unit-aws-api-llm-usage-limits-api-spec.md
      - id: TST-PFM-LLM-054
        path: implementation/tests/TST-PFM-LLM-054-unit-aws-api-llm-usage-permissions-spec.md
      - id: TST-PFM-LLM-055
        path: implementation/tests/TST-PFM-LLM-055-unit-catalog-classify-usage-dimensions-spec.md
      - id: TST-PFM-LLM-056
        path: implementation/tests/TST-PFM-LLM-056-unit-catalog-digest-declarations-spec.md
      - id: TST-PFM-LLM-057
        path: implementation/tests/TST-PFM-LLM-057-unit-catalog-llm-executions-spec.md
      - id: TST-PFM-LLM-058
        path: implementation/tests/TST-PFM-LLM-058-unit-catalog-pricing-spec.md
      - id: TST-PFM-LLM-059
        path: implementation/tests/TST-PFM-LLM-059-unit-catalog-rate-conversions-spec.md
      - id: TST-PFM-LLM-060
        path: implementation/tests/TST-PFM-LLM-060-unit-catalog-validate-catalog-declarations-spec.md
      - id: TST-PFM-LLM-061
        path: implementation/tests/TST-PFM-LLM-061-unit-db-invocation-transitions-spec.md
      - id: TST-PFM-LLM-062
        path: implementation/tests/TST-PFM-LLM-062-unit-llm-settings-spec.md
      - id: TST-PFM-LLM-063
        path: implementation/tests/TST-PFM-LLM-063-unit-runtime-anthropic-credentials-spec.md
      - id: TST-PFM-LLM-064
        path: implementation/tests/TST-PFM-LLM-064-unit-runtime-anthropic-provider-spec.md
      - id: TST-PFM-LLM-065
        path: implementation/tests/TST-PFM-LLM-065-unit-runtime-execute-with-llm-retry-spec.md
      - id: TST-PFM-LLM-066
        path: implementation/tests/TST-PFM-LLM-066-unit-runtime-llm-mode-spec.md
      - id: TST-PFM-LLM-067
        path: implementation/tests/TST-PFM-LLM-067-unit-runtime-retry-policy-spec.md
      - id: TST-PFM-LLM-068
        path: implementation/tests/TST-PFM-LLM-068-unit-runtime-run-tool-loop-spec.md
      - id: TST-PFM-LLM-069
        path: implementation/tests/TST-PFM-LLM-069-unit-runtime-stub-provider-spec.md
      - id: TST-PFM-LLM-070
        path: implementation/tests/TST-PFM-LLM-070-unit-services-adjustments-adjustment-request-spec.md
      - id: TST-PFM-LLM-071
        path: implementation/tests/TST-PFM-LLM-071-unit-services-allowance-overrides-spec.md
      - id: TST-PFM-LLM-072
        path: implementation/tests/TST-PFM-LLM-072-unit-services-evidence-redaction-spec.md
      - id: TST-PFM-LLM-073
        path: implementation/tests/TST-PFM-LLM-073-unit-services-evidence-evidence-access-spec.md
      - id: TST-PFM-LLM-074
        path: implementation/tests/TST-PFM-LLM-074-unit-services-explain-explain-spec.md
      - id: TST-PFM-LLM-075
        path: implementation/tests/TST-PFM-LLM-075-unit-services-llm-metering-errors-spec.md
      - id: TST-PFM-LLM-076
        path: implementation/tests/TST-PFM-LLM-076-unit-services-llm-metrics-spec.md
      - id: TST-PFM-LLM-077
        path: implementation/tests/TST-PFM-LLM-077-unit-services-llm-operation-disabled-spec.md
      - id: TST-PFM-LLM-078
        path: implementation/tests/TST-PFM-LLM-078-unit-services-refusal-snapshot-spec.md
      - id: TST-PFM-LLM-079
        path: implementation/tests/TST-PFM-LLM-079-unit-services-tenant-limits-spec.md
      - id: TST-PFM-LLM-080
        path: implementation/tests/TST-PFM-LLM-080-unit-services-threshold-notice-spec.md
      - id: TST-PFM-LLM-081
        path: implementation/tests/TST-PFM-LLM-081-unit-services-usage-reports-usage-status-spec.md
      - id: TST-PFM-LLM-082
        path: implementation/tests/TST-PFM-LLM-082-unit-services-usage-reports-usage-windows-spec.md
      - id: TST-PFM-LLM-083
        path: implementation/tests/TST-PFM-LLM-083-unit-services-usage-organization-usage-spec.md
      - id: TST-PFM-LLM-084
        path: implementation/tests/TST-PFM-LLM-084-unit-services-usage-usage-features-spec.md
      - id: TST-PFM-LLM-085
        path: implementation/tests/TST-PFM-LLM-085-unit-services-usage-usage-sentences-spec.md
      - id: TST-PFM-LLM-086
        path: implementation/tests/TST-PFM-LLM-086-unit-llm-provider-boundary-spec.md
      - id: TST-PFM-LLM-087
        path: implementation/tests/TST-PFM-LLM-087-unit-llm-stub-mode-config-spec.md
testing_counts:
  capability_specifications: 20
  feature_suites: 7
  executable_suites: 87
---

# AI Requests, Usage and the Jazz AI Teammate

## Purpose

This module brings together model requests, monthly capacity, usage inspection and AI control history. It also documents the Jazz AI console prototype. The specifications distinguish the shared Platform accounting path from prototype behavior that bypasses it.

## Boundary

The module owns AI accounting and control records, operation definitions, reporting and diagnostic evidence. Query work, staff authority, notification transport, licensing and workspace lifecycle remain responsibilities of their owning modules. The charter metadata identifies those dependencies and the screens hosted elsewhere.

## Features

| Feature | Grouping |
|---|---|
| `FEAT-PFM-LLM-01` | Metered AI Requests |
| `FEAT-PFM-LLM-02` | AI Catalog and Pricing |
| `FEAT-PFM-LLM-03` | Monthly AI Allowance and Notices |
| `FEAT-PFM-LLM-04` | Rhythm HQ AI Usage Oversight |
| `FEAT-PFM-LLM-05` | Rhythm HQ AI Controls |
| `FEAT-PFM-LLM-06` | Organization AI Usage |
| `FEAT-PFM-LLM-07` | Jazz AI Conversations |

## Capabilities

| Capability | Outcome | Product intent | Implementation evidence |
|---|---|---|---|
| `CAP-PFM-LLM-001` | Run AI requests with consistent attribution and accounting | proposed | observed |
| `CAP-PFM-LLM-002` | Bound AI conversations and handle recoverable failures | proposed | observed |
| `CAP-PFM-LLM-003` | Keep one account for a multi-request AI task | proposed | observed |
| `CAP-PFM-LLM-004` | Retain redacted AI evidence and remove it safely | proposed | observed |
| `CAP-PFM-LLM-005` | Publish AI operation definitions and historical prices | proposed | observed |
| `CAP-PFM-LLM-006` | Check AI behavior with scripted models and deliberate live runs | proposed | observed |
| `CAP-PFM-LLM-007` | Admit AI work against the organization’s monthly allowance | proposed | observed |
| `CAP-PFM-LLM-008` | Notify administrators at allowance thresholds | proposed | observed |
| `CAP-PFM-LLM-009` | Recover interrupted requests and identify accounting drift | proposed | observed |
| `CAP-PFM-LLM-010` | Monitor AI usage across organizations | proposed | observed |
| `CAP-PFM-LLM-011` | Inspect an organization’s AI account and request history | proposed | observed |
| `CAP-PFM-LLM-012` | Explain an AI refusal or unsuccessful conversation | proposed | observed |
| `CAP-PFM-LLM-013` | Set an organization’s AI access and recurring limits | proposed | partially-observed |
| `CAP-PFM-LLM-014` | Provide temporary AI capacity and revoke it | proposed | partially-observed |
| `CAP-PFM-LLM-015` | Correct an organization’s AI charges | proposed | partially-observed |
| `CAP-PFM-LLM-016` | Inspect captured AI content with a live access grant | proposed | partially-observed |
| `CAP-PFM-LLM-017` | Show administrators their organization’s AI allowance | proposed | partially-observed |
| `CAP-PFM-LLM-018` | Give people understandable AI refusal messages | proposed | observed |
| `CAP-PFM-LLM-019` | Use Jazz AI conversations and project folders | proposed | partially-observed |
| `CAP-PFM-LLM-020` | Refine queries and directory filters with Jazz AI | proposed | partially-observed |

## Journeys

| Journey | Goal | Product intent | E2E policy |
|---|---|---|---|
| `JNY-PFM-LLM-001` | A staff member reaches the monthly AI allowance | proposed | required |
| `JNY-PFM-LLM-002` | Support investigates an AI refusal | proposed | required |
| `JNY-PFM-LLM-003` | A Rhythm administrator grants and withdraws temporary AI capacity | proposed | required |
| `JNY-PFM-LLM-004` | An administrator investigates an allowance warning | proposed | optional |
| `JNY-PFM-LLM-005` | A staff member refines a query and resumes its Jazz AI conversation | proposed | required |

The examination report supplies the inventory mapping and outstanding proof obligations. Coverage means that an artifact addresses a source item; it does not mean that a complete customer journey has passed acceptance.


## Test Hierarchy

Feature acceptance stays in planning, detailed capability proof lives in design and executable suites live in implementation. The testing tree names every artifact and its location. Results remain unexecuted, and the coverage findings preserve the missing experiments rather than claiming complete acceptance.