modal 1.5.6.dev25__tar.gz → 1.5.6.dev27__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modal
-Version: 1.5.6.dev25
+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.dev25 → 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
@@ -23,16 +24,17 @@ try:
     from .functions import Function, FunctionCall
     from .image import Image
     from .network_file_system import NetworkFileSystem
-    from .outbound_policy import OutboundPolicy
     from .output import enable_output
     from .partial_function import (
         asgi_app,
         batched,
+        clustered,
         concurrent,
         enter,
         exit,
         fastapi_endpoint,
         method,
+        sessioned,
         web_endpoint,
         web_server,
         wsgi_app,
@@ -62,6 +64,7 @@ __all__ = [
     "__version__",
     "App",
     "Client",
+    "Cluster",
     "Cls",
     "Cron",
     "Dict",
@@ -72,7 +75,6 @@ __all__ = [
     "FunctionCall",
     "Image",
     "NetworkFileSystem",
-    "OutboundPolicy",
     "Period",
     "Probe",
     "Proxy",
@@ -90,6 +92,7 @@ __all__ = [
     "asgi_app",
     "batched",
     "billing",
+    "clustered",
     "concurrent",
     "current_function_call_id",
     "current_input_id",
@@ -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.dev25 → 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.dev25 → modal-1.5.6.dev27}/modal/_environments.py

@@ -4,7 +4,7 @@ import builtins
 from collections.abc import Iterable, Mapping
 from dataclasses import dataclass
 from datetime import datetime, timezone
-from typing import Any, Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from google.protobuf.empty_pb2 import Empty
 from google.protobuf.message import Message
@@ -24,6 +24,9 @@ from .config import config, logger
 from .exception import InvalidError, WorkspaceManagementError
 from .types import BillingReportItem, EnvironmentBillingSummary
 
+if TYPE_CHECKING:
+    import modal
+
 
 @dataclass(frozen=True)
 class EnvironmentSettings:
@@ -59,7 +62,7 @@ class _EnvironmentManager:
             request.default_member_role_str = default_role
         if (experimental_options or {}).get("is_public", False):
             request.environment_type = api_pb2.ENVIRONMENT_TYPE_PUBLIC
-        await client.stub.EnvironmentCreate(request)
+        await client._stub.EnvironmentCreate(request)
 
     async def list(
         self,
@@ -76,7 +79,7 @@ class _EnvironmentManager:
         ```
         """
         client = await _Client.from_env() if client is None else client
-        resp = await client.stub.EnvironmentList(Empty())
+        resp = await client._stub.EnvironmentList(Empty())
         environments = []
         for item in resp.items:
             metadata = api_pb2.EnvironmentMetadata(
@@ -110,7 +113,7 @@ class _EnvironmentManager:
         ```
         """
         client = await _Client.from_env() if client is None else client
-        await client.stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
+        await client._stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
 
 
 class _EnvironmentRolesManager:
@@ -139,7 +142,7 @@ class _EnvironmentRolesManager:
         """
         await self._environment.hydrate()
         req = api_pb2.EnvironmentGetRolesRequest(environment_id=self._environment.object_id)
-        resp = await self._environment.client.stub.EnvironmentGetRoles(req)
+        resp = await self._environment.client._stub.EnvironmentGetRoles(req)
 
         users: dict[str, str] = {}
         service_users: dict[str, str] = {}
@@ -180,7 +183,7 @@ class _EnvironmentRolesManager:
         service_users = service_users or {}
 
         req = api_pb2.EnvironmentGetRolesRequest(environment_id=self._environment.object_id)
-        resp = await self._environment.client.stub.EnvironmentGetRoles(req)
+        resp = await self._environment.client._stub.EnvironmentGetRoles(req)
 
         # EnvironmentGetRoles returns every workspace principal
         user_name_to_id: dict[str, str] = {}
@@ -214,7 +217,7 @@ class _EnvironmentRolesManager:
     async def _dispatch_role_updates(self, requests: dict[str, api_pb2.EnvironmentRoleSetRequest]) -> None:
         """Send batched EnvironmentRoleSet RPCs and report all errors encountered."""
         results = await asyncio.gather(
-            *(self._environment.client.stub.EnvironmentRoleSet(req) for req in requests.values()),
+            *(self._environment.client._stub.EnvironmentRoleSet(req) for req in requests.values()),
             return_exceptions=True,
         )
         errors = [(label, result) for label, result in zip(requests.keys(), results) if isinstance(result, Exception)]
@@ -269,7 +272,7 @@ class _EnvironmentMembersManager:
         service_users = service_users or []
 
         req = api_pb2.EnvironmentGetRolesRequest(environment_id=self._environment.object_id)
-        resp = await self._environment.client.stub.EnvironmentGetRoles(req)
+        resp = await self._environment.client._stub.EnvironmentGetRoles(req)
 
         user_name_to_id: dict[str, str] = {}
         service_user_name_to_id: dict[str, str] = {}
@@ -300,6 +303,55 @@ class _EnvironmentMembersManager:
         await _EnvironmentRolesManager(self._environment)._dispatch_role_updates(requests)
 
 
+class _EnvironmentAppsManager:
+    """mdmd:namespace"""
+
+    def __init__(self, environment: "_Environment"):
+        """mdmd:hidden"""
+        self._environment = environment
+
+    async def list(self) -> builtins.list["modal.app._App"]:
+        """Return handles for live Apps in this Environment.
+
+        The returned handles reference existing remote Apps and can be used with APIs such as
+        [`App.info()`](https://modal.com/docs/sdk/py/latest/App#info),
+        [`App.logs`](https://modal.com/docs/sdk/py/latest/App#logs), and
+        [`Sandbox.create()`](https://modal.com/docs/sdk/py/latest/Sandbox#create). Listing Apps does not create
+        Apps.
+
+        Examples:
+
+        ```python notest
+        environment = modal.Environment.from_name("prod")
+        apps = environment.apps.list()
+        print([app.name for app in apps])
+        ```
+        """
+        from .app import _App
+
+        await self._environment.hydrate()
+        assert self._environment.name is not None
+
+        response = await self._environment.client._stub.AppList(
+            api_pb2.AppListRequest(environment_name=self._environment.name)
+        )
+        stopped_app_states = (
+            api_pb2.APP_STATE_STOPPED,
+            api_pb2.APP_STATE_DISABLED,
+        )
+        return [
+            _App._new_remote(
+                item.name or None,
+                item.app_id,
+                self._environment.name,
+                self._environment.client,
+                description=item.description or None,
+            )
+            for item in response.apps
+            if item.state not in stopped_app_states
+        ]
+
+
 class _Environment(_Object, type_prefix="en"):
     _name: str | None = None
     _settings: EnvironmentSettings
@@ -334,6 +386,11 @@ class _Environment(_Object, type_prefix="en"):
         # Deprecated alias for `Environment.roles`.
         return _EnvironmentMembersManager(self)
 
+    @property
+    def apps(self) -> "_EnvironmentAppsManager":
+        """Namespace for accessing Apps deployed in this Environment."""
+        return _EnvironmentAppsManager(self)
+
     # TODO(michael) Keeping this private for now until we decide what else should be in it
     # And what the rules should be about updates / mutability
     # @property
@@ -366,7 +423,7 @@ class _Environment(_Object, type_prefix="en"):
                     else api_pb2.OBJECT_CREATION_TYPE_UNSPECIFIED
                 ),
             )
-            response = await load_context.client.stub.EnvironmentGetOrCreate(request)
+            response = await load_context.client._stub.EnvironmentGetOrCreate(request)
             logger.debug(f"Created environment with id {response.environment_id}")
             self._hydrate(response.environment_id, load_context.client, response.metadata)
 
@@ -491,7 +548,7 @@ class _EnvironmentBillingManager:
 
         return [
             BillingReportItem._from_proto(pb_item)
-            async for pb_item in self._environment.client.stub.WorkspaceBillingReport.unary_stream(request)
+            async for pb_item in self._environment.client._stub.WorkspaceBillingReport.unary_stream(request)
         ]
 
     async def summary(
@@ -556,7 +613,7 @@ class _EnvironmentBillingManager:
         request.start_timestamp.FromDatetime(cycle)
 
         return EnvironmentBillingSummary._from_proto(
-            await self._environment.client.stub.EnvironmentBillingSummary(request)
+            await self._environment.client._stub.EnvironmentBillingSummary(request)
         )
 
 
@@ -582,7 +639,7 @@ async def _get_environment_cached(name: str, client: _Client) -> _Environment:
 async def _delete_environment(name: str, client: _Client | None = None):
     if client is None:
         client = await _Client.from_env()
-    await client.stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
+    await client._stub.EnvironmentDelete(api_pb2.EnvironmentDeleteRequest(name=name))
 
 
 async def _update_environment(
@@ -608,19 +665,19 @@ async def _update_environment(
     )
     if client is None:
         client = await _Client.from_env()
-    await client.stub.EnvironmentUpdate(update_payload)
+    await client._stub.EnvironmentUpdate(update_payload)
 
 
 async def _create_environment(name: str, client: _Client | None = None):
     if client is None:
         client = await _Client.from_env()
-    await client.stub.EnvironmentCreate(api_pb2.EnvironmentCreateRequest(name=name))
+    await client._stub.EnvironmentCreate(api_pb2.EnvironmentCreateRequest(name=name))
 
 
 async def _list_environments(client: _Client | None = None) -> list[api_pb2.EnvironmentListItem]:
     if client is None:
         client = await _Client.from_env()
-    resp = await client.stub.EnvironmentList(Empty())
+    resp = await client._stub.EnvironmentList(Empty())
     return list(resp.items)