API Reference

ModelRegistryClient

class kubeflow.hub.ModelRegistryClient(base_url: str, port: int | None = None, *, author: str | None = None, is_secure: bool | None = None, user_token: str | None = None, custom_ca: str | None = None)

Bases: object

Client for Kubeflow Model Registry operations.

Requires the model-registry package to be installed. Install it with:

pip install ‘kubeflow[hub]’

__init__(base_url: str, port: int | None = None, *, author: str | None = None, is_secure: bool | None = None, user_token: str | None = None, custom_ca: str | None = None)

Initialize the ModelRegistryClient.

Parameters:

base_url (str) – Base URL of the model registry server including scheme. Examples: “https://registry.example.com”, “http://localhost”. The scheme is used to infer is_secure and port if not explicitly provided.

Keyword Arguments:

• port – Server port. If not provided, inferred from base_url scheme: - https:// defaults to 443 - http:// defaults to 8080 - no scheme defaults to 443

• author – Name of the author. Defaults to None.

• is_secure – Whether to use a secure connection. If not provided, inferred from base_url: - https:// sets is_secure=True - http:// sets is_secure=False - no scheme defaults to True

• user_token – The PEM-encoded user token as a string. Defaults to None.

• custom_ca – Path to the PEM-encoded root certificates as a string. Defaults to None.

Raises:

ImportError – If model-registry is not installed.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org", port=456)
>>> client = ModelRegistryClient("https://example.org:456")
>>> client = ModelRegistryClient("https://example.org")

register_model(name: str, uri: str, *, version: str, model_format_name: str | None = None, model_format_version: str | None = None, author: str | None = None, owner: str | None = None, version_description: str | None = None, metadata: Mapping[str, bool | int | float | str] | None = None, storage_config: StorageConfig | None = None) → RegisteredModel

Register a model in the model registry.

This registers a model version and its artifact in the registry. The model data must be stored in remote storage (e.g., S3, GCS) before registration.

Most models can be registered using their URI, along with an optional storage_config describing how KServe should fetch the model at inference time. URI builder utilities are recommended when referring to specialized storage; for example utils.s3_uri_from when using S3 object storage data connections.

Parameters:

• name (str) – Name of the model.

• uri (str) – URI of the model artifact in remote storage.

Keyword Arguments:

• version – Unique version string for the model (e.g., “v1.0.0”).

• model_format_name – Name of the model format (e.g., “pytorch”, “onnx”). Used by KServe to select the appropriate serving runtime. Defaults to None.

• model_format_version – Version of the model format (e.g., “2.0”). Defaults to None.

• author – Author of the model. Defaults to the client author.

• owner – Owner of the model. Defaults to the client author.

• version_description – Description of the model version. Defaults to None.

• metadata – Additional model version metadata. Defaults to None.

• storage_config – Storage credentials configuration for the model artifact. See StorageConfig for details. Defaults to None.

Returns:

The registered model object.

Raises:

model_registry.exceptions.StoreError – If registration fails in the underlying store.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> model = client.register_model(
...     name="my-model",
...     uri="s3://my-bucket/models/my-model",
...     version="v1.0.0",
...     model_format_name="pytorch",
...     model_format_version="2.0",
...     version_description="Initial model registration",
... )

update_model(model: RegisteredModel) → RegisteredModel

Update a registered model metadata or attributes.

Parameters:

model (RegisteredModel) – The registered model object to update. Must contain an ID.

Returns:

The updated registered model object.

Raises:

• TypeError – If the input is not a RegisteredModel instance.

• model_registry.exceptions.StoreError – If the model does not have an ID or store fails.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> model = client.get_model("my-model")
>>> model.description = "Updated description"
>>> updated_model = client.update_model(model)

update_model_version(model_version: ModelVersion) → ModelVersion

Update metadata or attributes of a model version.

Parameters:

model_version (ModelVersion) – The model version object to update. Must contain an ID.

Returns:

The updated model version object.

Raises:

• TypeError – If the input is not a ModelVersion instance.

• model_registry.exceptions.StoreError – If the model version does not have an ID or the store operation fails.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> version = client.get_model_version("my-model", "v1.0.0")
>>> version.description = "Updated version description"
>>> updated_version = client.update_model_version(version)

update_model_artifact(model_artifact: ModelArtifact) → ModelArtifact

Update metadata or attributes of a model artifact.

Parameters:

model_artifact (ModelArtifact) – The model artifact object to update. Must contain an ID.

Returns:

The updated model artifact object.

Raises:

• TypeError – If the input is not a ModelArtifact instance.

• model_registry.exceptions.StoreError – If the model artifact does not have an ID or the store operation fails.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> artifact = client.get_model_artifact("my-model", "v1.0.0")
>>> artifact.uri = "s3://my-bucket/new-path"
>>> updated_artifact = client.update_model_artifact(artifact)

get_model(name: str) → RegisteredModel

Retrieve a registered model by name.

Parameters:

name (str) – The name of the registered model.

Returns:

The retrieved registered model object.

Raises:

ValueError – If the model name is not found.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> model = client.get_model("my-model")
>>> print(model.id)

get_model_version(name: str, version: str) → ModelVersion

Retrieve a specific model version.

Parameters:

• name (str) – The name of the registered model.

• version (str) – The model version string to retrieve.

Returns:

The retrieved model version object.

Raises:

• model_registry.exceptions.StoreError – If the model does not exist.

• ValueError – If the version is not found.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> version = client.get_model_version("my-model", "v1.0.0")
>>> print(version.id)

get_model_artifact(name: str, version: str) → ModelArtifact

Retrieve a model artifact.

Parameters:

• name (str) – The name of the registered model.

• version (str) – The version string of the model.

Returns:

The retrieved model artifact object.

Raises:

• model_registry.exceptions.StoreError – If either the model or the version does not exist.

• ValueError – If the artifact is not found.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> artifact = client.get_model_artifact("my-model", "v1.0.0")
>>> print(artifact.uri)

list_models() → Iterator[RegisteredModel]

List registered models.

Yields:

Registered model objects in the registry.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> for model in client.list_models():
...     print(model.name)

list_model_versions(name: str) → Iterator[ModelVersion]

List model versions for a registered model.

Parameters:

name (str) – The name of the registered model.

Yields:

Model version objects associated with the model.

Raises:

model_registry.exceptions.StoreError – If the model does not exist.

Examples

>>> from kubeflow.hub import ModelRegistryClient
>>> client = ModelRegistryClient("https://example.org")
>>> for version in client.list_model_versions("my-model"):
...     print(version.name)

Types

The following types are returned by the client methods. They are provided by the model-registry package.

class model_registry.types.RegisteredModel(**data: Any) → None

Bases: BaseResourceModel

Represents a registered model.

name

Registered model name.

owner

Owner of this Registered Model.

description

Description of the object.

external_id

Customizable ID. Has to be unique among instances of the same type.

name: str

owner: str | None

state: RegisteredModelState

create(**kwargs) → RegisteredModelCreate

Convert the object to a create request.

update(**kwargs) → RegisteredModelUpdate

Convert the object to an update request.

classmethod from_basemodel(source: RegisteredModel) → RegisteredModel

Create a new object from a BaseModel object.

model_config: ClassVar[ConfigDict] = {'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class model_registry.types.ModelVersion(**data: Any) → None

Bases: BaseResourceModel

Represents a model version.

name

Name of this version.

author

Author of this model version.

state

Status of this model version.

description

Description of this object.

external_id

Customizable ID. Has to be unique among instances of the same type.

artifacts

Artifacts associated with this version.

name: str

author: str | None

state: ModelVersionState

registered_model_id: str | None

create(*, registered_model_id: str, **kwargs) → ModelVersionCreate

Convert the object to a create request.

update(**kwargs) → ModelVersionUpdate

Convert the object to an update request.

classmethod from_basemodel(source: ModelVersion) → ModelVersion

Create a new object from a BaseModel object.

model_config: ClassVar[ConfigDict] = {'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class model_registry.types.ModelArtifact(**data: Any) → None

Bases: Artifact

Represents a Model.

name

Name of the model.

uri

URI of the model.

description

Description of the object.

external_id

Customizable ID. Has to be unique among instances of the same type.

model_format_name

Name of the model format.

model_format_version

Version of the model format.

storage_key

Storage secret name.

storage_path

Storage path of the model.

service_account_name

Name of the service account with storage secret.

model_source_kind

A string identifier describing the source kind.

model_source_class

A subgroup within the source kind.

model_source_group

This identifies a source group for models from source class.

model_source_id

A unique identifier for a source model within kind, class, and group.

model_source_name

A human-readable name for the source model.

model_format_name: str | None

model_format_version: str | None

storage_key: str | None

storage_path: str | None

service_account_name: str | None

model_source_kind: str | None

model_source_class: str | None

model_source_group: str | None

model_source_id: str | None

model_source_name: str | None

uri: str | None

create(**kwargs) → ModelArtifactCreate

Create a new ModelArtifactCreate object.

update(**kwargs) → ModelArtifactUpdate

Create a new ModelArtifactUpdate object.

as_basemodel() → ModelArtifact

Wrap the object in a BaseModel object.

classmethod from_basemodel(source: ModelArtifact) → ModelArtifact

Create a new ModelArtifact object from a BaseModel object.

model_config: ClassVar[ConfigDict] = {'protected_namespaces': ()}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Parameters:

• self (BaseModel) – The BaseModel instance.

• context (Any) – The context.