viam.app.ml_training_client
===========================

.. py:module:: viam.app.ml_training_client


Attributes
----------

.. autoapisummary::

   viam.app.ml_training_client.LOGGER


Classes
-------

.. autoapisummary::

   viam.app.ml_training_client.MLTrainingClient


Module Contents
---------------

.. py:data:: LOGGER

.. py:class:: MLTrainingClient(channel: grpclib.client.Channel, metadata: Mapping[str, str])

   gRPC client for working with ML training jobs.

   Constructor is used by `ViamClient` to instantiate relevant service stubs.
   Calls to `MLTrainingClient` methods should be made through `ViamClient`.

   Establish a Connection::

       import asyncio

       from viam.rpc.dial import DialOptions, Credentials
       from viam.app.viam_client import ViamClient


       async def connect() -> ViamClient:
           # Replace "<API-KEY>" (including brackets) with your API key and "<API-KEY-ID>" with your API key ID
           dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
           return await ViamClient.create_from_dial_options(dial_options)


       async def main():

           # Make a ViamClient
           async with await connect() as viam_client:
               # Instantiate an MLTrainingClient to run ML training client API methods on
               ml_training_client = viam_client.ml_training_client

       if __name__ == '__main__':
           asyncio.run(main())

   For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/>`_.


   .. py:method:: submit_training_job(org_id: str, dataset_id: str, model_name: str, model_version: str, model_type: viam.proto.app.mltraining.ModelType.ValueType, tags: List[str]) -> str
      :async:


      Submit a training job.

      ::

          from viam.proto.app.mltraining import ModelType

          job_id = await ml_training_client.submit_training_job(
              org_id="<organization-id>",
              dataset_id="<dataset-id>",
              model_name="<your-model-name>",
              model_version="1",
              model_type=ModelType.MODEL_TYPE_SINGLE_LABEL_CLASSIFICATION,
              tags=["tag1", "tag2"]
          )

      :param org_id: the ID of the org to submit the training job to.
      :type org_id: str
      :param dataset_id: the ID of the dataset to train the model on.
      :type dataset_id: str
      :param model_name: the model name.
      :type model_name: str
      :param model_version: the model version.
      :type model_version: str
      :param model_type: the model type.
      :type model_type: ModelType.ValueType
      :param tags: the labels to train the model on.
      :type tags: List[str]

      :returns: the ID of the training job.
      :rtype: str

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submittrainingjob>`_.



   .. py:method:: submit_custom_training_job(org_id: str, dataset_id: str, registry_item_id: str, registry_item_version: str, model_name: str, model_version: str, container_id: str = '') -> str
      :async:


      Submit a custom training job.

      ::

          job_id = await ml_training_client.submit_custom_training_job(
              org_id="<organization-id>",
              dataset_id="<dataset-id>",
              registry_item_id="viam:classification-tflite",
              registry_item_version="2024-08-13T12-11-54",
              model_name="<your-model-name>",
              model_version="1"
          )

      :param org_id: the ID of the org to submit the training job to.
      :type org_id: str
      :param dataset_id: the ID of the dataset to train the model on.
      :type dataset_id: str
      :param registry_item_id: the ID of the training script from the registry.
      :type registry_item_id: str
      :param registry_item_version: the version of the training script from the registry.
      :type registry_item_version: str
      :param model_name: the model name.
      :type model_name: str
      :param model_version: the model version.
      :type model_version: str
      :param container_id: the ID of the custom training container to run the job in. If unspecified, the training script's
                           default container is used.
      :type container_id: str

      :returns: the ID of the training job.
      :rtype: str

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submitcustomtrainingjob>`_.



   .. py:method:: get_training_job(id: str) -> viam.proto.app.mltraining.TrainingJobMetadata
      :async:


      Gets training job data.

      ::

          job_metadata = await ml_training_client.get_training_job(
              id="<job-id>")

      :param id: the ID of the requested training job.
      :type id: str

      :returns: the training job data.
      :rtype: viam.proto.app.mltraining.TrainingJobMetadata

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#gettrainingjob>`_.



   .. py:method:: list_training_jobs(org_id: str, training_status: Optional[viam.proto.app.mltraining.TrainingStatus.ValueType] = None) -> List[viam.proto.app.mltraining.TrainingJobMetadata]
      :async:


      Returns training job data for all jobs within an org.

      ::

          jobs_metadata = await ml_training_client.list_training_jobs(
              org_id="<org-id>")

          first_job_id = jobs_metadata[1].id

      :param org_id: the ID of the org to request training job data from.
      :type org_id: str
      :param training_status: the status to filter the training jobs list by.
                              If unspecified, all training jobs will be returned.
      :type training_status: Optional[TrainingStatus]

      :returns: the list of training job data.
      :rtype: List[viam.proto.app.mltraining.TrainingJobMetadata]

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#listtrainingjobs>`_.



   .. py:method:: cancel_training_job(id: str) -> None
      :async:


      Cancels the specified training job.

      ::

          await ml_training_client.cancel_training_job(
              id="<job-id>")

      :param id: the ID of the job to cancel.
      :type id: str

      :raises GRPCError: if no training job exists with the given ID.

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#canceltrainingjob>`_.



   .. py:method:: delete_completed_training_job(id: str) -> None
      :async:


      Delete a completed training job from the database, whether the job succeeded or failed.

      ::

          await ml_training_client.delete_completed_training_job(
              id="<job-id>")

      :param id: the ID of the training job to delete.
      :type id: str

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#deletecompletedtrainingjob>`_.



   .. py:method:: list_containers(org_id: str) -> List[viam.proto.app.mltraining.Container]
      :async:


      List the training containers available to an organization.

      ::

          containers = await ml_training_client.list_containers(
              org_id="<organization-id>")

      :param org_id: the ID of the org to list available training containers for.
      :type org_id: str

      :returns: the list of available training containers.
      :rtype: List[viam.proto.app.mltraining.Container]

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#listcontainers>`_.



   .. py:method:: get_container(id: str) -> viam.proto.app.mltraining.Container
      :async:


      Get a training container by ID.

      ::

          container = await ml_training_client.get_container(
              id="<container-id>")

      :param id: the ID of the requested training container.
      :type id: str

      :returns: the training container.
      :rtype: viam.proto.app.mltraining.Container

      For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#getcontainer>`_.



   .. py:method:: register_custom_training_container(org_id: str, image_uri: str, description: str) -> str
      :async:


      Register a custom training container for an organization.

      ::

          container_id = await ml_training_client.register_custom_training_container(
              org_id="<organization-id>",
              image_uri="docker.io/library/my-training-image:latest",
              description="<my-training-container>"
          )

      :param org_id: the ID of the org to register the custom training container to.
      :type org_id: str
      :param image_uri: the Docker Hub reference of the training container image.
      :type image_uri: str
      :param description: a description of the training container, used as its display name. Must not be empty.
      :type description: str

      :returns: the ID of the registered training container.
      :rtype: str

      For more information, see
      `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#registercustomtrainingcontainer>`_.



   .. py:method:: delete_custom_training_container(id: str) -> None
      :async:


      Delete a custom training container.

      ::

          await ml_training_client.delete_custom_training_container(
              id="<container-id>")

      :param id: the ID of the custom training container to delete.
      :type id: str

      For more information, see
      `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#deletecustomtrainingcontainer>`_.