Data Model: Centralise LLM Routing, Quotas and Budgets

One new Mongo collection and one Keycloak object per agent. Limits and usage stay in the gateway.

1. Deployment settings

Setting	Default	Meaning
LLM_GATEWAY_ENABLED	false	Global routing switch. false uses direct-provider configuration and bypasses the gateway even when configured and reachable; true routes migrated paths through the gateway and fails closed on gateway failure.
OPENAI_COMPATIBLE_BASE_URL	—	Gateway endpoint (from llm_wrapper).
LLM_GATEWAY_AUTH	jwt	jwt (gateway token) · key (per-agent gateway key). A gateway property, independent of the adapter.
LLM_GATEWAY_AUDIENCE	llm-gateway	aud of gateway tokens. The gateway must expect the same value.
LLM_GATEWAY_ADAPTER	none	Gateway management integration: litellm · agentgateway · kong · agentrouter · none. none disables management integration, not gateway routing (see adapter contract).
LLM_GATEWAY_DEFAULT_TEAM	platform	Team charged for agents without owner_team_slug. Provisioned at startup.
LLM_GATEWAY_BUDGET_SIGNAL	named adapter default; unset for none	Gateway-limit recognition rule (research Decision 10). Required for budget-error conformance with adapter none.
Adapter admin credential	—	Through the existing secret strategies. Only needed by the UI backend for management integration; not required for none.

Direct-provider configuration and credentials must remain available for disabled mode; configuring a gateway endpoint alone does not enable routing.

2. llm_models (existing collection, additive fields)

Field	Existing?	Meaning
model_id	✓	Same value the gateway alias uses. Unchanged for existing rows.
name, provider, description	✓	Unchanged.
source	new	seed · admin · gateway
gateway_synced_at	new	Time of the last list_models sync.

• Persistence: model catalogue entries persist in MongoDB. Entries come from application configuration, the LLM Models UI, or gateway sync when the adapter declares models.list. Without that capability, administrators maintain entries through the existing configuration or UI and ensure model IDs match gateway aliases. Model sync is not required for inference.
• Rule: when LLM_GATEWAY_ENABLED=true, build_chat_model uses the openai-compatible provider with model_id, whatever provider the caller passes.

3. Gateway token (JWT, not stored)

Claim	Example	Source
iss	https://idp.example.com/realms/caipe	signer
aud	LLM_GATEWAY_AUDIENCE	setting
sub	user or task-owner subject (effective principal)	caller token / trusted run binding (#2891)
act	{"sub": "service-account-dynamic-agents"}	acting service (#2885)
org	example-org	existing org claim (budget key namespace)
agent_id	agent-example	Keycloak scope (K2) or signer (C1)
team_id	team-example	agent owner_team_slug, else LLM_GATEWAY_DEFAULT_TEAM
exp	≤ 5 min	signer

• Cache key: (sub, agent_id, owner_team_slug). The key alone does not ensure ownership consistency: CAIPE must check credential bindings against committed ownership before use or caching, block new calls during unresolved transfers, and invalidate cached credentials for the previous owner on completion.
• Caller kind (user, service account, autonomous) is an OTel label set by the runtime, not a claim.

4. Agent scope (Keycloak, K2 only)

Field	Value
name	llm-agent-<agent_id>
mappers	hardcoded claims agent_id, team_id
assigned to	dynamic-agents exchanger client (optional scope)
lifecycle	created with the agent; synchronized through a recoverable ownership-transfer operation; deleted with the agent

• MongoDB ownership is authoritative. Transfer coordination must prevent calls from using inconsistent ownership and credential bindings, and support recovery after interruption. The recovery mechanism is an implementation decision; updating Keycloak before saving MongoDB is not sufficient on its own.

AI-assist system identity

• Provision a stable AI-assist system agent and its authorization relationships before enabling gateway routing for /assistant/suggest.
• Grant its can_use permission to users authorized to use AI-assist through the existing authorization model; model access remains a separate CAS check.
• Prepare its Keycloak scope (K2), signer mapping (C1), or per-agent gateway key according to the configured authentication mode, including any gateway principal required before first use.
• Use the authenticated caller as sub, the system agent as agent_id, and its owning team as team_id (or LLM_GATEWAY_DEFAULT_TEAM when ownerless). The agent being drafted or edited supplies none of these identity bindings.

5. llm_quota_requests (new Mongo collection)

Field	Meaning
scope	user · agent · team
principal_id	subject, agent id or team slug
requested_by	subject
requested_limit, reason	the ask
status	pending · approved · rejected
decided_by, decided_at	approver
created_at	—

• On approval, the UI backend calls set_limit on the adapter. The gateway holds the result.

6. Adapter capabilities (not stored)

Capabilities describe CAIPE's supported gateway management operations, including model discovery. Auth mode is LLM_GATEWAY_AUTH; inference routing is controlled by LLM_GATEWAY_ENABLED.

Capability	Meaning
models.list	can fetch gateway models and persist them in llm_models; exposing /v1/models alone does not enable CAIPE sync
principals.ensure	must pre-create a user, agent or team before first use
limits.user / limits.agent / limits.team	can set a limit per dimension
limits.budget_usd / limits.tokens / limits.rpm	supported limit types
usage.read	can return spend or usage per principal
keys.issue	can issue per-agent keys; required only for automated key provisioning through CAIPE

• Key authentication requires a valid per-agent gateway key in CAIPE's credentials store. Operator-provisioned keys work without keys.issue, including with adapter none.