B04 - Model Registry

Group	Technology	Status	Service	Roadmap phase	Contracts
B - LLM management and Model Gateway	Developed (PostgreSQL)	to develop	llm	2	model-manifest

Back to index - Français

Role and responsibilities

Every model with mandatory fields: modalities, limits, reasoning, residency, classification, pricing, status.

Position in the architecture and interactions

Source for the Resolver, Router, Context Manager, Pricing and Governance Registry. Models can be applied as manifests with POST /v1/manifests/apply (kind: Model). Promotion to approved requires an evaluation gate (B12) and an approval (A12).

Data model

eai.llm_models stores the Model Manifest (contracts/v1/model-manifest.schema.json). Mandatory fields:

Field	Meaning
model_id	Stable internal identifier
provider	Provider id from the Provider Registry
provider_model_id	Identifier used by the provider API
deployment_id	Deployment and region (e.g. vllm-paris-a100)
modalities	Input and output modalities
capabilities	chat, tools, json_schema, streaming, embeddings, reasoning...
context_window	Maximum documented window in tokens
max_output_tokens	Maximum output tokens
reasoning_modes	Supported effort levels and native mechanism
supports_caching	Prompt caching support
supports_batch	Batch API support
supports_streaming	Streaming support
data_residency	Regions where data is processed
data_classification_max	Highest classification allowed
pricing_version	Price card version (B10)
quality_profile	Evaluation profile and scores (B12)
status	approved, restricted, deprecated, blocked

Tables (schema eai, every tenant table carries tenant_id uuid NOT NULL with an RLS policy on current_setting('app.tenant_id', true)::uuid): eai.llm_models, eai.audit_events.

API endpoints

• GET /v1/models
• POST /v1/models
• GET /v1/models/{model_id}
• PATCH /v1/models/{model_id}
• DELETE /v1/models/{model_id}
• POST /v1/models/{model_id}/status
• POST /v1/models/{model_id}/disable

POST /v1/models HTTP/1.1
Host: <control-plane-host>
X-API-Key: eai_xxx_secret
Accept-Language: en
Content-Type: application/json

{"apiVersion": "enterprise-ai.io/v1", "kind": "Model", "metadata": {"name": "claude-sonnet-eu"}, "spec": {"model_id": "claude-sonnet-eu", "provider": "aws_bedrock", "provider_model_id": "eu.anthropic.claude-sonnet-4-20250514-v1:0", "deployment_id": "bedrock-eu-west-3-claude-sonnet-4", "status": "approved", "modalities": {"input": ["text"], "output": ["text"]}, "capabilities": ["chat", "tools", "streaming"], "context_window": 200000, "max_output_tokens": 64000, "reasoning_modes": ["none"], "supports_caching": true, "supports_batch": false, "supports_streaming": true, "data_residency": {"regions": ["eu-west-3"], "jurisdiction": "eu"}, "data_classification_max": "confidential", "pricing_version": "2025-10", "quality_profile": {"general": 0.9}}}

{"status": "approved", "model_id": "claude-sonnet-eu", "provider": "aws_bedrock", "modalities": {"input": ["text"], "output": ["text"]}, "capabilities": ["chat", "tools", "streaming"], "deployment_id": "bedrock-eu-west-3-claude-sonnet-4", "context_window": 200000, "data_residency": {"regions": ["eu-west-3"], "jurisdiction": "eu"}, "supports_batch": false, "pricing_version": "2025-10", "quality_profile": {"general": 0.9}, "reasoning_modes": ["none"], "supports_caching": true, "max_output_tokens": 64000, "provider_model_id": "eu.anthropic.claude-sonnet-4-20250514-v1:0", "supports_streaming": true, "data_classification_max": "confidential", "id": "011711da-6130-4d85-a40c-1681c38c152d", "disabled": false, "pricing": {}, "version": "1.0.0", "owner": "platform-team", "scope": "tenant", "source": "api", "wire_format": "bedrock_converse", "provider_local": false, "provider_row_id": null, "provider_disabled": false, "provider_configured": false, "provider_api_base": "https://bedrock-runtime.{aws_region_name}.amazonaws.com"}

Errors use the common envelope {"error": {"code", "message", "message_i18n", "details", "request_id"}}; lists are paginated with limit and cursor.

SDK usage

Python (enterprise_ai):

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_xxx_secret")
items = client.models.list()

TypeScript (@enterprise-ai/sdk):

import { EnterpriseAI } from "@enterprise-ai/sdk";

const eai = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY });
const items = await eai.models.list();

Java (enterprise-ai-java):

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .build();
var items = client.models().list();

Go (enterprise-ai-go):

client, _ := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")))
items, err := client.Models.List(ctx)

Configuration

• Environment: EAI_DATABASE_URL, EAI_OTEL_EXPORTER_OTLP_ENDPOINT.
• Helm values: controlPlane.enabled, controlPlane.replicas, controlPlane.resources, controlPlane.config, litellm.enabled, litellm.config.

Security controls

• Authentication by OIDC JWT, tenant API key with scopes, or SPIFFE mTLS; tenant resolved from the credential, never from the body.
• Authorization through OpenFGA and OPA decisions; every mutation and decision writes a hash-chained eai.audit_events row.
• Secrets never returned by the API; TLS everywhere; Cilium network policies restrict who can reach the service.

Observability

• Metrics: eai_model_registry_requests_total, eai_model_registry_errors_total, eai_model_registry_latency_seconds (Prometheus).
• Traces: OpenTelemetry spans eai.models.* with W3C traceparent propagation, AI spans forwarded to Opik.
• Audit actions: model.create, model.update, model.delete, model.status, policy.evaluate.

FinOps aspects

Operating cost is allocated per tenant and project through labels on Usage Events and Kubernetes resource requests; no direct per-call cost.

Failure modes and resilience

• Stateless replicas behind the API Gateway, PostgreSQL HA for state; readiness probe GET /readyz removes unhealthy pods.
• External system unavailable: fail closed for security decisions, explicit error code, no silent bypass.

Standalone adoption (client of a client)

A client of a client can adopt this brick alone with the Python SDK sub-client client.models (TS eai.models, Java client.models(), Go client.Models). Minimal deployment: Control Plane API + PostgreSQL + Keycloak (or API keys), the Control Plane loads every domain of services/control-plane/src/eai/domains; the optional chart components are switched off in deploy/helm/enterprise-ai/values.yaml (vllm.enabled, qdrant.enabled, nats.enabled, workers.enabled).

Acceptance tests

1. A tenant cannot read or modify another tenant's resources (RLS test).
2. Every mutation produces an audit event verifiable by GET /v1/audit/verify.
3. Errors are returned in English and French according to Accept-Language.

Versions, licences, weights, rollout and rollback (LLM_-004, LLM_-016)

Each version (eai.llm_model_versions, V135) carries a licence (SPDX expression or vendor terms reference https:// or LicenseRef-) and the weights provenance: source (hf://, oci://, https://, s3://, registry://), sha256: digest, size. A version starts draft; POST .../versions/{version}/approval opens a model_version_activation approval decided by another person (tenant_admin or security_officer, separation of duties); approved_by and approved_at are copied onto the version at publication. Without a granted approval the publication is refused (403 model_version_not_approved).

POST .../rollout publishes at 100 percent or opens a canary (1 to 99 percent of the traffic, split stably per session); POST .../rollback aborts the canary or restores the previous version. Every step is appended to eai.llm_model_rollout_history (V136) and audited (model.rollout.publish|canary|rollback). Tests: tests/test_llm_model_lifecycle.py.