viam-sdk 0.45.2__py3-none-win_amd64.whl

viam/app/ml_training_client.py

@@ -0,0 +1,251 @@
+from typing import List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam import logging
+from viam.proto.app.mltraining import (
+    CancelTrainingJobRequest,
+    DeleteCompletedTrainingJobRequest,
+    GetTrainingJobRequest,
+    GetTrainingJobResponse,
+    ListTrainingJobsRequest,
+    ListTrainingJobsResponse,
+    MLTrainingServiceStub,
+    ModelType,
+    SubmitCustomTrainingJobRequest,
+    SubmitCustomTrainingJobResponse,
+    SubmitTrainingJobRequest,
+    SubmitTrainingJobResponse,
+    TrainingJobMetadata,
+    TrainingStatus,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+class MLTrainingClient:
+    """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
+            viam_client = await connect()
+            # Instantiate an MLTrainingClient to run ML training client API methods on
+            ml_training_client = viam_client.ml_training_client
+
+            viam_client.close()
+
+        if __name__ == '__main__':
+            asyncio.run(main())
+
+    For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/>`_.
+    """
+
+    def __init__(self, channel: Channel, metadata: Mapping[str, str]):
+        """Create a `MLTrainingClient` that maintains a connection to app.
+
+        Args:
+            channel (grpclib.client.Channel): Connection to app.
+            metadata (Mapping[str, str]): Required authorization token to send requests to app.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/>`_.
+        """
+        self._metadata = metadata
+        self._ml_training_client = MLTrainingServiceStub(channel)
+        self._channel = channel
+
+    async def submit_training_job(
+        self,
+        org_id: str,
+        dataset_id: str,
+        model_name: str,
+        model_version: str,
+        model_type: ModelType.ValueType,
+        tags: List[str],
+    ) -> str:
+        """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"]
+            )
+
+        Args:
+            org_id (str): the ID of the org to submit the training job to.
+            dataset_id (str): the ID of the dataset to train the model on.
+            model_name (str): the model name.
+            model_version (str): the model version.
+            model_type (ModelType.ValueType): the model type.
+            tags (List[str]): the labels to train the model on.
+
+        Returns:
+            str: the ID of the training job.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submittrainingjob>`_.
+        """
+
+        request = SubmitTrainingJobRequest(
+            dataset_id=dataset_id,
+            organization_id=org_id,
+            model_name=model_name,
+            model_version=model_version,
+            model_type=model_type,
+            tags=tags,
+        )
+        response: SubmitTrainingJobResponse = await self._ml_training_client.SubmitTrainingJob(request, metadata=self._metadata)
+        return response.id
+
+    async def submit_custom_training_job(
+        self, org_id: str, dataset_id: str, registry_item_id: str, registry_item_version: str, model_name: str, model_version: str
+    ) -> str:
+        """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"
+            )
+
+        Args:
+            org_id (str): the ID of the org to submit the training job to.
+            dataset_id (str): the ID of the dataset to train the model on.
+            registry_item_id (str): the ID of the training script from the registry.
+            registry_item_version (str): the version of the training script from the registry.
+            model_name (str): the model name.
+            model_version (str): the model version.
+
+        Returns:
+            str: the ID of the training job.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#submitcustomtrainingjob>`_.
+        """
+
+        request = SubmitCustomTrainingJobRequest(
+            dataset_id=dataset_id,
+            registry_item_id=registry_item_id,
+            registry_item_version=registry_item_version,
+            organization_id=org_id,
+            model_name=model_name,
+            model_version=model_version,
+        )
+        response: SubmitCustomTrainingJobResponse = await self._ml_training_client.SubmitCustomTrainingJob(request, metadata=self._metadata)
+        return response.id
+
+    async def get_training_job(self, id: str) -> TrainingJobMetadata:
+        """Gets training job data.
+
+        ::
+
+            job_metadata = await ml_training_client.get_training_job(
+                id="<job-id>")
+
+        Args:
+            id (str): the ID of the requested training job.
+
+        Returns:
+            viam.proto.app.mltraining.TrainingJobMetadata: the training job data.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#gettrainingjob>`_.
+        """
+
+        request = GetTrainingJobRequest(id=id)
+        response: GetTrainingJobResponse = await self._ml_training_client.GetTrainingJob(request, metadata=self._metadata)
+
+        return response.metadata
+
+    async def list_training_jobs(
+        self,
+        org_id: str,
+        training_status: Optional[TrainingStatus.ValueType] = None,
+    ) -> List[TrainingJobMetadata]:
+        """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
+
+        Args:
+            org_id (str): the ID of the org to request training job data from.
+            training_status (Optional[TrainingStatus]): the status to filter the training jobs list by.
+                If unspecified, all training jobs will be returned.
+
+        Returns:
+            List[viam.proto.app.mltraining.TrainingJobMetadata]: the list of training job data.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#listtrainingjobs>`_.
+        """
+
+        training_status = training_status if training_status else TrainingStatus.TRAINING_STATUS_UNSPECIFIED
+        request = ListTrainingJobsRequest(organization_id=org_id, status=training_status)
+        response: ListTrainingJobsResponse = await self._ml_training_client.ListTrainingJobs(request, metadata=self._metadata)
+
+        return list(response.jobs)
+
+    async def cancel_training_job(self, id: str) -> None:
+        """Cancels the specified training job.
+
+        ::
+
+            await ml_training_client.cancel_training_job(
+                id="<job-id>")
+
+        Args:
+            id (str): the ID of the job to cancel.
+
+        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>`_.
+        """
+
+        request = CancelTrainingJobRequest(id=id)
+        await self._ml_training_client.CancelTrainingJob(request, metadata=self._metadata)
+
+    async def delete_completed_training_job(self, id: str) -> None:
+        """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>")
+
+        Args:
+            id (str): the ID of the training job to delete.
+
+        For more information, see `ML Training Client API <https://docs.viam.com/dev/reference/apis/ml-training-client/#deletecompletedtrainingjob>`_.
+        """
+        request = DeleteCompletedTrainingJobRequest(id=id)
+        await self._ml_training_client.DeleteCompletedTrainingJob(request, metadata=self._metadata)

viam/app/provisioning_client.py

@@ -0,0 +1,95 @@
+from typing import List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam import logging
+from viam.proto.provisioning import (
+    CloudConfig,
+    GetNetworkListRequest,
+    GetNetworkListResponse,
+    GetSmartMachineStatusRequest,
+    GetSmartMachineStatusResponse,
+    NetworkInfo,
+    ProvisioningServiceStub,
+    SetNetworkCredentialsRequest,
+    SetSmartMachineCredentialsRequest,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+class ProvisioningClient:
+    """gRPC client for getting and setting smart machine info.
+
+    Constructor is used by `ViamClient` to instantiate relevant service stubs. Calls to
+    `ProvisioningClient` 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
+            viam_client = await connect()
+            # Instantiate a ProvisioningClient to run provisioning client API methods on
+            provisioning_client = viam_client.provisioning_client
+
+            viam_client.close()
+
+        if __name__ == '__main__':
+            asyncio.run(main())
+
+    """
+
+    def __init__(self, channel: Channel, metadata: Mapping[str, str]):
+        """Create a `ProvisioningClient` that maintains a connection to app.
+
+        Args:
+            channel (grpclib.client.Channel): Connection to app.
+            metadata (Mapping[str, str]): Required authorization token to send requests to app.
+        """
+        self._metadata = metadata
+        self._provisioning_client = ProvisioningServiceStub(channel)
+        self._channel = channel
+
+    _provisioning_client: ProvisioningServiceStub
+    _metadata: Mapping[str, str]
+    _channel: Channel
+
+    async def get_network_list(self) -> List[NetworkInfo]:
+        """Returns list of networks that are visible to the Smart Machine."""
+        request = GetNetworkListRequest()
+        resp: GetNetworkListResponse = await self._provisioning_client.GetNetworkList(request, metadata=self._metadata)
+        return list(resp.networks)
+
+    async def get_smart_machine_status(self) -> GetSmartMachineStatusResponse:
+        """Returns the status of the smart machine."""
+        request = GetSmartMachineStatusRequest()
+        return await self._provisioning_client.GetSmartMachineStatus(request, metadata=self._metadata)
+
+    async def set_network_credentials(self, network_type: str, ssid: str, psk: str) -> None:
+        """Sets the network credentials of the Smart Machine.
+
+        Args:
+            network_type (str): The type of the network.
+            ssid (str): The SSID of the network.
+            psk (str): The network's passkey.
+        """
+
+        request = SetNetworkCredentialsRequest(type=network_type, ssid=ssid, psk=psk)
+        await self._provisioning_client.SetNetworkCredentials(request, metadata=self._metadata)
+
+    async def set_smart_machine_credentials(self, cloud_config: Optional[CloudConfig] = None) -> None:
+        request = SetSmartMachineCredentialsRequest(cloud=cloud_config)
+        await self._provisioning_client.SetSmartMachineCredentials(request, metadata=self._metadata)

viam/app/viam_client.py

@@ -0,0 +1,260 @@
+import os
+from typing import Mapping, Optional
+
+from grpclib.client import Channel
+from typing_extensions import Self
+
+from viam import logging
+from viam.app.app_client import AppClient
+from viam.app.billing_client import BillingClient
+from viam.app.data_client import DataClient
+from viam.app.ml_training_client import MLTrainingClient
+from viam.app.provisioning_client import ProvisioningClient
+from viam.robot.client import RobotClient
+from viam.rpc.dial import Credentials, DialOptions, _dial_app, _get_access_token
+
+LOGGER = logging.getLogger(__name__)
+
+
+class ViamClient:
+    """gRPC client for all communication and interaction with app.
+
+    `ViamClient` class for creating and managing specialized client instances.
+    There is currently 1 way to instantiate a `ViamClient` object::
+
+        ViamClient.create_from_dial_options(...)
+    """
+
+    @classmethod
+    async def create_from_env_vars(cls, dial_options: Optional[DialOptions] = None, app_url: Optional[str] = None) -> Self:
+        """Create `ViamClient` using credentials set in the environment as `VIAM_API_KEY` and `VIAM_API_KEY_ID`.
+
+        ::
+
+            client = await ViamClient.create_from_env_vars()
+
+        Args:
+            dial_options (Optional[viam.rpc.dial.DialOptions]): Options for authorization and connection to app.
+                If not provided, default options will be selected. Note that `creds` and `auth_entity`
+                fields will be overwritten by the values set by a module.
+            app_url: (Optional[str]): URL of app. Uses app.viam.com if not specified.
+
+        Raises:
+            ValueError: If there are no env vars set by the module, or if they are set improperly
+
+        """
+        dial_options = dial_options if dial_options else DialOptions()
+        api_key = os.environ.get("VIAM_API_KEY")
+        if api_key is None:
+            raise ValueError("api key cannot be None")
+        api_key_id = os.environ.get("VIAM_API_KEY_ID")
+        if api_key_id is None:
+            raise ValueError("api key ID cannot be None")
+        credentials = Credentials(type="api-key", payload=api_key)
+        dial_options.credentials = credentials
+        dial_options.auth_entity = api_key_id
+
+        return await cls.create_from_dial_options(dial_options, app_url)
+
+    @classmethod
+    async def create_from_dial_options(cls, dial_options: DialOptions, app_url: Optional[str] = None) -> Self:
+        """Create `ViamClient` that establishes a connection to the Viam app.
+
+        ::
+
+            dial_options = DialOptions.with_api_key("<API-KEY>", "<API-KEY-ID>")
+            client = await ViamClient.create_from_dial_options(dial_options)
+
+        Args:
+            dial_options (viam.rpc.dial.DialOptions): Required information for authorization and connection to app.
+                `creds` and `auth_entity` fields are required.
+            app_url: (Optional[str]): URL of app. Uses app.viam.com if not specified.
+
+        Raises:
+            ValueError: If the input parameters are missing a required field or simply invalid.
+
+        Returns:
+            Self: The `ViamClient`.
+        """
+        if dial_options.credentials is None:
+            raise ValueError("dial_options.credentials cannot be None.")
+        if dial_options.credentials.type == "robot-secret":
+            raise ValueError("dial_options.credentials.type cannot be 'robot-secret'")
+        if dial_options.auth_entity is None:
+            raise ValueError("dial_options.auth_entity cannot be None.")
+
+        self = cls()
+        self._dial_options = dial_options
+        self._location_id = None
+        if dial_options.credentials.type == "robot-location-secret":
+            self._location_id = dial_options.auth_entity.split(".")[1]
+        if app_url is None:
+            app_url = "app.viam.com"
+        self._channel = await _dial_app(app_url)
+        access_token = await _get_access_token(self._channel, dial_options.auth_entity, dial_options)
+        self._metadata = {"authorization": f"Bearer {access_token}"}
+        return self
+
+    _channel: Channel
+    _metadata: Mapping[str, str]
+    _closed: bool = False
+    _location_id: Optional[str]
+    _dial_options: DialOptions
+
+    @property
+    def data_client(self) -> DataClient:
+        """Instantiate and return a `DataClient` object used to make `data` and `data_sync` method calls.
+        To use the `DataClient`, you must first instantiate a `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():
+                viam_client = await connect()
+
+                # Instantiate a DataClient to run data client API methods on
+                data_client = viam_client.data_client
+        """
+        return DataClient(self._channel, self._metadata)
+
+    @property
+    def app_client(self) -> AppClient:
+        """Instantiate and return an `AppClient` used to make  `app` method calls.
+        To use the `AppClient`, you must first instantiate a `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():
+                viam_client = await connect()
+
+                # Instantiate an AppClient called "fleet" to run fleet management API methods on
+                fleet = viam_client.app_client
+        """
+        return AppClient(self._channel, self._metadata, self._location_id)
+
+    @property
+    def ml_training_client(self) -> MLTrainingClient:
+        """Instantiate and return a `MLTrainingClient` used to make `ml_training` method calls.
+        To use the `MLTrainingClient`, you must first instantiate a `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():
+                viam_client = await connect()
+
+                # Instantiate an MLTrainingClient to run ML training client API methods on
+                ml_training_client = viam_client.ml_training_client
+        """
+        return MLTrainingClient(self._channel, self._metadata)
+
+    @property
+    def billing_client(self) -> BillingClient:
+        """Instantiate and return a `BillingClient` used to make `billing` method calls.
+            To use the `BillingClient`, you must first instantiate a `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():
+                viam_client = await connect()
+
+                # Instantiate a BillingClient to run billing client API methods on
+                billing_client = viam_client.billing_client
+        """
+
+        return BillingClient(self._channel, self._metadata)
+
+    @property
+    def provisioning_client(self) -> ProvisioningClient:
+        """Instantiate and return a `ProvisioningClient` used to make  `provisioning` method calls.
+        To use the `ProvisioningClient`, you must first instantiate a `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():
+                viam_client = await connect()
+
+                # Instantiate a ProvisioningClient to run provisioning API methods on
+                provisioning_client = viam_client.provisioning_client
+        """
+        return ProvisioningClient(self._channel, self._metadata)
+
+    def close(self):
+        """Close opened channels used for the various service stubs initialized."""
+        if self._closed:
+            LOGGER.debug("ViamClient is already closed.")
+            return
+        LOGGER.debug("Closing gRPC channel to app.")
+        self._channel.close()
+        self._closed = True
+
+    async def connect_to_machine(self, *, address: Optional[str] = None, id: Optional[str] = None) -> RobotClient:
+        """Connect to a machine using existing credentials.
+
+        A connection can be attempted using either the machine's address or its ID.
+        If both an address and ID are provided, the address will take precedence and the ID will be ignored.
+
+        ::
+
+            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():
+                viam_client = await connect()
+
+                # Connect to a machine and obtain a RobotClient
+                # Replace "<MACHINE_ADDRESS>" (including brackets) with your machine's connection address
+                machine = await viam_client.connect_to_machine(address="<MACHINE_ADDRESS>")
+
+        Args:
+            address (Optional[str]): The address (FQDN) of the machine. Defaults to None.
+            id (Optional[str]): The ID (as a UUID) of the machine. Defaults to None.
+
+        Raises:
+            ValueError: If neither an address nor ID is provided.
+
+        Returns:
+            RobotClient: The active connection to the machine.
+        """
+        if address is None and id is None:
+            raise ValueError("Either a machine address or ID must be provided")
+
+        if id is not None and address is None:
+            parts = await self.app_client.get_robot_parts(id)
+            main_part = next(p for p in parts if p.main_part)
+            address = main_part.fqdn
+
+        opts = RobotClient.Options(dial_options=self._dial_options)
+
+        assert address is not None
+        return await RobotClient.at_address(address, opts)

viam/components/arm/__init__.py

@@ -0,0 +1,16 @@
+from viam.proto.common import KinematicsFileFormat, Pose
+from viam.proto.component.arm import JointPositions
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .arm import Arm
+from .client import ArmClient
+from .service import ArmRPCService
+
+__all__ = [
+    "Arm",
+    "JointPositions",
+    "KinematicsFileFormat",
+    "Pose",
+]
+
+Registry.register_api(ResourceRegistration(Arm, ArmRPCService, lambda name, channel: ArmClient(name, channel)))