modal 1.6.4.dev1__tar.gz → 1.6.4.dev2__tar.gz

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/PKG-INFO

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

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal/app.py

@@ -3,6 +3,7 @@ import inspect
 import typing
 from collections.abc import AsyncGenerator, Callable, Collection, Coroutine, Mapping, Sequence
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from pathlib import PurePosixPath
 from textwrap import dedent
 from typing import (
@@ -56,7 +57,7 @@ from .retries import Retries
 from .running_app import RunningApp
 from .schedule import Schedule
 from .secret import _Secret
-from .types import AppInfo
+from .types import AppInfo, SandboxGroupStats
 from .volume import _Volume
 
 _default_image: _Image = _Image.debian_slim()
@@ -135,6 +136,82 @@ class _LocalAppState:
     volumes_default: dict[str | PurePosixPath, _Volume]
 
 
+class _AppSandboxesManager:
+    """mdmd:namespace"""
+
+    def __init__(self, app: "_App"):
+        """mdmd:hidden"""
+        self._app = app
+
+    async def stats(
+        self,
+        *,
+        since: datetime,
+        until: datetime | None = None,
+        group_by_tags: Sequence[str] | None = None,
+        tags: dict[str, str] | None = None,
+    ) -> AsyncGenerator[SandboxGroupStats, None]:
+        """Return statistics for this App's Sandboxes over a time range, optionally grouped by tag values.
+
+        The maximum time range is 7 days.
+
+        Args:
+            since: The beginning of the time range, inclusive, on a UTC hour boundary. Values without a
+                timezone are interpreted as local time.
+            until: The end of the time range, exclusive, on a UTC hour boundary. If omitted, this defaults to
+                the current time. Values without a timezone are interpreted as local time.
+            group_by_tags: Tag names to group by. Sandboxes with the same values for these names form one group;
+                a name not present on a Sandbox counts as `None`. If omitted, all matching Sandboxes are returned
+                as a single group.
+            tags: Only include Sandboxes that have at least these tags.
+
+        Yields:
+            `SandboxGroupStats` objects, one per combination of tag values, with the following fields:
+            - `tags`: the value of each name in `group_by_tags` for the group's Sandboxes, `None` where not present.
+            - `cost`: total cost in USD, the sum of `cost_by_resource`.
+            - `cost_by_resource`: cost in USD by billed resource: `CPU`, `Memory`, and GPU types such as
+              `H100`. The resource names are subject to change as Modal's billing model evolves.
+
+        Raises:
+            InvalidError: If the time range is invalid or there are more than 10,000 groups.
+
+        Examples:
+            ```python notest
+            app = modal.App.lookup("my-app")
+            since = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0) - timedelta(days=1)
+            for group in app.sandboxes.stats(since=since, group_by_tags=["team"]):
+                print(group.tags, group.cost, group.cost_by_resource)
+            ```
+        """
+        if self._app._app_id is None:
+            raise InvalidError("`App.sandboxes.stats` requires a running, deployed or looked-up App.")
+        if until is not None:
+            if until.tzinfo is None:
+                until = until.astimezone()
+            until = until.astimezone(timezone.utc)
+        if since.tzinfo is None:
+            since = since.astimezone()
+        since = since.astimezone(timezone.utc)
+        if since >= datetime.now(timezone.utc):
+            raise InvalidError("`since` must be in the past.")
+        if until is not None and since >= until:
+            raise InvalidError("`since` must be before `until`.")
+        client = self._app._client or await _Client.from_env()
+        request = api_pb2.SandboxGetTimeRangeStatsRequest(
+            group_by_tags=list(group_by_tags or []), tags=tags or {}, app_id=self._app._app_id
+        )
+        request.since.FromDatetime(since)
+        if until is not None:
+            request.until.FromDatetime(until)
+        while True:
+            response = await client._stub.SandboxGetTimeRangeStats(request)
+            for group in response.groups:
+                yield SandboxGroupStats._from_proto(group)
+            if not response.next_page_token:
+                return
+            request.page_token = response.next_page_token
+
+
 class _App:
     """A Modal App is a group of functions and classes that are deployed together.
 
@@ -1679,6 +1756,11 @@ class _App:
 
         return _AppLogsManager(self)
 
+    @property
+    def sandboxes(self) -> _AppSandboxesManager:
+        """Namespace for the Sandboxes belonging to this App."""
+        return _AppSandboxesManager(self)
+
     async def info(self, refresh: bool = False) -> AppInfo:
         """Return information for a modal `App`.
 
@@ -1711,4 +1793,5 @@ class _App:
         return self._info
 
 
+AppSandboxesManager = synchronize_api(_AppSandboxesManager)
 App = synchronize_api(_App)

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal/app.pyi

@@ -1,4 +1,5 @@
 import collections.abc
+import datetime
 import modal._functions
 import modal._image
 import modal._load_context
@@ -115,6 +116,54 @@ class _LocalAppState:
         """Return self==value."""
         ...
 
+class _AppSandboxesManager:
+    """mdmd:namespace"""
+    def __init__(self, app: _App):
+        """mdmd:hidden"""
+        ...
+
+    def stats(
+        self,
+        *,
+        since: datetime.datetime,
+        until: typing.Optional[datetime.datetime] = None,
+        group_by_tags: typing.Optional[collections.abc.Sequence[str]] = None,
+        tags: typing.Optional[dict[str, str]] = None,
+    ) -> collections.abc.AsyncGenerator[modal.types.SandboxGroupStats, None]:
+        """Return statistics for this App's Sandboxes over a time range, optionally grouped by tag values.
+
+        The maximum time range is 7 days.
+
+        Args:
+            since: The beginning of the time range, inclusive, on a UTC hour boundary. Values without a
+                timezone are interpreted as local time.
+            until: The end of the time range, exclusive, on a UTC hour boundary. If omitted, this defaults to
+                the current time. Values without a timezone are interpreted as local time.
+            group_by_tags: Tag names to group by. Sandboxes with the same values for these names form one group;
+                a name not present on a Sandbox counts as `None`. If omitted, all matching Sandboxes are returned
+                as a single group.
+            tags: Only include Sandboxes that have at least these tags.
+
+        Yields:
+            `SandboxGroupStats` objects, one per combination of tag values, with the following fields:
+            - `tags`: the value of each name in `group_by_tags` for the group's Sandboxes, `None` where not present.
+            - `cost`: total cost in USD, the sum of `cost_by_resource`.
+            - `cost_by_resource`: cost in USD by billed resource: `CPU`, `Memory`, and GPU types such as
+              `H100`. The resource names are subject to change as Modal's billing model evolves.
+
+        Raises:
+            InvalidError: If the time range is invalid or there are more than 10,000 groups.
+
+        Examples:
+            ```python notest
+            app = modal.App.lookup("my-app")
+            since = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0) - timedelta(days=1)
+            for group in app.sandboxes.stats(since=since, group_by_tags=["team"]):
+                print(group.tags, group.cost, group.cost_by_resource)
+            ```
+        """
+        ...
+
 class _App:
     """A Modal App is a group of functions and classes that are deployed together.
 
@@ -953,6 +1002,11 @@ class _App:
         """
         ...
 
+    @property
+    def sandboxes(self) -> _AppSandboxesManager:
+        """Namespace for the Sandboxes belonging to this App."""
+        ...
+
     async def info(self, refresh: bool = False) -> modal.types.AppInfo:
         """Return information for a modal `App`.
 
@@ -971,6 +1025,101 @@ class _App:
         """
         ...
 
+class AppSandboxesManager:
+    """mdmd:namespace"""
+    def __init__(self, app: App):
+        """mdmd:hidden"""
+        ...
+
+    class __stats_spec(typing_extensions.Protocol):
+        def __call__(
+            self,
+            /,
+            *,
+            since: datetime.datetime,
+            until: typing.Optional[datetime.datetime] = None,
+            group_by_tags: typing.Optional[collections.abc.Sequence[str]] = None,
+            tags: typing.Optional[dict[str, str]] = None,
+        ) -> typing.Generator[modal.types.SandboxGroupStats, None, None]:
+            """Return statistics for this App's Sandboxes over a time range, optionally grouped by tag values.
+
+            The maximum time range is 7 days.
+
+            Args:
+                since: The beginning of the time range, inclusive, on a UTC hour boundary. Values without a
+                    timezone are interpreted as local time.
+                until: The end of the time range, exclusive, on a UTC hour boundary. If omitted, this defaults to
+                    the current time. Values without a timezone are interpreted as local time.
+                group_by_tags: Tag names to group by. Sandboxes with the same values for these names form one group;
+                    a name not present on a Sandbox counts as `None`. If omitted, all matching Sandboxes are returned
+                    as a single group.
+                tags: Only include Sandboxes that have at least these tags.
+
+            Yields:
+                `SandboxGroupStats` objects, one per combination of tag values, with the following fields:
+                - `tags`: the value of each name in `group_by_tags` for the group's Sandboxes, `None` where not present.
+                - `cost`: total cost in USD, the sum of `cost_by_resource`.
+                - `cost_by_resource`: cost in USD by billed resource: `CPU`, `Memory`, and GPU types such as
+                  `H100`. The resource names are subject to change as Modal's billing model evolves.
+
+            Raises:
+                InvalidError: If the time range is invalid or there are more than 10,000 groups.
+
+            Examples:
+                ```python notest
+                app = modal.App.lookup("my-app")
+                since = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0) - timedelta(days=1)
+                for group in app.sandboxes.stats(since=since, group_by_tags=["team"]):
+                    print(group.tags, group.cost, group.cost_by_resource)
+                ```
+            """
+            ...
+
+        def aio(
+            self,
+            /,
+            *,
+            since: datetime.datetime,
+            until: typing.Optional[datetime.datetime] = None,
+            group_by_tags: typing.Optional[collections.abc.Sequence[str]] = None,
+            tags: typing.Optional[dict[str, str]] = None,
+        ) -> collections.abc.AsyncGenerator[modal.types.SandboxGroupStats, None]:
+            """Return statistics for this App's Sandboxes over a time range, optionally grouped by tag values.
+
+            The maximum time range is 7 days.
+
+            Args:
+                since: The beginning of the time range, inclusive, on a UTC hour boundary. Values without a
+                    timezone are interpreted as local time.
+                until: The end of the time range, exclusive, on a UTC hour boundary. If omitted, this defaults to
+                    the current time. Values without a timezone are interpreted as local time.
+                group_by_tags: Tag names to group by. Sandboxes with the same values for these names form one group;
+                    a name not present on a Sandbox counts as `None`. If omitted, all matching Sandboxes are returned
+                    as a single group.
+                tags: Only include Sandboxes that have at least these tags.
+
+            Yields:
+                `SandboxGroupStats` objects, one per combination of tag values, with the following fields:
+                - `tags`: the value of each name in `group_by_tags` for the group's Sandboxes, `None` where not present.
+                - `cost`: total cost in USD, the sum of `cost_by_resource`.
+                - `cost_by_resource`: cost in USD by billed resource: `CPU`, `Memory`, and GPU types such as
+                  `H100`. The resource names are subject to change as Modal's billing model evolves.
+
+            Raises:
+                InvalidError: If the time range is invalid or there are more than 10,000 groups.
+
+            Examples:
+                ```python notest
+                app = modal.App.lookup("my-app")
+                since = datetime.now(timezone.utc).replace(minute=0, second=0, microsecond=0) - timedelta(days=1)
+                for group in app.sandboxes.stats(since=since, group_by_tags=["team"]):
+                    print(group.tags, group.cost, group.cost_by_resource)
+                ```
+            """
+            ...
+
+    stats: __stats_spec
+
 SUPERSELF = typing.TypeVar("SUPERSELF", covariant=True)
 
 class App:
@@ -2073,6 +2222,11 @@ class App:
         """
         ...
 
+    @property
+    def sandboxes(self) -> AppSandboxesManager:
+        """Namespace for the Sandboxes belonging to this App."""
+        ...
+
     class __info_spec(typing_extensions.Protocol):
         def __call__(self, /, refresh: bool = False) -> modal.types.AppInfo:
             """Return information for a modal `App`.

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal/cli/endpoint.py

@@ -5,6 +5,7 @@ from json import dumps
 from typing import Optional
 
 import click
+from rich.box import SIMPLE
 from rich.table import Column, Table
 from rich.text import Text
 
@@ -21,6 +22,7 @@ from modal_proto import api_pb2
 
 from ._help import ModalGroup
 from ._logs import _validate_logs_args
+from ._stats import STATS_METADATA_STYLE
 from .server import _run_server_logs, _run_server_stats, _server_stats_time_range
 
 _ENDPOINT_HELP = """
@@ -41,6 +43,11 @@ _SERVING_MODE_LABELS = {
     api_pb2.ENDPOINT_SERVING_MODE_DEDICATED: "dedicated",
     api_pb2.ENDPOINT_SERVING_MODE_SHARED: "shared",
 }
+_INPUT_MODALITY_LABELS = {
+    api_pb2.ENDPOINT_INPUT_MODALITY_TEXT: "text",
+    api_pb2.ENDPOINT_INPUT_MODALITY_IMAGE: "image",
+    api_pb2.ENDPOINT_INPUT_MODALITY_AUDIO: "audio",
+}
 _ENDPOINT_STATUS_LABELS = {
     api_pb2.EndpointGetInfoResponse.ENDPOINT_STATUS_PROVISIONING: "provisioning",
     api_pb2.EndpointGetInfoResponse.ENDPOINT_STATUS_LIVE: "live",
@@ -502,6 +509,108 @@ async def stop(
         output.print(f"[green]✓[/green] Stopped Endpoint {endpoint_id}.")
 
 
+@endpoint_cli.command("library", panel="Inspection")
+@click.option(
+    "--input-modality",
+    type=click.Choice(["text", "image", "audio"]),
+    multiple=True,
+    help="Only show models that accept any of these inputs. Can be repeated.",
+)
+@click.option("--json", "json_output", is_flag=True, help="Output models as JSON.")
+@synchronizer.create_blocking
+async def library(*, input_modality: tuple[str, ...] = (), json_output: bool = False) -> None:
+    """List models you can serve with Modal Endpoints.
+
+    Models are listed by their Hugging Face repo ID, with the input types they
+    accept and whether they're available as shared endpoints, dedicated
+    endpoints, or both.
+
+    This is Modal's catalog of supported models, not the Endpoints in your
+    workspace. To see those, run `modal endpoint list`.
+
+    Examples:
+
+    List models that support text input modality:
+
+    ```
+    modal endpoint library --input-modality text
+    ```
+
+    Pick a model ID and then create a shared endpoint:
+
+    ```
+    modal endpoint create --model Qwen/Qwen3.8-27B --shared
+    ```
+    """
+    client = await _Client.from_env()
+    response = await client._stub.EndpointGetLibrary(api_pb2.EndpointGetLibraryRequest())
+    modalities = {modality for modality, label in _INPUT_MODALITY_LABELS.items() if label in input_modality}
+
+    models = sorted(
+        (
+            model
+            for model in response.models
+            if (not modalities or modalities.intersection(model.supported_input_modalities))
+        ),
+        key=lambda model: model.base_model_repo_id,
+    )
+    output = OutputManager.get()
+    if json_output:
+        output.print_json(
+            dumps(
+                [
+                    {
+                        "base_model_repo_id": model.base_model_repo_id,
+                        "input_modalities": [
+                            _INPUT_MODALITY_LABELS.get(modality, "unknown")
+                            for modality in model.supported_input_modalities
+                        ],
+                        "shared": api_pb2.ENDPOINT_SERVING_MODE_SHARED in model.available_serving_modes,
+                        "dedicated": api_pb2.ENDPOINT_SERVING_MODE_DEDICATED in model.available_serving_modes,
+                    }
+                    for model in models
+                ]
+            )
+        )
+        return
+    output.print(
+        Text(
+            f"Displaying {len(models):,} {'model' if len(models) == 1 else 'models'}",
+            style=STATS_METADATA_STYLE,
+        )
+    )
+    if not models:
+        output.print(
+            "No endpoint-compatible models match the filters."
+            if input_modality
+            else "No endpoint-compatible models are available."
+        )
+        return
+    display_table(
+        [
+            Column("Model ID", overflow="fold"),
+            "Input Modalities",
+            Column("Shared", justify="center"),
+            Column("Dedicated", justify="center"),
+        ],
+        [
+            (
+                Text.assemble(
+                    (model.base_model_repo_id, f"link https://huggingface.co/{model.base_model_repo_id}"),
+                    (" ↗", "bright_blue not underline"),
+                ),
+                ", ".join(
+                    _INPUT_MODALITY_LABELS.get(modality, "unknown") for modality in model.supported_input_modalities
+                ),
+                "✓" if api_pb2.ENDPOINT_SERVING_MODE_SHARED in model.available_serving_modes else "—",
+                "✓" if api_pb2.ENDPOINT_SERVING_MODE_DEDICATED in model.available_serving_modes else "—",
+            )
+            for model in models
+        ],
+        table_box=SIMPLE,
+    )
+
+
 @endpoint_cli.command("info", panel="Inspection", no_args_is_help=True)
 @click.argument("endpoint_identifier")
 @env_option

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal/client.pyi

@@ -87,7 +87,7 @@ class _Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.4.dev1",
+        version: str = "1.6.4.dev2",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):
@@ -304,7 +304,7 @@ class Client:
         server_url: str,
         client_type: int,
         credentials: typing.Optional[tuple[str, str]],
-        version: str = "1.6.4.dev1",
+        version: str = "1.6.4.dev2",
         *,
         oauth_credentials: typing.Optional[_OAuthCredentials] = None,
     ):

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal/types.py

@@ -215,7 +215,10 @@ class StatsPercentileDistribution:
 
     @classmethod
     def _from_proto(cls, proto: api_pb2.StatsPercentileDistribution) -> "StatsPercentileDistribution":
-        return cls(unit=proto.unit, percentiles=[StatsPercentile._from_proto(p) for p in proto.percentiles])
+        return cls(
+            unit=proto.unit,
+            percentiles=[StatsPercentile._from_proto(p) for p in proto.percentiles],
+        )
 
 
 @dataclass(frozen=True)
@@ -571,6 +574,23 @@ class BillingReportItem:
         )
 
 
+@dataclass(slots=True, frozen=True)
+class SandboxGroupStats:
+    """Statistics for a group of Sandboxes over a time range."""
+
+    tags: dict[str, str | None]
+    cost: float
+    cost_by_resource: dict[str, float]
+
+    @classmethod
+    def _from_proto(cls, pb: "api_pb2.SandboxStatsGroup") -> "SandboxGroupStats":
+        return cls(
+            tags={name: tag.value if tag.HasField("value") else None for name, tag in pb.tags.items()},
+            cost=pb.cost,
+            cost_by_resource=dict(pb.cost_by_resource),
+        )
+
+
 @dataclass(slots=True, frozen=True)
 class WorkspaceBillingSummary:
     start: datetime

{modal-1.6.4.dev1 → modal-1.6.4.dev2}/modal.egg-info/PKG-INFO

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