--- id: SVC-PFM-LLM-llm title: LLM foundation and AI usage product_area: platform module: llm repository: services-platform source_module: modules/llm revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-LLM-001 - DOM-PFM-LLM-002 - DOM-PFM-LLM-003 - DOM-PFM-LLM-004 does_not_own: - 'Consuming features construct the model question, validate its answer and decide domain effects.' - 'Security owns staff authority, access grants, role audiences and security-audit storage.' - 'Security and workspace lifecycle retain organization identity, status and calendar context.' - 'Queries owns its execution engine, datasets and reusable reporting recipes.' - Shared email transport and future notification delivery retain their separate owners. - Workspace lifecycle orchestrates deletion and invokes this module’s scoped participant. - Console conversation routes retain prototype Jazz AI projects and history. inference: - IOP-PFM-LLM-002 operations: - operation_id: getHqLlmUsageSummary intent: >- Compare historical cost and activity with the preceding window and report current warning and stop counts. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-010 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqLlmUsageTrend intent: 'Show historical spend series for a selected dimension, retaining ten leaders and an Other remainder.' access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-010 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqLlmUsageTenants intent: List organization usage with historical activity and readable live capacity where available. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-010 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqLlmUsageBreakdown intent: 'Group cost, requests, average attempt latency and failure rate by the selected reporting dimension.' access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-010 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqLlmUsageExecutions intent: List expensive closed tasks in the window and identify organizations whose tasks could not be read. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-010 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqLlmUsageCatalog intent: Read each operation’s latest routing and up to nineteen preceding versions. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-005 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqLlmUsageRates intent: Read each provider-model price’s latest version and up to nineteen preceding versions. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-005 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqTenantLlmUsage intent: >- Read an organization’s live position, configuration, active grants, recent months, breakdowns and problem requests as independent sections. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsagePeriods intent: Page through the organization’s allowance months from newest to oldest. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageInvocations intent: Page through filtered organization requests without opening evidence. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqTenantLlmUsageInvocation intent: >- Read request attribution, routing, attempts, charges, task association and capture metadata without object locations. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqTenantLlmUsageInvocationEvidence intent: Read one redacted body or its availability status after eligible access and audit checks. access: system permission: hq.llm-usage.read-evidence realises: - CAP-PFM-LLM-016 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageExecutions intent: Page through an organization’s running and closed tasks in reverse chronological order. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqTenantLlmUsageExecution intent: Read a task’s bookkeeping alongside the requests associated with it. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: getHqTenantLlmUsageLimits intent: 'Read configured limits, effective defaults and platform ceilings.' access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 - CAP-PFM-LLM-013 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageOverrides intent: Page through capacity grants by descending start time with their calculated eligibility. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 - CAP-PFM-LLM-014 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageAdjustments intent: 'Page through signed charge corrections, optionally within one month.' access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 - CAP-PFM-LLM-015 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageCrossings intent: Read the month’s threshold records and their notice claims and completion bookkeeping. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 - CAP-PFM-LLM-008 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: listHqTenantLlmUsageAudit intent: Page through AI control and content-access security history. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-011 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: explainHqTenantLlmUsageInvocation intent: Explain retained refusal decisions or unsuccessful attempts alongside present admission conditions. access: system permission: hq.llm-usage.read realises: - CAP-PFM-LLM-012 published_to_submissions: 'not published: privileged usage or evidence inspection does not capture business records' - operation_id: putHqTenantLlmUsageLimits intent: Replace version-checked limits and synchronize the current month with a reasoned audit. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-013 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: previewHqTenantLlmUsageLimits intent: Calculate the effect of proposed limits without persisting or auditing a change. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-013 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: createHqTenantLlmUsageAdjustment intent: Commit a signed monthly charge correction and its audit together. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-015 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: grantHqTenantLlmUsageOverride intent: Create validated temporary capacity with audit and an optional qualifying restoration notice. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-014 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: previewHqTenantLlmUsageOverride intent: Calculate a grant’s peak capacity and current effect without creating it. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-014 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: revokeHqTenantLlmUsageOverride intent: Record the reasoned revocation of a grant that remains unrevoked and unended. access: system permission: hq.llm-usage.manage realises: - CAP-PFM-LLM-014 published_to_submissions: 'not published: privileged staff controls are outside customer intake' - operation_id: getLlmUsageSummary intent: >- Read the customer’s credits, utilisation, local reset, recent history and feature totals without staff-only detail. access: console permission: platform.llm-usage.read realises: - CAP-PFM-LLM-017 - CAP-PFM-LLM-018 published_to_submissions: 'not published: this read exposes the organization’s own usage rather than accepting business data' - operation_id: listLlmUsageFeatures intent: Read customer feature descriptions and their reported availability or restriction. access: console permission: platform.llm-usage.read realises: - CAP-PFM-LLM-017 - CAP-PFM-LLM-018 published_to_submissions: 'not published: this read exposes the organization’s own usage rather than accepting business data' - operation_id: runOperation intent: 'Execute declared model work through reservation, evidence, attempts and settlement bookkeeping.' access: internal permission: 'none: an in-process call; the consumer authorises its own caller' realises: - CAP-PFM-LLM-001 - CAP-PFM-LLM-002 - CAP-PFM-LLM-004 - CAP-PFM-LLM-007 - CAP-PFM-LLM-013 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' - operation_id: withLlmExecution intent: Wrap related requests in a declared task and return prior work for a repeated replay key. access: internal permission: 'none: an in-process call' realises: - CAP-PFM-LLM-003 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' - operation_id: providerFor intent: Select scripted or live execution and enforce stub-mode and credential prerequisites. access: internal permission: 'none: an in-process call' realises: - CAP-PFM-LLM-006 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' - operation_id: materializeLlmCatalog intent: Publish changed routing and rates into immutable numbered history. access: internal permission: 'none: the deploy-time migration function' realises: - CAP-PFM-LLM-005 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' - operation_id: runLlmReconciliation intent: 'Run stale-work recovery, task checks, notice retries and daily reporting maintenance.' access: internal permission: 'none: invoked by its schedule' realises: - CAP-PFM-LLM-009 - CAP-PFM-LLM-008 - CAP-PFM-LLM-010 - CAP-PFM-LLM-003 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' - operation_id: 'llmParticipant (provision, verifyProvisioned, purge, inventory)' intent: 'Provide workspace preparation, verification, purge and inventory responses for scoped AI data.' access: internal permission: 'none: invoked by the workspace lifecycle job' realises: - CAP-PFM-LLM-004 published_to_submissions: 'not published: internal execution, deployment or workspace maintenance is outside configurable intake' events: [] jobs: - >- Hourly reconciliation at minute seven with one reserved execution slot, a delivery dead-letter queue and configured silence, stale-request, reporting-lag and notice-failure alarms. - Deployment publication after migrations. - Workspace participant responses with bounded purge and inventory. integrations: - system: Anthropic direction: outbound contract: >- Use the vendor messages adapter under the repository provider-boundary guard; obtain credentials at runtime from the named environment-account secret. - system: Evidence bucket (platform-llm-evidence per environment) direction: outbound contract: >- Write redacted JSON under the organization prefix in private encrypted versioned storage governed by current and noncurrent lifecycle expiry. - system: 'Security (role holders, staff access grants, security audit events)' direction: outbound contract: Use Security readers for authority and audience and its audit writer inside control transactions. - system: Shared e-mail library direction: outbound contract: Send recipient messages after commit under the environment delivery policy and count failures. - system: Queries (reporting datasets) direction: inbound contract: >- Expose reporting views for Queries datasets while restricting the HQ reporting reader to aggregate columns. - system: Queries (Describe With AI) direction: inbound contract: Accept the Queries worker’s in-process execution wrapper and declared model-operation invocation. consistency: - rule: Admission reserves capacity and one running slot in a single conditional period update. kind: transactional compensation: A rejected admission takes no new hold. - rule: 'Request settlement and task increments commit together, followed by a separate period movement.' kind: eventual compensation: >- No automatic repair covers terminal requests with incomplete period accounting; reasoned corrections require investigation. - rule: 'Limits, grants, revocations and corrections commit atomically with their security audit.' kind: transactional compensation: A failed transaction rolls back its control and audit writes. - rule: Notice claims are bounded and can end with duplicate messages or no delivery. kind: eventual compensation: Hourly retries stop after three claims and retain an unstamped exhausted crossing. - rule: Daily aggregates reflect successfully rebuilt historical requests up to recorded progress. kind: eventual compensation: Replace complete daily cells on the next eligible rebuild. - rule: 'Validation precedes publication, but rate and routing appends commit individually.' kind: eventual compensation: Keep earlier appends and use digest comparison when publication is repeated. evidence: - >- services-platform at ad3f6a6: modules/llm/aws/api/llm-usage.routes.ts (twenty-eight declared operations, plus the shared health route), llm-usage-api-mapper.ts, llm-usage.schemas.ts; aws/lambda/API.handler.ts, RECONCILIATION.handler.ts; aws/logic/llm-api.lambda.ts, llm-reconciliation.lambda.ts, llm-runtime.access.ts; aws/resources/llm-evidence.s3.ts; services/**; runtime/**; catalog/**; aws/platform.service.ts (LLM_USAGE_PERMISSIONS, HQ_LLM_USAGE_PERMISSIONS); aws/lambda/migrate.handler.ts; modules/tenants/services/lifecycle/participants.ts; docs/llm.md; docs/standards/submission-compatible-operations.md; docs/standards/custom-field-capability.md. controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, 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-CHG-007, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, 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-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # LLM foundation and AI usage ## What This Service Is For The LLM foundation executes declared model operations and accounts for their usage. It gives HQ staff historical and diagnostic reads, privileged controls and narrow evidence access, while customer administrators receive their own credit summary. Query generation uses this execution boundary; prototype general Jazz AI replies do not. ## Boundary The service owns request and task bookkeeping, operation and price history, allowance records, captured bodies and daily aggregates. Consuming features determine questions and validate answers. Security, Queries, email transport and workspace orchestration retain their respective delegated work. Prototype conversation storage remains in the console. ## Operations in Words Staff reads cover cross-organization history and one organization’s periods, requests, tasks, configuration and audit. Sensitive management operations preview or change limits, grant or revoke capacity and record corrections. Evidence access uses separate permission and eligible grants. Customer reads provide credits and feature availability. Internal functions execute tasks, publish declarations and perform maintenance. ## Events and Jobs No business-event producer or consumer is declared. The hourly worker recovers stale work, checks task totals, retries notices and refreshes daily reporting. Deployment publishes configuration, and workspace lifecycle invokes the purge participant. Metrics and alarms provide operational signals. No operation declares a Submissions binding. ## Consistency Guarantees Admission and control-audit transactions have explicit database boundaries. Request settlement and period movement do not share an automatic transaction, so interrupted accounting remains a finding. Notice handling and daily reporting complete later and can remain incomplete. Catalogue validation prevents invalid declarations from publishing, while separate appends can leave partial publication.