AI Across the Platform — Operator Guide guide

This guide covers the credit model, the model routing policy, the guard model, and how to operate it.

Concepts

Concept	What it means
Operation	A named AI action (`categorization`, `sol_chat`, `invoice_extraction`, …) with a credit price.
Credit gate	The pre-check that charges and, if over limit, refuses — before the model runs.
Payer	The account a request is billed to: the acting account, or an opted-in managed client’s.
Feature group	The org-facing bundle a credit grant is expressed in (TICKET_AI, INVOICE_AI, SOL_ASSISTANT, KNOWLEDGE_AI, CHANGE_AI).
Routing matrix	The single table mapping each operation to model, token budget, reasoning depth and caching.
Model usage	The per-request dollar cost record: model, tokens, cache reads/writes.

The credit model

Prices are declared once, in AI_OPERATION_CREDITS:

Operation	Credits
`categorization`	1
`sol_tool_execution`	1
`summaries`	2
`rag`	3
`sol_chat`	3
`change_analysis`	4
`invoice_extraction`	5
`sol_vision`	5
`sol_tool_use`	5
`brand_palette`	5

The gate runs as the first statement of a route, before validation or business logic, and refuses with:

Code	Status	Meaning
`AI_CREDIT_LIMIT_EXCEEDED`	402	The payer is out of credits for the period.
`AI_ACCOUNT_CONTEXT_REQUIRED`	402	No billable account. Only platform admins may run without one.
`AI_FEATURE_NOT_ON_PLAN`	403	The plan lacks the capability; carries an upgrade offer.
`AI_METERING_UNAVAILABLE`	503	Metering itself is down — refused rather than run free.

The gate fails closed. An unresolvable plan degrades to a bounded free-tier floor, never to unlimited.

Who pays

resolveAiPayer picks the bucket: the acting account by default, or an opted-in managed client’s account when an MSP acts on that client.

Model routing

Every operation declares its configuration in one place rather than at the call site:

Reasoning is off for routine operations, so an operation’s token budget is spent on its answer rather than on thinking. The assistant’s turns are the exception: they enable adaptive reasoning with a summary shown in the stream.

Two constraints the router enforces for you:

Haiku does not accept the effort parameter, so it is never sent there.
Disabling reasoning cannot be combined with the top two effort levels on the Opus 5 line — the pair is rejected by the API — so effort is clamped instead.

Adding a model means adding a rate row to MODEL_COST_RATES; without one, requests are costed at the tier’s prefix-match fallback.

Guards

Every router carries a role floor or documents why it is deliberately open. Remember the hierarchy:

platform administrator > MSP administrator > MSP technician > organization administrator > power user > CUSTOMER

MSP technician ranks above organization administrator, so a MSP technician floor removes a feature from the org portal entirely.

Deliberately unfloored, with the reason recorded in each file:

Rank is only half of it. A floor answers “what rank”, never “whose data”. Routes that take an entity id from the path also verify the caller may reach that entity, and return 404 rather than 403 so existence is not disclosed.

Degraded behaviour

The house rule is that a degraded AI path never invents a figure.

An outage returns 200 with analysis fields null, fallback: true, and a human-readable fallbackReason. A score that was not computed is null, not a plausible default — a defaulted “LOW” risk would turn an outage into a fleet-wide silent downgrade.
These are the quick-check, quick-assess and quick-assessment family.
Model refusals and truncations raise distinct errors rather than surfacing as “failed to parse AI response”.

Troubleshooting

Symptom	Cause
Everything AI returns 503 on startup	A required key is unset. In production the service refuses to start and says which.
One tenant sees `402` everywhere	Its allowance is exhausted for the period. Check `usage/summary`.
An MSP gets `403` acting on a client	The client has not granted access to the MSP’s credit pool for that feature group.
Cost summary looks lower than expected	Check the operation is going through the shared client; a service constructing its own model client must record usage explicitly.
A route 404s for a record the user can see	The caller does not service that record’s account.

Limits and known behaviour

Batch processing is not mounted. The router exists but is disabled pending an ownership record, credit gating and cost attribution.
A number of client hooks exist without a UI caller; they are reachable over the API but not from the product.