modal 1.5.6.dev26__tar.gz → 1.5.6.dev27__tar.gz

{modal-1.5.6.dev26 → modal-1.5.6.dev27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.6.dev26
+Version: 1.5.6.dev27
 Summary: Python client library for Modal
 Author-email: Modal Labs <support@modal.com>
 License-Expression: Apache-2.0

{modal-1.5.6.dev26 → modal-1.5.6.dev27}/modal/__init__.py

@@ -16,6 +16,7 @@ try:
     from .client import Client
     from .cloud_bucket_mount import CloudBucketMount
     from .cls import Cls, parameter
+    from .cluster import Cluster
     from .dict import Dict
     from .environments import Environment
     from .exception import Error
@@ -33,6 +34,7 @@ try:
         exit,
         fastapi_endpoint,
         method,
+        sessioned,
         web_endpoint,
         web_server,
         wsgi_app,
@@ -62,6 +64,7 @@ __all__ = [
     "__version__",
     "App",
     "Client",
+    "Cluster",
     "Cls",
     "Cron",
     "Dict",
@@ -103,6 +106,7 @@ __all__ = [
     "interact",
     "method",
     "parameter",
+    "sessioned",
     "types",
     "web_endpoint",
     "web_server",

modal-1.5.6.dev27/modal/_cluster.py

@@ -0,0 +1,192 @@
+# Copyright Modal Labs 2026
+import os
+import socket
+from dataclasses import dataclass
+from typing import Literal, cast
+
+from google.protobuf.message import Message
+
+from modal_proto import api_pb2
+
+from ._load_context import LoadContext
+from ._object import _Object, live_method
+from ._resolver import Resolver
+from ._utils.async_utils import synchronize_api
+from .client import _Client
+from .exception import InvalidError
+
+
+@dataclass
+class ClusterContext:
+    """Cluster metadata and the executing container's rank, initialized at startup."""
+
+    rank: int
+    cluster_id: str
+    container_ips: list[str]
+    container_ipv4_ips: list[str]
+    fabric_ids: list[str]
+
+
+current_cluster_context: ClusterContext | None = None
+
+
+def get_current_cluster_context() -> ClusterContext:
+    """Return the executing container's initialized cluster context without an RPC."""
+    if current_cluster_context is None:
+        raise InvalidError(
+            "Cluster context is not initialized. This operation requires execution "
+            "inside a clustered Function or Server."
+        )
+    return current_cluster_context
+
+
+class _Cluster(_Object, type_prefix="cu"):
+    """A group of containers scheduled together for a clustered Function or Server.
+
+    Use `Cluster.from_context()` inside a cluster, or `Cluster.from_id()` to
+    inspect a cluster remotely. Containers are ordered by cluster rank.
+    """
+
+    _metadata: api_pb2.ClusterStats | None = None
+
+    def _hydrate_metadata(self, metadata: Message | None):
+        if metadata is not None:
+            assert isinstance(metadata, api_pb2.ClusterStats)
+            self._metadata = metadata
+
+    def _get_metadata(self) -> api_pb2.ClusterStats:
+        assert self._metadata is not None
+        return self._metadata
+
+    @staticmethod
+    def from_context() -> "_Cluster":
+        """Reference a Cluster from within one of its containers.
+
+        Raises `InvalidError` outside an initialized clustered execution.
+        """
+        context = get_current_cluster_context()
+        if not context.cluster_id:
+            raise InvalidError("The executing container does not have an initialized cluster ID.")
+        return _Cluster.from_id(context.cluster_id)
+
+    @staticmethod
+    def from_id(cluster_id: str, *, client: _Client | None = None) -> "_Cluster":
+        """Reference a Cluster by its ID.
+
+        Args:
+            cluster_id: ID of the cluster.
+            client: Modal client to use; defaults to `Client.from_env()` when omitted.
+
+        Examples:
+            ```python notest
+            cluster = modal.Cluster.from_id("cu-123")
+            ```
+        """
+
+        async def _load(self: _Cluster, resolver: Resolver, context: LoadContext, existing_object_id: str | None):
+            response = await context.client._stub.ClusterGet(api_pb2.ClusterGetRequest(cluster_id=cluster_id))
+            self._hydrate(cluster_id, context.client, response.cluster)
+
+        obj = _Cluster._from_loader(
+            _load,
+            f"modal.Cluster.from_id({cluster_id!r})",
+            hydrate_lazily=True,
+            load_context_overrides=LoadContext(client=client),
+        )
+        obj._object_id = cluster_id
+        return obj
+
+    @property
+    def object_id(self) -> str:
+        """The cluster's unique `cu-` object ID."""
+        return super().object_id
+
+    @live_method
+    async def container_ids(self) -> list[str]:
+        """Return container IDs ordered by cluster rank."""
+        return list(self._get_metadata().task_ids)
+
+    async def container_ips(self, family: Literal["ipv4", "ipv6"] = "ipv6") -> list[str]:
+        """Return container IP addresses ordered by cluster rank.
+
+        Returns IPv6 addresses by default; pass `family="ipv4"` for IPv4.
+        These addresses are for intra-cluster communication.
+
+        Must be called from a container in this cluster; otherwise raises `InvalidError`.
+        """
+        if family not in ("ipv4", "ipv6"):
+            raise InvalidError("family must be 'ipv4' or 'ipv6'.")
+        context = get_current_cluster_context()
+        if context.cluster_id != self.object_id:
+            raise InvalidError("container_ips() must be called from a container in the referenced cluster.")
+        return list(context.container_ipv4_ips if family == "ipv4" else context.container_ips)
+
+    async def container_rank(self, container_id: str | None = None) -> int:
+        """Return a container's rank within this cluster.
+
+        With no argument, return the executing container's rank without a network
+        request. Raises `InvalidError` if it is not a member of this cluster.
+
+        With an explicit container ID, look up its rank in the cluster's membership.
+        Raises `InvalidError` for nonmembers.
+        """
+        if container_id is None:
+            context = get_current_cluster_context()
+            if context.cluster_id != self.object_id:
+                raise InvalidError("The executing container is not a member of the referenced cluster.")
+            return context.rank
+
+        container_ids = await self.container_ids()
+        try:
+            return container_ids.index(container_id)
+        except ValueError:
+            raise InvalidError(f"Container {container_id!r} is not a member of cluster {self.object_id!r}.") from None
+
+
+async def _initialize_clustered_function(client: _Client, task_id: str):
+    global current_cluster_context
+
+    def get_i6pn() -> str:
+        """Returns the ipv6 address assigned to this container."""
+        # An AF_INET6 result always carries a (host, port, flowinfo, scope_id) sockaddr,
+        # but getaddrinfo is typed for every address family, some of which lead with an int
+        return cast(str, socket.getaddrinfo("i6pn.modal.local", None, socket.AF_INET6)[0][4][0])
+
+    hostname = socket.gethostname()
+    container_ip = get_i6pn()
+
+    # nccl's default host ID is $(hostname)$(cat /proc/sys/kernel/random/boot_id).
+    # on runc, if two i6pn-linked containers get scheduled on the same worker,
+    # their boot ID and hostname will both be identical, causing nccl to break.
+    # As a workaround, we can explicitly specify a unique host ID here.
+    # See MOD-4067.
+    os.environ["NCCL_HOSTID"] = f"{hostname}{container_ip}"
+
+    # We found these settings to work well in most cases. You may be able to achieve
+    # better performance by tuning these settings.
+    if os.environ["MODAL_CLOUD_PROVIDER"] in ("CLOUD_PROVIDER_GCP", "CLOUD_PROVIDER_OCI"):
+        os.environ["NCCL_SOCKET_NTHREADS"] = "4"
+        os.environ["NCCL_NSOCKS_PERTHREAD"] = "1"
+    elif os.environ["MODAL_CLOUD_PROVIDER"] == "CLOUD_PROVIDER_AWS":
+        os.environ["NCCL_SOCKET_NTHREADS"] = "2"
+        os.environ["NCCL_NSOCKS_PERTHREAD"] = "8"
+    else:
+        os.environ["NCCL_SOCKET_NTHREADS"] = "1"
+        os.environ["NCCL_NSOCKS_PERTHREAD"] = "1"
+
+    resp = await client._stub.TaskClusterHello(
+        api_pb2.TaskClusterHelloRequest(
+            task_id=task_id,
+            container_ip=container_ip,
+        ),
+    )
+    current_cluster_context = ClusterContext(
+        rank=resp.cluster_rank,
+        cluster_id=resp.cluster_id,
+        container_ips=list(resp.container_ips),
+        container_ipv4_ips=list(resp.container_ipv4_ips),
+        fabric_ids=list(resp.fabric_ids),
+    )
+
+
+initialize_clustered_function = synchronize_api(_initialize_clustered_function)

modal-1.5.6.dev27/modal/_cluster.pyi

@@ -0,0 +1,108 @@
+import google.protobuf.message
+import modal._object
+import modal.client
+import modal_proto.api_pb2
+import types
+import typing
+import typing_extensions
+
+class ClusterContext:
+    """Cluster metadata and the executing container's rank, initialized at startup."""
+
+    rank: int
+    cluster_id: str
+    container_ips: list[str]
+    container_ipv4_ips: list[str]
+    fabric_ids: list[str]
+
+    def __init__(
+        self, rank: int, cluster_id: str, container_ips: list[str], container_ipv4_ips: list[str], fabric_ids: list[str]
+    ) -> None:
+        """Initialize self.  See help(type(self)) for accurate signature."""
+        ...
+
+    def __repr__(self):
+        """Return repr(self)."""
+        ...
+
+    def __eq__(self, other):
+        """Return self==value."""
+        ...
+
+def get_current_cluster_context() -> ClusterContext:
+    """Return the executing container's initialized cluster context without an RPC."""
+    ...
+
+class _Cluster(modal._object._Object):
+    """A group of containers scheduled together for a clustered Function or Server.
+
+    Use `Cluster.from_context()` inside a cluster, or `Cluster.from_id()` to
+    inspect a cluster remotely. Containers are ordered by cluster rank.
+    """
+
+    _metadata: typing.Optional[modal_proto.api_pb2.ClusterStats]
+
+    def _hydrate_metadata(self, metadata: typing.Optional[google.protobuf.message.Message]): ...
+    def _get_metadata(self) -> modal_proto.api_pb2.ClusterStats: ...
+    @staticmethod
+    def from_context() -> _Cluster:
+        """Reference a Cluster from within one of its containers.
+
+        Raises `InvalidError` outside an initialized clustered execution.
+        """
+        ...
+
+    @staticmethod
+    def from_id(cluster_id: str, *, client: typing.Optional[modal.client._Client] = None) -> _Cluster:
+        """Reference a Cluster by its ID.
+
+        Args:
+            cluster_id: ID of the cluster.
+            client: Modal client to use; defaults to `Client.from_env()` when omitted.
+
+        Examples:
+            ```python notest
+            cluster = modal.Cluster.from_id("cu-123")
+            ```
+        """
+        ...
+
+    @property
+    def object_id(self) -> str:
+        """The cluster's unique `cu-` object ID."""
+        ...
+
+    async def container_ids(self) -> list[str]:
+        """Return container IDs ordered by cluster rank."""
+        ...
+
+    async def container_ips(self, family: typing.Literal["ipv4", "ipv6"] = "ipv6") -> list[str]:
+        """Return container IP addresses ordered by cluster rank.
+
+        Returns IPv6 addresses by default; pass `family="ipv4"` for IPv4.
+        These addresses are for intra-cluster communication.
+
+        Must be called from a container in this cluster; otherwise raises `InvalidError`.
+        """
+        ...
+
+    async def container_rank(self, container_id: typing.Optional[str] = None) -> int:
+        """Return a container's rank within this cluster.
+
+        With no argument, return the executing container's rank without a network
+        request. Raises `InvalidError` if it is not a member of this cluster.
+
+        With an explicit container ID, look up its rank in the cluster's membership.
+        Raises `InvalidError` for nonmembers.
+        """
+        ...
+
+async def _initialize_clustered_function(client: modal.client._Client, task_id: str): ...
+
+class __initialize_clustered_function_spec(typing_extensions.Protocol):
+    def __call__(self, /, client: modal.client.Client, task_id: str): ...
+    async def aio(self, /, client: modal.client.Client, task_id: str): ...
+
+initialize_clustered_function: __initialize_clustered_function_spec
+
+current_cluster_context: ClusterContext | None

{modal-1.5.6.dev26 → modal-1.5.6.dev27}/modal/_container_entrypoint.py

@@ -24,7 +24,7 @@ from typing import TYPE_CHECKING, Any, cast
 
 from google.protobuf.message import Message
 
-from modal._clustered_functions import initialize_clustered_function
+from modal._cluster import initialize_clustered_function
 from modal._runtime.user_code_event_loop import UserCodeEventLoop
 from modal._serialization import deserialize, deserialize_params
 from modal._utils.async_utils import TaskContext, aclosing, synchronizer
@@ -407,11 +407,7 @@ def run_server(container_args: api_pb2.ContainerArguments, client: Client):
     service: Service = hydrate_function(container_args, task_lifecycle_manager, function_def, _client)
     # Initialize clustered functions.
     if function_def._experimental_group_size > 0:
-        initialize_clustered_function(
-            client,
-            container_args.task_id,
-            function_def._experimental_group_size,
-        )
+        initialize_clustered_function(client, container_args.task_id)
 
     with UserCodeEventLoop() as event_loop:
         with service.lifecycle_context(
@@ -452,11 +448,7 @@ def run_function(container_args: api_pb2.ContainerArguments, client: Client):
 
         # Initialize clustered functions.
         if function_def._experimental_group_size > 0:
-            initialize_clustered_function(
-                client,
-                container_args.task_id,
-                function_def._experimental_group_size,
-            )
+            initialize_clustered_function(client, container_args.task_id)
 
         with service.function_execution_context(
             event_loop=event_loop,

{modal-1.5.6.dev26 → modal-1.5.6.dev27}/modal/_function_variants.py

@@ -1,12 +1,12 @@
 # Copyright Modal Labs 2026
+import copy
 import dataclasses
 from collections.abc import Collection, Sequence, Sized
 from pathlib import PurePosixPath
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypedDict
 
 import google.protobuf.message
 
-from modal.types import CloudBucketMountInfo, FunctionInfo, VolumeMountInfo
 from modal_proto import api_pb2
 
 from ._resources import convert_fn_config_to_resources_config
@@ -23,6 +23,7 @@ from .cloud_bucket_mount import _CloudBucketMount, cloud_bucket_mounts_to_proto
 from .exception import InvalidError
 from .retries import Retries
 from .secret import _Secret
+from .types import CloudBucketMountInfo, FunctionInfo, VolumeMountInfo
 from .volume import _Volume, _volume_to_mount_proto
 
 if TYPE_CHECKING:
@@ -441,7 +442,7 @@ def _make_function_variant(
             if options is not None:
                 function_variant._function_info = _get_function_info_with_options(base_function._function_info, options)
             else:
-                function_variant._function_info = base_function._function_info._get_copy()
+                function_variant._function_info = copy.deepcopy(base_function._function_info)
 
     def _deps():
         if options:
@@ -464,44 +465,67 @@ def _make_function_variant(
         if options is not None:
             fun._function_info = _get_function_info_with_options(base_function._function_info, options)
         else:
-            fun._function_info = base_function._function_info._get_copy()
+            fun._function_info = copy.deepcopy(base_function._function_info)
 
     return fun
 
 
+class _FunctionInfoArgsT(TypedDict, total=False):
+    cpu: float | tuple[float, float]
+    memory_mib: int | tuple[int, int]
+    gpus: list[tuple[str, int]]
+    ephemeral_disk_mib: int
+    timeout: int
+    max_retries: int
+    regions: list[str]
+    cloud: str
+    volumes: dict[str, VolumeMountInfo]
+    cloud_bucket_mounts: dict[str, CloudBucketMountInfo]
+    secrets: list[str]
+    routing_region: str
+    batching_info: FunctionInfo.BatchingInfo
+    concurrency_info: FunctionInfo.ConcurrencyInfo
+
+
 def _get_function_info_with_options(info: FunctionInfo, options: _FunctionOptions):
-    new_info = info._get_copy()
+    args: _FunctionInfoArgsT = {}
 
     if options.resources is not None:
         res = options.resources
         if res.milli_cpu_max > 0:
-            new_info.cpu = (res.milli_cpu / 1000, res.milli_cpu_max / 1000)
+            args["cpu"] = (res.milli_cpu / 1000, res.milli_cpu_max / 1000)
         elif res.milli_cpu > 0:
-            new_info.cpu = res.milli_cpu / 1000
+            args["cpu"] = res.milli_cpu / 1000
 
         if res.memory_mb_max > 0:
-            new_info.memory_mib = (res.memory_mb, res.memory_mb_max)
+            args["memory_mib"] = (res.memory_mb, res.memory_mb_max)
         elif res.memory_mb > 0:
-            new_info.memory_mib = res.memory_mb
+            args["memory_mib"] = res.memory_mb
 
         if res.HasField("gpu_config") and res.gpu_config.count > 0:
-            new_info.gpus = [(res.gpu_config.count, res.gpu_config.gpu_type)]
+            args["gpus"] = [(res.gpu_config.gpu_type, res.gpu_config.count)]
 
         if res.ephemeral_disk_mb > 0:
-            new_info.ephemeral_disk_mib = res.ephemeral_disk_mb
+            args["ephemeral_disk_mib"] = res.ephemeral_disk_mb
+
+    if options.timeout_secs is not None:
+        args["timeout"] = options.timeout_secs
+
+    if options.retry_policy is not None:
+        args["max_retries"] = options.retry_policy.retries
 
     if options.scheduler_placement is not None:
         sp = options.scheduler_placement
         # Note: not putting `nonpreemptible` here as that is not currently possible to set via
         # `.with_options(...)`
         if len(sp.regions) > 0:
-            new_info.regions = list(sp.regions)
+            args["regions"] = list(sp.regions)
 
     if options.cloud is not None:
-        new_info.cloud = options.cloud
+        args["cloud"] = options.cloud
 
     if len(options.validated_volumes) > 0:
-        new_info.volumes = {
+        args["volumes"] = {
             mount_path: VolumeMountInfo(vol._name, vol._object_id, False, None)
             if vol._mount_options is None
             else VolumeMountInfo(
@@ -514,16 +538,44 @@ def _get_function_info_with_options(info: FunctionInfo, options: _FunctionOption
         }
 
     if len(options.cloud_bucket_mounts) > 0:
-        new_info.cloud_bucket_mounts = {}
+        args["cloud_bucket_mounts"] = {}
         protos, _ = cloud_bucket_mounts_to_proto(options.cloud_bucket_mounts, include_secrets=False)
 
         for proto in protos:
-            new_info.cloud_bucket_mounts[proto.mount_path] = CloudBucketMountInfo._from_proto(proto)
+            args["cloud_bucket_mounts"][proto.mount_path] = CloudBucketMountInfo._from_proto(proto)
 
     if len(options.secrets) > 0:
-        new_info.secrets = [repr(s) for s in options.secrets]
+        args["secrets"] = [repr(s) for s in options.secrets]
 
     if options.routing_region:
-        new_info.routing_region = options.routing_region
+        args["routing_region"] = options.routing_region
+
+    if options.batch_max_size is not None and options.batch_wait_ms is not None:
+        args["batching_info"] = FunctionInfo.BatchingInfo(
+            max_batch_size=options.batch_max_size,
+            wait_ms=options.batch_wait_ms,
+        )
+
+    if options.max_concurrent_inputs is not None or options.target_concurrent_inputs is not None:
+        max_inputs = (
+            options.max_concurrent_inputs
+            if options.max_concurrent_inputs is not None
+            else info.concurrency_info.max_inputs
+            if info.concurrency_info is not None
+            else None
+        )
+
+        target_inputs = (
+            options.target_concurrent_inputs
+            if options.target_concurrent_inputs is not None
+            else info.concurrency_info.target_inputs
+            if info.concurrency_info is not None
+            else None
+        )
+
+        args["concurrency_info"] = FunctionInfo.ConcurrencyInfo(
+            max_inputs=max_inputs,
+            target_inputs=target_inputs,
+        )
 
-    return new_info
+    return dataclasses.replace(copy.deepcopy(info), **args)