enterprise_ai.llm.models

Source: sdks/python/src/enterprise_ai/llm/models/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class ModelsClient

/v1/models, /v1/llm/categories, /v1/litellm.

Resource

ModelsClient.approve_version

approve_version(model_id: str, version: str, approval: dict[str, Any] | None = None) -> Any

Request the approval of a version. Opens an approval request (action model_version_activation) for a draft version and answers 202 with its id; the version becomes pending_approval. The approvers are tenant_admin and security_officer, and the requester cannot approve its own request (separation of duties). A version that is not a draft answers 409 model_version_state. Audited. Requires a tenant principal with tenant_admin or platform_admin.

Route: /v1/models/{model_id}/versions/{version}/approval (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
version	str		yes	Version to approve, as registered.
approval	dict[str, Any] | None	None	no	Approval document sent as the body; empty by default.

Returns: Any. Decoded JSON answer of the operation "Request the approval of a version".

Raises: the typed errors of the transport (Errors).

ModelsClient.create

create(model: dict[str, Any]) -> Any

Register a model. Registers a model for the tenant, or a shared one with scope: platform (platform_admin only), and answers 201. The body is a Model Manifest v1 or a bare spec; it must be valid (422 invalid_manifest) and its category must exist. A model id already registered in the same scope answers 409 model_exists. Audited (model.create). Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/models (POST).

Name	Type	Default	Required	Description
model	dict[str, Any]		yes	Only cards whose model pattern matches this model id (case insensitive glob).

Returns: Any. Decoded JSON answer of the operation "Register a model".

Raises: the typed errors of the transport (Errors).

ModelsClient.create_category

create_category(slug: str, label: dict[str, str], **extra: Any) -> Any

Create a model category. Creates a category for the tenant, or a shared one with scope: platform (platform_admin only, 403 platform_only), and answers 201. A slug already used answers 409 category_exists; invalid fields 422 parameter_invalid. Audited. Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/llm/categories (POST).

Name	Type	Default	Required	Description
slug	str		yes	Unique slug of the new category.
label	dict[str, str]		yes	Display name of the category in both languages, {en, fr}.
**extra	Any		no	Extra fields merged into the request body.

Returns: Any. Decoded JSON answer of the operation "Create a model category".

Raises: the typed errors of the transport (Errors).

ModelsClient.create_version

create_version(model_id: str, version: dict[str, Any]) -> Any

Register a model version. Registers a version of the model in the tenant with status draft and answers 201. The version needs a licence (SPDX expression, or terms reference starting with https:// or LicenseRef-) and the weights provenance; invalid fields answer 422 model_version_invalid with their names, an existing version 409 model_version_exists. Audited (model.version.create). Requires a tenant principal with tenant_admin or platform_admin.

Route: /v1/models/{model_id}/versions (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
version	dict[str, Any]		yes	Version document (version, provider_model, digest...) sent as the body.

Returns: Any. Decoded JSON answer of the operation "Register a model version".

Raises: the typed errors of the transport (Errors).

ModelsClient.delete

delete(model_id: str) -> Any

Delete a model from the registry. Deletes the tenant entry of the model (an override of a shared model brings the shared entry back), or the shared entry when there is no tenant entry; the shared entry needs platform_admin (403 platform_only). Answers 204; audited (model.delete). Unknown model: 404 model_not_found. Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/models/{model_id} (DELETE).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model (not the provider model id).

Returns: Any. Decoded JSON answer of the operation "Delete a model from the registry".

Raises: the typed errors of the transport (Errors).

ModelsClient.delete_category

delete_category(slug: str) -> Any

Delete a model category. Deletes a category created by the tenant or the platform and answers 204. A predefined category cannot be deleted (409 category_builtin), nor a category still used by a model (409 category_in_use); a shared category needs platform_admin (403 platform_only). Audited. Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/llm/categories/{slug} (DELETE).

Name	Type	Default	Required	Description
slug	str		yes	Slug of the category: lowercase letters, digits, dashes and underscores, 1 to 40 characters.

Returns: Any. Decoded JSON answer of the operation "Delete a model category".

Raises: the typed errors of the transport (Errors).

ModelsClient.disable

disable(model_id: str) -> Any

Disable a model (kill switch). Kill switch of the model for the tenant: the gateway refuses it at once (403 model_disabled). On a shared model this creates a tenant override. Audited (model.disable). Requires tenant_admin, platform_admin, ai_platform_engineer or security_officer.

Route: /v1/models/{model_id}/disable (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.

Returns: Any. Decoded JSON answer of the operation "Disable a model (kill switch)".

Raises: the typed errors of the transport (Errors).

ModelsClient.enable

enable(model_id: str) -> Any

Enable a disabled model. Lifts the kill switch of the model for the tenant. Audited (model.enable). Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/models/{model_id}/enable (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.

Returns: Any. Decoded JSON answer of the operation "Enable a disabled model".

Raises: the typed errors of the transport (Errors).

ModelsClient.get

get(model_id: str) -> Any

Get a registered model. One model of the registry, or its Model Manifest v1 with format=manifest. Unknown model: 404 model_not_found. Requires a reader role.

Route: /v1/models/{model_id} (GET).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.

Returns: Any. Decoded JSON answer of the operation "Get a registered model".

Raises: the typed errors of the transport (Errors).

ModelsClient.get_category

get_category(slug: str) -> Any

Get a model category. One model category with its number of models. Unknown slug: 404 category_not_found. Requires a reader role.

Route: /v1/llm/categories/{slug} (GET).

Name	Type	Default	Required	Description
slug	str		yes	Slug of the category.

Returns: Any. Decoded JSON answer of the operation "Get a model category".

Raises: the typed errors of the transport (Errors).

ModelsClient.import_models

import_models(provider_id: str, models: list[dict[str, Any]], scope: str | None = None) -> Any

Import discovered models. Registers the models chosen in a discovery. Idempotent: the ones already registered (same id, or same provider and provider model id) are skipped and listed with already_registered. Every item is checked first; one invalid item refuses the whole import with 422 import_invalid and the problem of each item. Each model and the import are audited. Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/models/import (POST).

Name	Type	Default	Required	Description
provider_id	str		yes	Identifier of the provider that serves the models.
models	list[dict[str, Any]]		yes	Models picked in a provider discovery; models already registered are skipped.
scope	str | None	None	no	Scope of the imported models, for example tenant or platform; the server default when omitted.

Returns: Any. Decoded JSON answer of the operation "Import discovered models".

Raises: the typed errors of the transport (Errors).

ModelsClient.list

list(**page: Any) -> Any

List the registered models. Models visible to the caller (shared models with the tenant overrides applied, and the tenant models), optionally filtered. One page only (next_cursor is always null). Requires a reader role.

Route: /v1/models (GET).

Name	Type	Default	Required	Description
**page	Any		no	Pagination options: limit (maximum number of models per page) and cursor (cursor of the page to read).

Returns: Any. Decoded JSON answer of the operation "List the registered models".

Raises: the typed errors of the transport (Errors).

ModelsClient.list_categories

list_categories() -> Any

List the model categories. Model categories visible to the caller (predefined, shared and tenant ones) with their label and description in English and French, icon, order and number of models using them. One page only. Requires a reader role.

Route: /v1/llm/categories (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the model categories".

Raises: the typed errors of the transport (Errors).

ModelsClient.list_versions

list_versions(model_id: str) -> Any

List the versions of a model. Versions of the model in the tenant, oldest first, with licence, weights source, digest and size, capabilities, status (draft, pending_approval, canary, active, superseded, rolled_back) and approval. Requires a tenant principal with tenant_admin, platform_admin, security_officer, finops, developer, auditor or viewer.

Route: /v1/models/{model_id}/versions (GET).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.

Returns: Any. Decoded JSON answer of the operation "List the versions of a model".

Raises: the typed errors of the transport (Errors).

ModelsClient.litellm_config

litellm_config() -> Any

Generate the LiteLLM configuration. LiteLLM proxy configuration generated from the visible models and the enabled providers (a tenant provider wins over a shared one of the same type). It never holds a secret value: credentials are os.environ/<NAME> references resolved by the LiteLLM deployment. Requires tenant_admin, platform_admin, ai_platform_engineer, security_officer or auditor.

Route: /v1/litellm/config (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Generate the LiteLLM configuration".

Raises: the typed errors of the transport (Errors).

ModelsClient.litellm_sync

litellm_sync() -> Any

Push the configuration to LiteLLM. Makes the LiteLLM proxy hold exactly the generated model list: models created by the Control Plane and no longer wanted are removed, missing ones are added; models added by hand in LiteLLM are left alone. Without EAI_LITELLM_URL nothing is pushed (mode: in_process). A transport error answers 502 upstream_error. Audited (litellm.sync). Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/litellm/sync (POST).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Push the configuration to LiteLLM".

Raises: the typed errors of the transport (Errors).

ModelsClient.resolve

resolve(model: str, effort: str | None = None, **params: Any) -> Any

Resolve the native call parameters. Capability Resolver: translates normalized call parameters (for example the reasoning effort none, low, medium, high, max) into the native parameters of the model, from what its manifest declares. An unsupported value is rejected with an explicit code or adjusted with a warning in the answer, never silently. Unknown model: 404 model_not_found. Requires a reader role.

Route: /v1/models/resolve (POST).

Name	Type	Default	Required	Description
model	str		yes	Only cards whose model pattern matches this model id (case insensitive glob).
effort	str | None	None	no	Reasoning effort to resolve for the model; the model default when omitted.
**params	Any		no	Extra fields merged into the request.

Returns: Any. Decoded JSON answer of the operation "Resolve the native call parameters".

Raises: the typed errors of the transport (Errors).

ModelsClient.rollback

rollback(model_id: str, request: dict[str, Any] | None = None) -> Any

Roll back a model version. During a canary, aborts it: the active version keeps all the traffic. Otherwise, restores the version that was active before the last full publication. The version left becomes rolled_back, the step is added to the rollout history and audited (model.rollout.rollback). Nothing to roll back: 409 model_rollback_unavailable. Requires a tenant principal with tenant_admin or platform_admin.

Route: /v1/models/{model_id}/rollback (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
request	dict[str, Any] | None	None	no	Optional {reason} written to the rollout history and the audit trail.

Returns: Any. Decoded JSON answer of the operation "Roll back a model version".

Raises: the typed errors of the transport (Errors).

ModelsClient.rollout

rollout(model_id: str) -> Any

Read the rollout of a model. Active version, canary version and canary share of the model in the tenant, with the whole rollout history (publish, canary, rollback, actor, reason, approval). Requires a tenant principal with tenant_admin, platform_admin, security_officer, finops, developer, auditor or viewer.

Route: /v1/models/{model_id}/rollout (GET).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.

Returns: Any. Decoded JSON answer of the operation "Read the rollout of a model".

Raises: the typed errors of the transport (Errors).

ModelsClient.set_status

set_status(model_id: str, status: str) -> Any

Change the status of a model. Sets the status to approved, restricted, deprecated or blocked (422 status_invalid otherwise). For a tenant, a promotion to approved is not applied at once: an approval request is opened and the answer is 202 with it; the status changes once it is approved. Other changes apply at once and are audited (model.status, with the previous and new status). Requires tenant_admin, platform_admin, ai_platform_engineer or security_officer.

Route: /v1/models/{model_id}/status (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
status	str		yes	New status: approved, restricted, deprecated or blocked; another value raises ValueError.

Returns: Any. Decoded JSON answer of the operation "Change the status of a model".

Raises: ValueError, the typed errors of the transport (Errors).

ModelsClient.start_rollout

start_rollout(model_id: str, version: str, rollout: dict[str, Any]) -> Any

Publish a model version. Publishes an approved version fully (canary_percent 100, default) or as a canary for 1 to 99 percent of the traffic, picked deterministically from the caller (same session or principal, same version). Requires a tenant principal with tenant_admin or platform_admin.

Route: /v1/models/{model_id}/versions/{version}/rollout (POST).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
version	str		yes	Approved version to publish.
rollout	dict[str, Any]		yes	Rollout document (canary percentage, guard thresholds) sent as the body.

Returns: Any. Decoded JSON answer of the operation "Publish a model version".

Raises: the typed errors of the transport (Errors).

ModelsClient.update

update(model_id: str, **changes: Any) -> Any

Update a registered model. Changes fields of the model spec, the sheet (category, display_name, knowledge_cutoff) or the prices; the model id never changes. A tenant change of a shared model creates a tenant override. The merged spec must stay a valid Model Manifest v1 (422 invalid_manifest) and the category must exist. Audited (model.update). Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/models/{model_id} (PATCH).

Name	Type	Default	Required	Description
model_id	str		yes	Registry identifier of the model.
**changes	Any		no	Fields of the model to change, sent as the PATCH body.

Returns: Any. Decoded JSON answer of the operation "Update a registered model".

Raises: the typed errors of the transport (Errors).

ModelsClient.update_category

update_category(slug: str, **changes: Any) -> Any

Update a model category. Changes the label, description, icon or order of a category; the slug never changes. A predefined category answers 409 category_builtin; a shared category needs platform_admin. Invalid values answer 422 parameter_invalid. Audited. Requires tenant_admin, platform_admin or ai_platform_engineer.

Route: /v1/llm/categories/{slug} (PATCH).

Name	Type	Default	Required	Description
slug	str		yes	Slug of the category.
**changes	Any		no	Fields of the category to change, sent as the PATCH body; predefined categories are read only.

Returns: Any. Decoded JSON answer of the operation "Update a model category".

Raises: the typed errors of the transport (Errors).

Class ModelRegistryCache

TTL cache of registry entries keyed by model_id (sync client).

Attributes:

Name	Type	Required	Description
ttl		yes	Lifetime of a cached entry, in seconds.

Constructor ModelRegistryCache

ModelRegistryCache(models: ModelsClient | None = None, ttl: float = 300.0) -> None

Create an empty cache, optionally backed by the models sub-client to fetch missing or stale entries.

Name	Type	Default	Required	Description
models	ModelsClient | None	None	no	Sync models sub-client used to fetch entries; None (or an async client) keeps the cache purely local.
ttl	float	300.0	no	Lifetime of a cached entry, in seconds (default 300.0).

ModelRegistryCache.get

get(model_id: str) -> dict[str, Any] | None

Return a cached entry, fetching it from the registry when stale.

Name	Type	Default	Required	Description
model_id	str		yes	Identifier of the model.

Returns: dict[str, Any] \| None. Registry entry of the model; without a sync client, the stale entry or None.

ModelRegistryCache.put

put(entry: dict[str, Any]) -> None

Insert an entry (manifest or registry document) locally.

Name	Type	Default	Required	Description
entry	dict[str, Any]		yes	Model Manifest or registry document; its key is spec.model_id, model_id or metadata.name.

Returns: None.