viam-sdk 0.3.0__py3-none-linux_armv6l.whl → 0.66.0__py3-none-linux_armv6l.whl

viam/services/discovery/service.py

@@ -0,0 +1,43 @@
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.discovery import (
+    DiscoverResourcesRequest,
+    DiscoverResourcesResponse,
+    UnimplementedDiscoveryServiceBase,
+)
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+from .discovery import Discovery
+
+
+class DiscoveryRPCService(UnimplementedDiscoveryServiceBase, ResourceRPCServiceBase):
+    """
+    gRPC service for a Discovery service
+    """
+
+    RESOURCE_TYPE = Discovery
+
+    async def DiscoverResources(self, stream: Stream[DiscoverResourcesRequest, DiscoverResourcesResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        discovery = self.get_resource(request.name)
+        extra = struct_to_dict(request.extra)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await discovery.discover_resources(
+            extra=extra,
+            timeout=timeout,
+        )
+        response = DiscoverResourcesResponse(
+            discoveries=result,
+        )
+        await stream.send_message(response)
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        discovery = self.get_resource(request.name)
+        timeout = stream.deadline.time_remaining() if stream.deadline else None
+        result = await discovery.do_command(struct_to_dict(request.command), timeout=timeout)
+        await stream.send_message(DoCommandResponse(result=dict_to_struct(result)))

viam/services/generic/__init__.py

@@ -0,0 +1,18 @@
+import viam.gen.service.generic.v1.generic_pb2  # Need this import for Generic service descriptors to resolve
+from viam.resource.registry import Registry, ResourceRegistration
+
+from .client import GenericClient
+from .generic import Generic
+from .service import GenericRPCService
+
+__all__ = [
+    "Generic",
+]
+
+Registry.register_api(
+    ResourceRegistration(
+        Generic,
+        GenericRPCService,
+        lambda name, channel: GenericClient(name, channel),
+    )
+)

viam/services/generic/client.py

@@ -0,0 +1,58 @@
+from typing import Any, Mapping, Optional
+
+from grpclib import GRPCError, Status
+from grpclib.client import Channel
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.generic import GenericServiceStub
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+
+from .generic import Generic
+
+
+class GenericClient(Generic, ReconfigurableResourceRPCClientBase):
+    """
+    gRPC client for the Generic service.
+    """
+
+    def __init__(self, name: str, channel: Channel):
+        self.channel = channel
+        self.client = GenericServiceStub(channel)
+        super().__init__(name)
+
+    async def do_command(
+        self,
+        command: Mapping[str, Any],
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Mapping[str, Any]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DoCommandRequest(name=self.name, command=dict_to_struct(command))
+        try:
+            response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
+        except GRPCError as e:
+            if e.status == Status.UNIMPLEMENTED:
+                raise NotImplementedError()
+            raise e
+
+        return struct_to_dict(response.result)
+
+
+async def do_command(
+    channel: Channel, name: str, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs
+) -> Mapping[str, ValueTypes]:
+    """Convenience method to allow service clients to execute ``do_command`` functions
+
+    Args:
+        channel (Channel): A gRPC channel
+        name (str): The name of the component
+        command (Dict[str, Any]): The command to execute
+
+    Returns:
+        Dict[str, Any]: The result of the executed command
+    """
+    md = kwargs.get("metadata", ResourceRPCClientBase.Metadata()).proto
+    client = GenericClient(name, channel)
+    return await client.do_command(command, timeout=timeout, metadata=md)

viam/services/generic/generic.py

@@ -0,0 +1,58 @@
+from typing import Final
+
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
+
+from ..service_base import ServiceBase
+
+
+class Generic(ServiceBase):
+    """
+    Generic service, which represents any type of service that can execute arbitrary commands
+
+    This acts as an abstract base class for any drivers representing generic services.
+    This cannot be used on its own. If the ``__init__()`` function is overridden, it must call the ``super().__init__()`` function.
+
+    To create a Generic service (an arbitrary service that can process commands), this ``Generic`` service should be subclassed
+    and the ``do_command`` function implemented.
+
+    Example::
+
+        class ComplexService(Generic):
+
+            async def do_command(
+                self,
+                command: Mapping[str, ValueTypes],
+                *,
+                timeout: Optional[float] = None,
+                **kwargs
+            ) -> Mapping[str, ValueTypes]:
+                result = {key: False for key in command.keys()}
+                for (name, args) in command.items():
+                    if name == 'set_val':
+                        self.set_val(*args)
+                        result[name] = True
+                    if name == 'get_val':
+                        result[name] = self.val
+                    if name == 'complex_command':
+                        self.complex_command(*args)
+                        result[name] = True
+                return result
+
+            def set_val(self, val: int):
+                self.val = val
+
+            def complex_command(self, arg1, arg2, arg3):
+                ...
+
+    To execute commands, simply call the ``do_command`` function with the appropriate parameters.
+    ::
+
+        await service.do_command({'set_val': 10})
+        service.val  # 10
+        await service.do_command({'set_val': 5})
+        service.val  # 5
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "generic"
+    )

viam/services/generic/service.py

@@ -0,0 +1,29 @@
+from grpclib import GRPCError, Status
+from grpclib.server import Stream
+
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.generic import GenericServiceBase
+from viam.resource.rpc_service_base import ResourceRPCServiceBase
+from viam.services.service_base import ServiceBase
+from viam.utils import dict_to_struct, struct_to_dict
+
+
+class GenericRPCService(GenericServiceBase, ResourceRPCServiceBase):
+    """
+    gRPC Service for a Generic service
+    """
+
+    RESOURCE_TYPE = ServiceBase
+
+    async def DoCommand(self, stream: Stream[DoCommandRequest, DoCommandResponse]) -> None:
+        request = await stream.recv_message()
+        assert request is not None
+        name = request.name
+        service = self.get_resource(name)
+        try:
+            timeout = stream.deadline.time_remaining() if stream.deadline else None
+            result = await service.do_command(struct_to_dict(request.command), timeout=timeout, metadata=stream.metadata)
+        except NotImplementedError:
+            raise GRPCError(Status.UNIMPLEMENTED, f"``DO`` command is unimplemented for service named: {name}")
+        response = DoCommandResponse(result=dict_to_struct(result))
+        await stream.send_message(response)

viam/services/mlmodel/__init__.py

@@ -1,3 +1,17 @@
+try:
+    import numpy
+except ImportError:
+    import warnings
+
+    warnings.warn(
+        (
+            """MLModel support in the Viam Python SDK requires the installation of an
+additional dependency: numpy.  Update your package using the extra [mlmodel]
+for example `pip install viam-sdk[mlmodel]` or the equivalent update in your dependency manager."""
+        ),
+    )
+    raise
+
 from viam.proto.service.mlmodel import File, LabelType, Metadata, TensorInfo
 from viam.resource.registry import Registry, ResourceRegistration
 
@@ -7,4 +21,4 @@ from .service import MLModelRPCService
 
 __all__ = ["File", "LabelType", "Metadata", "MLModel", "MLModelClient", "TensorInfo"]
 
-Registry.register_subtype(ResourceRegistration(MLModel, MLModelRPCService, lambda name, channel: MLModelClient(name, channel)))
+Registry.register_api(ResourceRegistration(MLModel, MLModelRPCService, lambda name, channel: MLModelClient(name, channel)))

viam/services/mlmodel/client.py

@@ -1,11 +1,12 @@
 from typing import Dict, Mapping, Optional
 
 from grpclib.client import Channel
+from numpy.typing import NDArray
 
-from viam.proto.common import DoCommandRequest, DoCommandResponse
 from viam.proto.service.mlmodel import InferRequest, InferResponse, MetadataRequest, MetadataResponse, MLModelServiceStub
 from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
-from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+from viam.services.mlmodel.utils import flat_tensors_to_ndarrays, ndarrays_to_flat_tensors
+from viam.utils import ValueTypes, dict_to_struct
 
 from .mlmodel import Metadata, MLModel
 
@@ -16,17 +17,21 @@ class MLModelClient(MLModel, ReconfigurableResourceRPCClientBase):
         self.client = MLModelServiceStub(channel)
         super().__init__(name)
 
-    async def infer(self, input_data: Dict[str, ValueTypes], *, timeout: Optional[float] = None) -> Dict[str, ValueTypes]:
-        request = InferRequest(name=self.name, input_data=dict_to_struct(input_data))
-        response: InferResponse = await self.client.Infer(request)
-        return struct_to_dict(response.output_data)
-
-    async def metadata(self, *, timeout: Optional[float] = None) -> Metadata:
-        request = MetadataRequest(name=self.name)
-        response: MetadataResponse = await self.client.Metadata(request)
+    async def infer(
+        self,
+        input_tensors: Dict[str, NDArray],
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Dict[str, NDArray]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = InferRequest(name=self.name, input_tensors=ndarrays_to_flat_tensors(input_tensors), extra=dict_to_struct(extra))
+        response: InferResponse = await self.client.Infer(request, timeout=timeout, metadata=md)
+        return flat_tensors_to_ndarrays(response.output_tensors)
+
+    async def metadata(self, *, extra: Optional[Mapping[str, ValueTypes]] = None, timeout: Optional[float] = None, **kwargs) -> Metadata:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = MetadataRequest(name=self.name, extra=dict_to_struct(extra))
+        response: MetadataResponse = await self.client.Metadata(request, timeout=timeout, metadata=md)
         return response.metadata
-
-    async def do_command(self, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None, **kwargs) -> Mapping[str, ValueTypes]:
-        request = DoCommandRequest(name=self.name, command=dict_to_struct(command))
-        response: DoCommandResponse = await self.client.DoCommand(request, tiemout=timeout)
-        return struct_to_dict(response.result)

viam/services/mlmodel/mlmodel.py

@@ -1,8 +1,10 @@
 import abc
-from typing import Dict, Final, Optional
+from typing import Dict, Final, Mapping, Optional
+
+from numpy.typing import NDArray
 
 from viam.proto.service.mlmodel import Metadata
-from viam.resource.types import RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, Subtype
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
 from viam.utils import ValueTypes
 
 from ..service_base import ServiceBase
@@ -15,27 +17,62 @@ class MLModel(ServiceBase):
     This acts as an abstract base class for any drivers representing specific
     arm implementations. This cannot be used on its own. If the ``__init__()`` function is
     overridden, it must call the ``super().__init__()`` function.
+
+    For more information, see `ML model service <https://docs.viam.com/dev/reference/apis/services/ml/>`_.
     """
 
-    SUBTYPE: Final = Subtype(RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "mlmodel")
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "mlmodel"
+    )
 
     @abc.abstractmethod
-    async def infer(self, input_data: Dict[str, ValueTypes], *, timeout: Optional[float]) -> Dict[str, ValueTypes]:
+    async def infer(
+        self,
+        input_tensors: Dict[str, NDArray],
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, NDArray]:
         """Take an already ordered input tensor as an array, make an inference on the model, and return an output tensor map.
 
+        ::
+
+            import numpy as np
+
+            my_mlmodel = MLModelClient.from_robot(robot=machine, name="my_mlmodel_service")
+
+            image_data = np.zeros((1, 384, 384, 3), dtype=np.uint8)
+
+            # Create the input tensors dictionary
+            input_tensors = {
+                "image": image_data
+            }
+
+            output_tensors = await my_mlmodel.infer(input_tensors)
+
         Args:
-            input_data (Dict[str, ValueTypes]): A dictionary of input arrays/tensors as specified in the metadata
+            input_tensors (Dict[str, NDArray]): A dictionary of input flat tensors as specified in the metadata
 
         Returns:
-            Dict[str, ValueTypes]: A dictionary of output arrays/tensors as specified in the metadata
+            Dict[str, NDArray]: A dictionary of output flat tensors as specified in the metadata
+
+        For more information, see `ML model service <https://docs.viam.com/dev/reference/apis/services/ml/#infer>`_.
         """
         ...
 
     @abc.abstractmethod
-    async def metadata(self, *, timeout: Optional[float]) -> Metadata:
+    async def metadata(self, *, extra: Optional[Mapping[str, ValueTypes]] = None, timeout: Optional[float] = None) -> Metadata:
         """Get the metadata (such as name, type, expected tensor/array shape, inputs, and outputs) associated with the ML model.
 
+        ::
+
+            my_mlmodel = MLModelClient.from_robot(robot=machine, name="my_mlmodel_service")
+
+            metadata = await my_mlmodel.metadata()
+
         Returns:
             Metadata: The metadata
+
+        For more information, see `ML model service <https://docs.viam.com/dev/reference/apis/services/ml/#metadata>`_.
         """
         ...

viam/services/mlmodel/service.py

@@ -1,9 +1,9 @@
 from grpclib.server import Stream
 
-from viam.errors import ResourceNotFoundError
 from viam.proto.service.mlmodel import InferRequest, InferResponse, MetadataRequest, MetadataResponse, MLModelServiceBase
 from viam.resource.rpc_service_base import ResourceRPCServiceBase
-from viam.utils import dict_to_struct
+from viam.services.mlmodel.utils import flat_tensors_to_ndarrays, ndarrays_to_flat_tensors
+from viam.utils import struct_to_dict
 
 from .mlmodel import MLModel
 
@@ -19,24 +19,20 @@ class MLModelRPCService(MLModelServiceBase, ResourceRPCServiceBase):
         request = await stream.recv_message()
         assert request is not None
         name = request.name
-        try:
-            mlmodel = self.get_resource(name)
-        except ResourceNotFoundError as e:
-            raise e.grpc_error
+        mlmodel = self.get_resource(name)
+        extra = struct_to_dict(request.extra)
         timeout = stream.deadline.time_remaining() if stream.deadline else None
-        output_data = await mlmodel.infer(input_data=request.input_data, timeout=timeout)
-        response = InferResponse(output_data=dict_to_struct(output_data))
+        output_tensors = await mlmodel.infer(input_tensors=flat_tensors_to_ndarrays(request.input_tensors), extra=extra, timeout=timeout)
+        response = InferResponse(output_tensors=ndarrays_to_flat_tensors(output_tensors))
         await stream.send_message(response)
 
     async def Metadata(self, stream: Stream[MetadataRequest, MetadataResponse]) -> None:
         request = await stream.recv_message()
         assert request is not None
         name = request.name
-        try:
-            mlmodel = self.get_resource(name)
-        except ResourceNotFoundError as e:
-            raise e.grpc_error
+        mlmodel = self.get_resource(name)
+        extra = struct_to_dict(request.extra)
         timeout = stream.deadline.time_remaining() if stream.deadline else None
-        metadata = await mlmodel.metadata(timeout=timeout)
+        metadata = await mlmodel.metadata(extra=extra, timeout=timeout)
         response = MetadataResponse(metadata=metadata)
         await stream.send_message(response)

viam/services/mlmodel/utils.py

@@ -0,0 +1,101 @@
+from typing import Dict
+
+import numpy as np
+from numpy.typing import NDArray
+from packaging.version import Version
+
+from viam.proto.service.mlmodel import (
+    FlatTensor,
+    FlatTensorDataDouble,
+    FlatTensorDataFloat,
+    FlatTensorDataInt8,
+    FlatTensorDataInt16,
+    FlatTensorDataInt32,
+    FlatTensorDataInt64,
+    FlatTensorDataUInt8,
+    FlatTensorDataUInt16,
+    FlatTensorDataUInt32,
+    FlatTensorDataUInt64,
+    FlatTensors,
+)
+
+
+def flat_tensors_to_ndarrays(flat_tensors: FlatTensors) -> Dict[str, NDArray]:
+    property_name_to_dtype = {
+        "float_tensor": np.float32,
+        "double_tensor": np.float64,
+        "int8_tensor": np.int8,
+        "int16_tensor": np.int16,
+        "int32_tensor": np.int32,
+        "int64_tensor": np.int64,
+        "uint8_tensor": np.uint8,
+        "uint16_tensor": np.uint16,
+        "uint32_tensor": np.uint32,
+        "uint64_tensor": np.uint64,
+    }
+
+    def make_ndarray(flat_data, dtype, shape):
+        """Takes flat data (protobuf RepeatedScalarFieldContainer | bytes) to output an ndarray
+        of appropriate dtype and shape"""
+        make_array = np.frombuffer if dtype == np.int8 or dtype == np.uint8 else np.array
+        # As per proto, int16 and uint16 are stored as uint32. As of numpy v2, this creates
+        # some strange interactions with negative values for int16. Specifically, we end up
+        # trying to create an np.Int16 value with an out of bounds int due to rollover.
+        # Creating our array as a uint32 array initially and then casting to int16 solves this.
+        if Version(np.__version__) >= Version("2") and dtype == np.int16:
+            arr = np.astype(make_array(flat_data, np.uint32), np.int16)  # pyright: ignore [reportAttributeAccessIssue]
+
+        else:
+            arr = make_array(flat_data, dtype)
+        return arr.reshape(shape)
+
+    ndarrays: Dict[str, NDArray] = dict()
+    for name, flat_tensor in flat_tensors.tensors.items():
+        property_name = flat_tensor.WhichOneof("tensor") or flat_tensor.WhichOneof(b"tensor")
+        if property_name:
+            tensor_data = getattr(flat_tensor, property_name)
+            flat_data, dtype, shape = tensor_data.data, property_name_to_dtype[property_name], flat_tensor.shape
+            ndarrays[name] = make_ndarray(flat_data, dtype, shape)
+    return ndarrays
+
+
+def ndarrays_to_flat_tensors(ndarrays: Dict[str, NDArray]) -> FlatTensors:
+    dtype_name_to_tensor_data_class = {
+        "float32": FlatTensorDataFloat,
+        "float64": FlatTensorDataDouble,
+        "int8": FlatTensorDataInt8,
+        "int16": FlatTensorDataInt16,
+        "int32": FlatTensorDataInt32,
+        "int64": FlatTensorDataInt64,
+        "uint8": FlatTensorDataUInt8,
+        "uint16": FlatTensorDataUInt16,
+        "uint32": FlatTensorDataUInt32,
+        "uint64": FlatTensorDataUInt64,
+    }
+
+    def get_tensor_data(ndarray: NDArray):
+        """Takes an ndarray and returns the corresponding tensor data class instance
+        for example FlatTensorDataInt8, FlatTensorDataUInt8 etc."""
+        tensor_data_class = dtype_name_to_tensor_data_class[ndarray.dtype.name]
+        data = ndarray.flatten()
+        if tensor_data_class == FlatTensorDataInt8 or tensor_data_class == FlatTensorDataUInt8:
+            data = data.tobytes()  # as per the proto, int8 and uint8 are stored as bytes
+        elif tensor_data_class == FlatTensorDataInt16 or tensor_data_class == FlatTensorDataUInt16:
+            data = data.astype(np.uint32)  # as per the proto, int16 and uint16 are stored as uint32
+        tensor_data = tensor_data_class(data=data)
+        return tensor_data
+
+    def get_tensor_data_type(ndarray: NDArray):
+        """Takes ndarray and returns a FlatTensor datatype property to be set
+        for example "float_tensor", "uint32_tensor" etc."""
+        if ndarray.dtype == np.float32:
+            return "float_tensor"
+        elif ndarray.dtype == np.float64:
+            return "double_tensor"
+        return f"{ndarray.dtype.name}_tensor"
+
+    tensors_mapping: Dict[str, FlatTensor] = dict()
+    for name, ndarray in ndarrays.items():
+        prop_name, prop_value = get_tensor_data_type(ndarray), get_tensor_data(ndarray)
+        tensors_mapping[name] = FlatTensor(shape=ndarray.shape, **{prop_name: prop_value})
+    return FlatTensors(tensors=tensors_mapping)

viam/services/motion/__init__.py

@@ -1,5 +1,17 @@
+from viam.proto.service.motion import Constraints, MotionConfiguration
+from viam.resource.registry import Registry, ResourceRegistration
+
 from .client import MotionClient
+from .motion import Motion
+from .service import MotionRPCService
+
+__all__ = ["Motion", "MotionClient", "MotionConfiguration", "Constraints"]
+
 
-__all__ = [
-    "MotionClient",
-]
+Registry.register_api(
+    ResourceRegistration(
+        Motion,
+        MotionRPCService,
+        lambda name, channel: MotionClient(name, channel),
+    )
+)