viam-sdk 0.25.2__py3-none-linux_armv7l.whl → 0.62.0__py3-none-linux_armv7l.whl

viam/robot/service.py

@@ -1,5 +1,4 @@
-import asyncio
-from typing import Any, Dict, Iterable, List, Set
+from typing import Any, Dict, List, Set
 
 from grpclib.server import Stream
 
@@ -9,18 +8,12 @@ from viam.components.sensor import Sensor
 from viam.errors import ViamGRPCError
 from viam.proto.common import ResourceName
 from viam.proto.robot import (
-    GetStatusRequest,
-    GetStatusResponse,
     ResourceNamesRequest,
     ResourceNamesResponse,
-    Status,
     StopAllRequest,
     StopAllResponse,
-    StreamStatusRequest,
-    StreamStatusResponse,
     UnimplementedRobotServiceBase,
 )
-from viam.resource.registry import Registry
 from viam.resource.rpc_service_base import ResourceRPCServiceBase
 from viam.utils import resource_names_for_resource, struct_to_dict
 
@@ -33,34 +26,13 @@ class RobotService(UnimplementedRobotServiceBase, ResourceRPCServiceBase):
 
         for resource in self.manager.resources.values():
             # If the resource is a MovementSensor, DO NOT include Sensor as well (it will get added via MovementSensor)
-            if resource.SUBTYPE == Sensor.SUBTYPE and MovementSensor.get_resource_name(resource.name) in self.manager.resources:
+            if resource.API == Sensor.API and MovementSensor.get_resource_name(resource.name) in self.manager.resources:
                 continue
 
             md.update(resource_names_for_resource(resource))
 
         return list(md)
 
-    async def _generate_status(self, resource_names: Iterable[ResourceName]) -> List[Status]:
-        statuses: List[Status] = []
-        seen_resource_names: Set[ResourceName] = set()
-
-        for resource in self.manager.resources.values():
-            for registration in Registry.REGISTERED_SUBTYPES().values():
-                if isinstance(resource, registration.resource_type):
-                    if resource_names and resource.get_resource_name(resource.name) not in resource_names:
-                        continue
-                    try:
-                        status = await registration.create_status(resource)
-                        if status.name not in seen_resource_names:
-                            seen_resource_names.add(status.name)
-                            statuses.append(status)
-                    except ViamGRPCError as e:
-                        raise e.grpc_error
-
-        if resource_names:
-            statuses = [s for s in statuses if s.name in resource_names]
-        return statuses
-
     async def ResourceNames(self, stream: Stream[ResourceNamesRequest, ResourceNamesResponse]) -> None:
         request = await stream.recv_message()
         assert request is not None
@@ -68,26 +40,6 @@ class RobotService(UnimplementedRobotServiceBase, ResourceRPCServiceBase):
         response = ResourceNamesResponse(resources=metadata)
         await stream.send_message(response)
 
-    async def GetStatus(self, stream: Stream[GetStatusRequest, GetStatusResponse]) -> None:
-        request = await stream.recv_message()
-        assert request is not None
-        status = await self._generate_status(request.resource_names)
-        response = GetStatusResponse(status=status)
-        await stream.send_message(response)
-
-    async def StreamStatus(self, stream: Stream[StreamStatusRequest, StreamStatusResponse]) -> None:
-        request = await stream.recv_message()
-        assert request is not None
-        interval = 1
-        every = request.every.ToSeconds()
-        if every > 0:
-            interval = every
-        while True:
-            status = await self._generate_status(request.resource_names)
-            response = StreamStatusResponse(status=status)
-            await stream.send_message(response)
-            await asyncio.sleep(interval)
-
     async def StopAll(self, stream: Stream[StopAllRequest, StopAllResponse]) -> None:
         request = await stream.recv_message()
         assert request is not None

viam/rpc/dial.py

@@ -11,6 +11,7 @@ from typing import Callable, Literal, Optional, Tuple, Type, Union
 
 from grpclib.client import Channel, Stream
 from grpclib.const import Cardinality
+from grpclib.events import SendRequest, listen
 from grpclib.metadata import Deadline, _MetadataLike
 from grpclib.protocol import H2Protocol
 from grpclib.stream import _RecvType, _SendType
@@ -21,15 +22,16 @@ from viam.errors import InsecureConnectionError, ViamError
 from viam.proto.rpc.auth import AuthenticateRequest, AuthServiceStub
 from viam.proto.rpc.auth import Credentials as PBCredentials
 from viam.utils import to_thread
+from viam.version_metadata import API_VERSION, SDK_VERSION
 
 LOGGER = logging.getLogger(__name__)
 
 
 @dataclass
 class Credentials:
-    """Credentials to connect to the robot and the Viam app."""
+    """Credentials to connect to the machine and app.viam.com."""
 
-    type: Union[Literal["robot-location-secret"], Literal["robot-secret"], Literal["api-key"]]
+    type: Union[Literal["robot-secret"], Literal["api-key"]]
     """The type of credential
     """
 
@@ -68,6 +70,14 @@ class DialOptions:
     max_reconnect_attempts: int = 3
     """Max number of times the client attempts to reconnect when connection is lost"""
 
+    initial_connection_attempts: int = 3
+    """Max number of times the client will attempt to establish an initial connection
+    If set to a non-positive integer, then there will be no limit to initial connection attempts"""
+
+    initial_connection_attempt_timeout: float
+    """Number of seconds before dial connection times out on initial connection attempts
+    Defaults to whatever value is set in the `timeout` field"""
+
     timeout: float = 20
     """Number of seconds before the dial connection times out
     Set to 20sec to match _defaultOfferDeadline in goutils/rpc/wrtc_call_queue.go"""
@@ -83,6 +93,8 @@ class DialOptions:
         allow_insecure_with_creds_downgrade: bool = False,
         max_reconnect_attempts: int = 3,
         timeout: float = 20,
+        initial_connection_attempts: int = 3,
+        initial_connection_attempt_timeout: Optional[float] = None,
     ) -> None:
         self.disable_webrtc = disable_webrtc
         self.auth_entity = auth_entity
@@ -92,6 +104,8 @@ class DialOptions:
         self.allow_insecure_with_creds_downgrade = allow_insecure_with_creds_downgrade
         self.max_reconnect_attempts = max_reconnect_attempts
         self.timeout = timeout
+        self.initial_connection_attempts = initial_connection_attempts
+        self.initial_connection_attempt_timeout = initial_connection_attempt_timeout if initial_connection_attempt_timeout else timeout
 
     @classmethod
     def with_api_key(cls, api_key: str, api_key_id: str) -> Self:
@@ -218,8 +232,9 @@ class _Runtime:
     _ptr: ctypes.c_void_p
 
     def __init__(self) -> None:
+        suffix = "dylib" if sys.platform == "darwin" else "so" if "linux" in sys.platform else "dll"
         LOGGER.debug("Creating new viam-rust-utils runtime")
-        libname = pathlib.Path(__file__).parent.absolute() / f"libviam_rust_utils.{'dylib' if sys.platform == 'darwin' else 'so'}"
+        libname = pathlib.Path(__file__).parent.absolute() / f"libviam_rust_utils.{suffix}"
         self._lib = ctypes.CDLL(libname.__str__())
         self._lib.init_rust_runtime.argtypes = ()
         self._lib.init_rust_runtime.restype = ctypes.c_void_p
@@ -277,15 +292,50 @@ class _Runtime:
 
 
 async def dial(address: str, options: Optional[DialOptions] = None) -> ViamChannel:
+    options = options if options else DialOptions()
+    timeout = options.timeout
+    options.timeout = options.initial_connection_attempt_timeout
+    if options.initial_connection_attempts == 0:
+        options.initial_connection_attempts = -1
+    attempt_countdown = options.initial_connection_attempts
+    exception: Exception
+    while attempt_countdown != 0:
+        try:
+            chan = await _dial_inner(address, options)
+            options.timeout = timeout
+            return chan
+        except Exception as e:
+            exception = e
+            attempt_countdown -= 1
+    # the only way we could get here is if we failed at least once which means we've set the
+    # exception, so typechecker concerns about a possibly unbounded variable are unfounded
+    raise exception  # type: ignore
+
+
+def _create_chan(path: str) -> Channel:
+    if sys.platform == "win32" or sys.platform == "cygwin":
+        # we have to use a TCP connection, so we want a host and port for our channel.
+        host, port = _host_port_from_url(path)
+        return Channel(host=host, port=port, ssl=None)
+    # we're not on windows and so can use a UDS
+    return Channel(path=path, ssl=None)
+
+
+async def _dial_inner(address: str, options: Optional[DialOptions] = None) -> ViamChannel:
+    async def send_request(event: SendRequest):
+        event.metadata["viam-client"] = f"python;v{SDK_VERSION};v{API_VERSION}"
+
     opts = options if options else DialOptions()
     if opts.disable_webrtc:
         channel = await _dial_direct(address, options)
+        listen(channel, SendRequest, send_request)
         return ViamChannel(channel, lambda: None)
     runtime = _Runtime()
     path, path_ptr = await runtime.dial(address, opts)
     if path:
         LOGGER.info(f"Connecting to socket: {path}")
-        chan = Channel(path=path, ssl=None)
+        chan = _create_chan(path)
+        listen(chan, SendRequest, send_request)
 
         def release():
             runtime.free_str(path_ptr)

viam/rpc/server.py

@@ -1,3 +1,4 @@
+import sys
 from typing import TYPE_CHECKING, Callable, List, Optional
 
 from grpclib import GRPCError, Status
@@ -41,7 +42,7 @@ class Server(ResourceManager):
         super().__init__(resources)
 
         services = [SignalingService(), RobotService(manager=self)]
-        for registration in Registry.REGISTERED_SUBTYPES().values():
+        for registration in Registry.REGISTERED_APIS().values():
             if issubclass(registration.rpc_service, ResourceRPCServiceBase):
                 services.append(registration.rpc_service(manager=self))
             else:
@@ -82,6 +83,24 @@ class Server(ResourceManager):
 
         event.method_func = log_resource_name
 
+    async def _serve(
+        self,
+        host: Optional[str] = "localhost",
+        port: Optional[int] = 9090,
+        log_level: Optional[int] = logging.INFO,
+        *,
+        path: Optional[str] = None,
+    ):
+        if path:
+            await self._server.start(path=path)
+            LOGGER.info(f"Serving on {path}")
+        else:
+            await self._server.start(host, port)
+            LOGGER.info(f"Serving on {host}:{port}")
+        await self._server.wait_closed()
+        await self.close()
+        LOGGER.debug("gRPC server closed")
+
     async def serve(
         self,
         host: Optional[str] = "localhost",
@@ -105,16 +124,11 @@ class Server(ResourceManager):
             logging.setLevel(log_level)
         listen(self._server, RecvRequest, self._grpc_recvrequest_handler)
 
-        with graceful_exit([self._server]):
-            if path:
-                await self._server.start(path=path)
-                LOGGER.info(f"Serving on {path}")
-            else:
-                await self._server.start(host, port)
-                LOGGER.info(f"Serving on {host}:{port}")
-            await self._server.wait_closed()
-            await self.close()
-            LOGGER.debug("gRPC server closed")
+        if sys.platform != "win32":
+            with graceful_exit([self._server]):
+                await self._serve(host=host, port=port, log_level=log_level, path=path)
+        else:
+            await self._serve(host=host, port=port, log_level=log_level, path=path)
 
     @classmethod
     async def create_and_serve(

viam/rpc/types.py

@@ -14,11 +14,9 @@ class RPCServiceBase(IServable):
     """
 
     @abstractmethod
-    def __mapping__(self) -> Mapping[str, grpclib.const.Handler]:
-        ...
+    def __mapping__(self) -> Mapping[str, grpclib.const.Handler]: ...
 
 
 @runtime_checkable
 class RPCServiceStubBase(Protocol):
-    def __init__(self, channel: Channel) -> None:
-        ...
+    def __init__(self, channel: Channel) -> None: ...

viam/services/discovery/__init__.py

@@ -0,0 +1,12 @@
+from viam.resource.registry import Registry, ResourceRegistration
+from viam.services.discovery.service import DiscoveryRPCService
+
+from .client import DiscoveryClient
+from .discovery import Discovery
+
+__all__ = [
+    "DiscoveryClient",
+    "Discovery",
+]
+
+Registry.register_api(ResourceRegistration(Discovery, DiscoveryRPCService, lambda name, channel: DiscoveryClient(name, channel)))

viam/services/discovery/client.py

@@ -0,0 +1,55 @@
+from typing import Any, List, Mapping, Optional
+
+from grpclib.client import Channel
+
+from viam.proto.app.robot import ComponentConfig
+from viam.proto.common import DoCommandRequest, DoCommandResponse
+from viam.proto.service.discovery import (
+    DiscoverResourcesRequest,
+    DiscoverResourcesResponse,
+    DiscoveryServiceStub,
+)
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
+from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
+
+from .discovery import Discovery
+
+
+class DiscoveryClient(Discovery, ReconfigurableResourceRPCClientBase):
+    """
+    Connect to the Discovery service, which allows you to discover resources on a machine.
+    """
+
+    client: DiscoveryServiceStub
+
+    def __init__(self, name: str, channel: Channel):
+        super().__init__(name)
+        self.channel = channel
+        self.client = DiscoveryServiceStub(channel)
+
+    async def discover_resources(
+        self,
+        *,
+        extra: Optional[Mapping[str, Any]] = None,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> List[ComponentConfig]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DiscoverResourcesRequest(
+            name=self.name,
+            extra=dict_to_struct(extra),
+        )
+        response: DiscoverResourcesResponse = await self.client.DiscoverResources(request, timeout=timeout, metadata=md)
+        return list(response.discoveries)
+
+    async def do_command(
+        self,
+        command: Mapping[str, ValueTypes],
+        *,
+        timeout: Optional[float] = None,
+        **kwargs,
+    ) -> Mapping[str, ValueTypes]:
+        md = kwargs.get("metadata", self.Metadata()).proto
+        request = DoCommandRequest(name=self.name, command=dict_to_struct(command))
+        response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
+        return struct_to_dict(response.result)

viam/services/discovery/discovery.py

@@ -0,0 +1,52 @@
+import abc
+from typing import Final, List, Mapping, Optional
+
+from viam.proto.app.robot import ComponentConfig
+from viam.resource.types import API, RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE
+from viam.utils import ValueTypes
+
+from ..service_base import ServiceBase
+
+
+class Discovery(ServiceBase):
+    """
+    Discovery represents a Discovery service.
+
+    This acts as an abstract base class for any drivers representing specific
+    discovery implementations. This cannot be used on its own. If the ``__init__()`` function is
+    overridden, it must call the ``super().__init__()`` function.
+
+    """
+
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
+        RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "discovery"
+    )
+
+    @abc.abstractmethod
+    async def discover_resources(
+        self,
+        *,
+        extra: Optional[Mapping[str, ValueTypes]] = None,
+        timeout: Optional[float] = None,
+    ) -> List[ComponentConfig]:
+        """Get all component configs of discovered resources on a machine
+
+        ::
+
+            my_discovery = DiscoveryClient.from_robot(machine, "my_discovery")
+
+            # Get the discovered resources
+            result = await my_discovery.discover_resources(
+                "my_discovery",
+            )
+            discoveries = result.discoveries
+
+        Args:
+            name (str): The name of the discover service
+
+        Returns:
+            List[ComponentConfig]: A list of ComponentConfigs that describe
+            the components found by a discover service
+
+        """
+        ...

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

@@ -9,7 +9,7 @@ __all__ = [
     "Generic",
 ]
 
-Registry.register_subtype(
+Registry.register_api(
     ResourceRegistration(
         Generic,
         GenericRPCService,

viam/services/generic/client.py

@@ -5,7 +5,7 @@ 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
+from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase, ResourceRPCClientBase
 from viam.utils import ValueTypes, dict_to_struct, struct_to_dict
 
 from .generic import Generic
@@ -17,6 +17,7 @@ class GenericClient(Generic, ReconfigurableResourceRPCClientBase):
     """
 
     def __init__(self, name: str, channel: Channel):
+        self.channel = channel
         self.client = GenericServiceStub(channel)
         super().__init__(name)
 
@@ -25,11 +26,12 @@ class GenericClient(Generic, ReconfigurableResourceRPCClientBase):
         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)
+            response: DoCommandResponse = await self.client.DoCommand(request, timeout=timeout, metadata=md)
         except GRPCError as e:
             if e.status == Status.UNIMPLEMENTED:
                 raise NotImplementedError()
@@ -39,7 +41,7 @@ class GenericClient(Generic, ReconfigurableResourceRPCClientBase):
 
 
 async def do_command(
-    channel: Channel, name: str, command: Mapping[str, ValueTypes], *, timeout: Optional[float] = None
+    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
 
@@ -51,5 +53,6 @@ async def do_command(
     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)
+    return await client.do_command(command, timeout=timeout, metadata=md)

viam/services/generic/generic.py

@@ -1,6 +1,6 @@
 from typing import Final
 
-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 ..service_base import ServiceBase
 
@@ -53,6 +53,6 @@ class Generic(ServiceBase):
         service.val  # 5
     """
 
-    SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
         RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "generic"
     )

viam/services/mlmodel/__init__.py

@@ -21,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,4 +1,4 @@
-from typing import Dict, Optional
+from typing import Dict, Mapping, Optional
 
 from grpclib.client import Channel
 from numpy.typing import NDArray
@@ -6,6 +6,7 @@ from numpy.typing import NDArray
 from viam.proto.service.mlmodel import InferRequest, InferResponse, MetadataRequest, MetadataResponse, MLModelServiceStub
 from viam.resource.rpc_client_base import ReconfigurableResourceRPCClientBase
 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,12 +17,21 @@ class MLModelClient(MLModel, ReconfigurableResourceRPCClientBase):
         self.client = MLModelServiceStub(channel)
         super().__init__(name)
 
-    async def infer(self, input_tensors: Dict[str, NDArray], *, timeout: Optional[float] = None) -> Dict[str, NDArray]:
-        request = InferRequest(name=self.name, input_tensors=ndarrays_to_flat_tensors(input_tensors))
-        response: InferResponse = await self.client.Infer(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, *, timeout: Optional[float] = None) -> Metadata:
-        request = MetadataRequest(name=self.name)
-        response: MetadataResponse = await self.client.Metadata(request)
+    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

viam/services/mlmodel/mlmodel.py

@@ -1,10 +1,11 @@
 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
 
@@ -17,25 +18,35 @@ class MLModel(ServiceBase):
     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/services/ml/deploy/>`_.
+    For more information, see `ML model service <https://docs.viam.com/dev/reference/apis/services/ml/>`_.
     """
 
-    SUBTYPE: Final = Subtype(  # pyright: ignore [reportIncompatibleVariableOverride]
+    API: Final = API(  # pyright: ignore [reportIncompatibleVariableOverride]
         RESOURCE_NAMESPACE_RDK, RESOURCE_TYPE_SERVICE, "mlmodel"
     )
 
     @abc.abstractmethod
-    async def infer(self, input_tensors: Dict[str, NDArray], *, timeout: Optional[float]) -> Dict[str, NDArray]:
+    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=robot, name="my_mlmodel_service")
+            my_mlmodel = MLModelClient.from_robot(robot=machine, name="my_mlmodel_service")
 
-            nd_array = np.array([1, 2, 3], dtype=np.float64)
-            input_tensors = {"0": nd_array}
+            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)
 
@@ -45,23 +56,23 @@ class MLModel(ServiceBase):
         Returns:
             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/services/ml/deploy/>`_.
+        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=robot, name="my_mlmodel_service")
+            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/services/ml/deploy/>`_.
+        For more information, see `ML model service <https://docs.viam.com/dev/reference/apis/services/ml/#metadata>`_.
         """
         ...