Update Modal step operator

docs/book/component-guide/step-operators/modal.md

@@ -36,6 +36,13 @@ To use the Modal step operator, we need:
   cloud artifact store supported by ZenML will work with Modal.
 * A cloud container registry as part of your stack. Any cloud container
   registry supported by ZenML will work with Modal.
+* An Image Builder in your stack. ZenML uses it to build the Docker image that
+  runs on Modal.
+
+The Modal step operator also respects the following environment variables if set:
+- MODAL_TOKEN_ID, MODAL_TOKEN_SECRET: authentication tokens
+- MODAL_WORKSPACE: workspace name
+- MODAL_ENVIRONMENT: Modal environment name (e.g., "main")
 
 We can then register the step operator:
 
@@ -66,30 +73,42 @@ You can specify the hardware requirements for each step using the
 `ResourceSettings` class as described in our documentation on [resource settings](https://docs.zenml.io/user-guides/tutorial/distributed-training):
 
 ```python
+from zenml import step
 from zenml.config import ResourceSettings
 from zenml.integrations.modal.flavors import ModalStepOperatorSettings
 
-modal_settings = ModalStepOperatorSettings(gpu="A100")
+modal_settings = ModalStepOperatorSettings(
+    gpu="A100",           # GPU type (e.g., "T4", "A100")
+    # region="us-east-1", # optional, enterprise/team only
+    # cloud="aws",        # optional, enterprise/team only
+    # modal_environment="main",  # optional
+    # timeout=86400,      # optional, seconds
+)
+
 resource_settings = ResourceSettings(
-    cpu=2,
-    memory="32GB"
+    cpu_count=2,
+    memory="32GB",
+    # gpu_count=1,        # optional; if omitted and a GPU type is set, defaults to 1 GPU
 )
 
 @step(
-    step_operator=True,
+    step_operator=True,   # or the specific name, e.g., step_operator="<NAME>"
     settings={
         "step_operator": modal_settings,
-        "resources": resource_settings
-    }
+        "resources": resource_settings,
+    },
 )
 def my_modal_step():
     ...
 ```
 
+Important:
+- If you request GPUs with `ResourceSettings.gpu_count > 0`, you must also specify a GPU type via `ModalStepOperatorSettings.gpu`; otherwise the run will fail with a validation error.
+- If a GPU type is set but `gpu_count == 0`, ZenML defaults to 1 GPU and logs a warning.
+- `cpu_count` must be an integer. `memory` can be a string like "32GB" or an integer amount of bytes.
+
 {% hint style="info" %}
 Note that the `cpu` parameter in `ResourceSettings` currently only accepts a single integer value. This specifies a soft minimum limit - Modal will guarantee at least this many physical cores, but the actual usage could be higher. The CPU cores/hour will also determine the minimum price paid for the compute resources.
-
-For example, with the configuration above (2 CPUs and 32GB memory), the minimum cost would be approximately $1.03 per hour ((0.135 * 2) + (0.024 * 32) = $1.03).
 {% endhint %}
 
 This will run `my_modal_step` on a Modal instance with 1 A100 GPU, 2 CPUs, and
@@ -108,8 +127,3 @@ pipeline execution failures. In the case of failures, however, Modal provides
 detailed error messages that can help identify what is incompatible. See more in
 the [Modal docs on region selection](https://modal.com/docs/guide/region-selection) for more
 details.
-
-<!-- For scarf -->
-<figure><img alt="ZenML Scarf" referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=f0b4f458-0a54-4fcd-aa95-d5ee424815bc" /></figure>
-
-

src/zenml/cli/cli.py

@@ -43,7 +43,7 @@ def __init__(
         commands: Optional[
             Union[Dict[str, click.Command], Sequence[click.Command]]
         ] = None,
-        **kwargs: Dict[str, Any],
+        **kwargs: Any,
     ) -> None:
         """Initialize the Tag group.
 

src/zenml/integrations/modal/__init__.py

@@ -29,7 +29,7 @@ class ModalIntegration(Integration):
     """Definition of Modal integration for ZenML."""
 
     NAME = MODAL
-    REQUIREMENTS = ["modal>=0.64.49,<1"]
+    REQUIREMENTS = ["modal>=1"]
 
     @classmethod
     def flavors(cls) -> List[Type[Flavor]]:

src/zenml/integrations/modal/flavors/modal_step_operator_flavor.py

@@ -15,13 +15,18 @@
 
 from typing import TYPE_CHECKING, Optional, Type
 
+from pydantic import Field
+
 from zenml.config.base_settings import BaseSettings
 from zenml.integrations.modal import MODAL_STEP_OPERATOR_FLAVOR
 from zenml.step_operators import BaseStepOperatorConfig, BaseStepOperatorFlavor
+from zenml.utils.secret_utils import SecretField
 
 if TYPE_CHECKING:
     from zenml.integrations.modal.step_operators import ModalStepOperator
 
+DEFAULT_TIMEOUT_SECONDS = 86400  # 24 hours
+
 
 class ModalStepOperatorSettings(BaseSettings):
     """Settings for the Modal step operator.
@@ -36,20 +41,82 @@ class ModalStepOperatorSettings(BaseSettings):
     incompatible. See more in the Modal docs at https://modal.com/docs/guide/region-selection.
 
     Attributes:
-        gpu: The type of GPU to use for the step execution.
+        gpu: The type of GPU to use for the step execution (e.g., "T4", "A100").
+            Use ResourceSettings.gpu_count to specify the number of GPUs.
         region: The region to use for the step execution.
         cloud: The cloud provider to use for the step execution.
+        modal_environment: The Modal environment to use for the step execution.
+        timeout: Maximum execution time in seconds (default 24h).
     """
 
-    gpu: Optional[str] = None
-    region: Optional[str] = None
-    cloud: Optional[str] = None
+    gpu: Optional[str] = Field(
+        None,
+        description="GPU type for step execution. Must be a valid Modal GPU type. "
+        "Examples: 'T4' (cost-effective), 'A100' (high-performance), 'V100' (training workloads). "
+        "Use ResourceSettings.gpu_count to specify number of GPUs. If not specified, uses CPU-only execution",
+    )
+    region: Optional[str] = Field(
+        None,
+        description="Cloud region for step execution. Must be a valid region for the selected cloud provider. "
+        "Examples: 'us-east-1', 'us-west-2', 'eu-west-1'. If not specified, Modal uses default region "
+        "based on cloud provider and availability",
+    )
+    cloud: Optional[str] = Field(
+        None,
+        description="Cloud provider for step execution. Must be a valid Modal-supported cloud provider. "
+        "Examples: 'aws', 'gcp'. If not specified, Modal uses default cloud provider "
+        "based on workspace configuration",
+    )
+    modal_environment: Optional[str] = Field(
+        None,
+        description="Modal environment name for step execution. Must be a valid environment "
+        "configured in your Modal workspace. Examples: 'main', 'staging', 'production'. "
+        "If not specified, uses the default environment for the workspace",
+    )
+    timeout: int = Field(
+        DEFAULT_TIMEOUT_SECONDS,
+        ge=1,
+        le=DEFAULT_TIMEOUT_SECONDS,
+        description=f"Maximum execution time in seconds for step completion. Must be between 1 and {DEFAULT_TIMEOUT_SECONDS} seconds. "
+        f"Examples: 3600 (1 hour), 7200 (2 hours), {DEFAULT_TIMEOUT_SECONDS} (24 hours maximum). "
+        "Step execution will be terminated if it exceeds this timeout",
+    )
 
 
 class ModalStepOperatorConfig(
     BaseStepOperatorConfig, ModalStepOperatorSettings
 ):
-    """Configuration for the Modal step operator."""
+    """Configuration for the Modal step operator.
+
+    Attributes:
+        token_id: Modal API token ID (ak-xxxxx format) for authentication.
+        token_secret: Modal API token secret (as-xxxxx format) for authentication.
+        workspace: Modal workspace name (optional).
+
+    Note: If token_id and token_secret are not provided, falls back to
+    Modal's default authentication (~/.modal.toml).
+    All other configuration options (modal_environment, gpu, region, etc.)
+    are inherited from ModalStepOperatorSettings.
+    """
+
+    token_id: Optional[str] = SecretField(
+        default=None,
+        description="Modal API token ID for authentication. Must be in format 'ak-xxxxx' as provided by Modal. "
+        "Example: 'ak-1234567890abcdef'. If not provided, falls back to Modal's default authentication "
+        "from ~/.modal.toml file. Required for programmatic access to Modal API",
+    )
+    token_secret: Optional[str] = SecretField(
+        default=None,
+        description="Modal API token secret for authentication. Must be in format 'as-xxxxx' as provided by Modal. "
+        "Example: 'as-abcdef1234567890'. Used together with token_id for API authentication. "
+        "If not provided, falls back to Modal's default authentication from ~/.modal.toml file",
+    )
+    workspace: Optional[str] = Field(
+        None,
+        description="Modal workspace name for step execution. Must be a valid workspace name "
+        "you have access to. Examples: 'my-company', 'ml-team', 'personal-workspace'. "
+        "If not specified, uses the default workspace from Modal configuration",
+    )
 
     @property
     def is_remote(self) -> bool: