snowflake-ml-python 1.34.0__tar.gz → 1.35.0__tar.gz

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Release History
 
-## 1.34.0
+## 1.35.0
+
+### New Features
+
+### Bug Fixes
+
+* Registry: Fixed `ParamSpec.from_mlflow_spec` dropping `shape`, which caused shaped scalar params
+  (e.g., array of ints) from MLflow to fail validation during model import.
+
+### Behavior Changes
+
+* ML Jobs: `spec_overrides` now validates container keys and warns when keys other than `name` and `secrets`
+  are provided. Additional keys are not officially supported and may not behave as expected.
+
+### Deprecations
+
+## 1.34.0 (2026-04-08)
 
 ### New Features
 

{snowflake_ml_python-1.34.0/snowflake_ml_python.egg-info → snowflake_ml_python-1.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-ml-python
-Version: 1.34.0
+Version: 1.35.0
 Summary: The machine learning client library that is used for interacting with Snowflake to build machine learning solutions.
 Author-email: "Snowflake, Inc" <support@snowflake.com>
 License: 
@@ -416,7 +416,23 @@ NOTE: Version 1.7.0 is used as example here. Please choose the the latest versio
 
 # Release History
 
-## 1.34.0
+## 1.35.0
+
+### New Features
+
+### Bug Fixes
+
+* Registry: Fixed `ParamSpec.from_mlflow_spec` dropping `shape`, which caused shaped scalar params
+  (e.g., array of ints) from MLflow to fail validation during model import.
+
+### Behavior Changes
+
+* ML Jobs: `spec_overrides` now validates container keys and warns when keys other than `name` and `secrets`
+  are provided. Additional keys are not officially supported and may not behave as expected.
+
+### Deprecations
+
+## 1.34.0 (2026-04-08)
 
 ### New Features
 

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/_utils/feature_flags.py

@@ -129,5 +129,5 @@ class FeatureFlags:
     ENABLE_RUNTIME_VERSIONS = _FeatureFlag("MLRS_ENABLE_RUNTIME_VERSIONS", default=True)
     ENABLE_STAGE_MOUNT_V2 = _FeatureFlag(
         "MLRS_ENABLE_STAGE_MOUNT_V2",
-        default=_enabled_in_clouds(SnowflakeCloudType.GCP),
+        default=True,
     )

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/_utils/scripts/get_instance_ip.py

@@ -38,9 +38,16 @@ def get_first_instance(service_name: str) -> Optional[tuple[str, str, str]]:
     Returns:
         tuple[str, str]: A tuple containing (instance_id, ip_address) of the head instance.
     """
-    from snowflake.runtime.utils import session_utils
+    try:
+        from snowflake import snowpark
+        from snowflake.ml._internal.utils.connection_params import SnowflakeLoginOptions
+    except ImportError:
+        from snowflake.ml.utils.connection_params import SnowflakeLoginOptions
+
+    config = SnowflakeLoginOptions()
+    config["client_session_keep_alive"] = "True"
+    session = snowpark.Session.builder.configs(config).create()  # noqa: F841
 
-    session = session_utils.get_session()
     result = session.sql(f"show service instances in service {service_name}").collect()
 
     if not result:

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/_utils/scripts/mljob_launcher.py

@@ -250,6 +250,25 @@ def save_mljob_result(result_obj: Any, is_error: bool, path: str) -> None:
         save_mljob_result_v1(result_obj, is_error, path)
 
 
+def get_active_ray_nodes() -> list[dict[str, Any]]:
+    import ray
+
+    if not ray.is_initialized():
+        ray.init(
+            address="auto",
+            ignore_reinit_error=True,
+            log_to_driver=False,
+            logging_level="CRITICAL",
+        )
+    nodes = ray.nodes()
+    alive_nodes = [n for n in nodes if n["Alive"]]
+    return alive_nodes
+
+
+def get_num_ray_nodes() -> int:
+    return len(get_active_ray_nodes())
+
+
 def wait_for_instances(
     min_instances: int,
     target_instances: int,
@@ -320,9 +339,6 @@ def wait_for_instances(
         #   target_instances = 100  => min_wait_time = 19.9
         min_wait_time = min(3 * math.log2(target_instances), timeout / 10)  # Clamp to timeout / 10
 
-    # mljob_launcher runs inside the CR where mlruntime libraries are available, so we can import common_util directly
-    from common_utils import common_util as mlrs_util
-
     start_time = time.time()
     current_interval = max(min(1, check_interval), 0.1)  # Default 1s, minimum 0.1s
     logger.info(
@@ -333,7 +349,7 @@ def wait_for_instances(
     )
 
     while (elapsed := time.time() - start_time) < timeout:
-        total_nodes = mlrs_util.get_num_ray_nodes()
+        total_nodes = get_num_ray_nodes()
         if total_nodes >= target_instances:
             # Best case scenario: target_instances are already available
             logger.info(f"Target instance requirement met: {total_nodes} instances available after {elapsed:.1f}s")

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/decorators.py

@@ -44,7 +44,6 @@ def remote(
             env_vars (dict): Environment variables to set in container.
             enable_metrics (bool): Whether to enable metrics publishing for the job.
             query_warehouse (str): The query warehouse to use. Defaults to session warehouse.
-            spec_overrides (dict): A dictionary of overrides for the service spec.
             imports (list[Union[tuple[str, str], tuple[str]]]): A list of additional payloads used in the job.
             runtime_environment (str): The runtime image to use. Only support image tag or full image URL,
                 e.g. "1.7.1" or "image_repo/image_name:image_tag". When it refers to a full image URL,

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/job_definition.py

@@ -30,6 +30,35 @@ from snowflake.snowpark.exceptions import SnowparkSQLException
 
 _Args = ParamSpec("_Args")
 _ReturnValue = TypeVar("_ReturnValue")
+
+_ALLOWED_CONTAINER_KEYS = {"name", "secrets"}
+_ALLOWED_SPEC_KEYS = {"containers"}
+
+logger = logging.getLogger(__name__)
+
+
+def _validate_spec_overrides(spec_overrides: Any) -> None:
+    """Warn if spec_overrides contains keys beyond the officially supported set."""
+    spec = spec_overrides.get("spec", {})
+
+    disallowed_spec_keys = set(spec.keys()) - _ALLOWED_SPEC_KEYS
+    if disallowed_spec_keys:
+        logger.warning(
+            f"'spec_overrides.spec' keys {sorted(disallowed_spec_keys)} are not officially supported. "
+            f"Only {sorted(_ALLOWED_SPEC_KEYS)} are recommended. "
+            f"Additional keys may work but are not guaranteed — please validate your configuration carefully."
+        )
+
+    for container in spec.get("containers", []):
+        disallowed_container_keys = set(container.keys()) - _ALLOWED_CONTAINER_KEYS
+        if disallowed_container_keys:
+            logger.warning(
+                f"'spec_overrides' container keys {sorted(disallowed_container_keys)} are not officially supported. "
+                f"Only {sorted(_ALLOWED_CONTAINER_KEYS)} are recommended. "
+                f"Additional keys may work but are not guaranteed — please validate your configuration carefully."
+            )
+
+
 JOB_ID_PREFIX = "MLJOB_"
 _PROJECT = "MLJob"
 logger = logging.getLogger(__name__)
@@ -252,6 +281,8 @@ class MLJobDefinition(Generic[_Args, _ReturnValue], SerializableSessionMixin):
         external_access_integrations = kwargs.pop("external_access_integrations", None)
         env_vars = kwargs.pop("env_vars", None)
         spec_overrides = kwargs.pop("spec_overrides", None)
+        if spec_overrides is not None:
+            _validate_spec_overrides(spec_overrides)
         enable_metrics = kwargs.pop("enable_metrics", True)
         query_warehouse = kwargs.pop("query_warehouse", None)
         imports = kwargs.pop("imports", None)

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/jobs/manager.py

@@ -222,7 +222,6 @@ def submit_file(
             env_vars (dict): Environment variables to set in container.
             enable_metrics (bool): Whether to enable metrics publishing for the job.
             query_warehouse (str): The query warehouse to use. Defaults to session warehouse.
-            spec_overrides (dict): A dictionary of overrides for the service spec.
             imports (list[Union[tuple[str, str], tuple[str]]]): A list of additional payloads used in the job.
             runtime_environment (str): The runtime image to use. Only support image tag or full image URL,
                 e.g. "1.7.1" or "image_repo/image_name:image_tag". When it refers to a full image URL,
@@ -286,7 +285,6 @@ def submit_directory(
             env_vars (dict): Environment variables to set in container.
             enable_metrics (bool): Whether to enable metrics publishing for the job.
             query_warehouse (str): The query warehouse to use. Defaults to session warehouse.
-            spec_overrides (dict): A dictionary of overrides for the service spec.
             imports (list[Union[tuple[str, str], tuple[str]]]): A list of additional payloads used in the job.
             runtime_environment (str): The runtime image to use. Only support image tag or full image URL,
                 e.g. "1.7.1" or "image_repo/image_name:image_tag". When it refers to a full image URL,
@@ -352,7 +350,6 @@ def submit_from_stage(
             env_vars (dict): Environment variables to set in container.
             enable_metrics (bool): Whether to enable metrics publishing for the job.
             query_warehouse (str): The query warehouse to use. Defaults to session warehouse.
-            spec_overrides (dict): A dictionary of overrides for the service spec.
             imports (list[Union[tuple[str, str], tuple[str]]]): A list of additional payloads used in the job.
             runtime_environment (str): The runtime image to use. Only support image tag or full image URL,
                 e.g. "1.7.1" or "image_repo/image_name:image_tag". When it refers to a full image URL,

snowflake_ml_python-1.35.0/snowflake/ml/model/_client/model/batch_inference_definition.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import yaml
+
+from snowflake.ml._internal import telemetry
+from snowflake.ml._internal.utils import identifier, sql_identifier
+from snowflake.ml.model._client.model import (
+    batch_inference_serialization,
+    batch_inference_specs,
+    model_version_impl,
+)
+from snowflake.snowpark import dataframe
+
+_TELEMETRY_PROJECT = "MLOps"
+_TELEMETRY_SUBPROJECT = "ModelManagement"
+
+
+class BatchInferenceDefinition:
+    """Definition for batch inference suitable for use as a DAGTask definition.
+
+    This class captures the full batch inference configuration and provides a
+    ``to_sql()`` method that returns the SQL needed to run the batch inference job,
+    suitable for use as a ``DAGTask`` definition in Snowflake task graphs.
+    """
+
+    @telemetry.send_api_usage_telemetry(
+        project=_TELEMETRY_PROJECT,
+        subproject=_TELEMETRY_SUBPROJECT,
+        func_params_to_log=[
+            "compute_pool",
+            "input_spec",
+            "output_spec",
+            "job_spec",
+            "inference_engine_options",
+        ],
+    )
+    def __init__(
+        self,
+        *,
+        model_version: model_version_impl.ModelVersion,
+        X: dataframe.DataFrame,
+        compute_pool: str,
+        output_spec: batch_inference_specs.OutputSpec,
+        input_spec: Optional[batch_inference_specs.InputSpec] = None,
+        job_spec: Optional[batch_inference_specs.JobSpec] = None,
+        inference_engine_options: Optional[dict[str, Any]] = None,
+    ) -> None:
+        self._fully_qualified_model_name: str = model_version.fully_qualified_model_name
+        self._version_name: str = model_version.version_name
+        self._compute_pool = compute_pool
+        self._output_spec = output_spec
+        self._input_spec = input_spec if input_spec is not None else batch_inference_specs.InputSpec()
+        self._job_spec = job_spec if job_spec is not None else batch_inference_specs.JobSpec()
+        self._inference_engine_options = inference_engine_options
+
+        # Resolve the inference function the same way as run_batch().
+        function_name = job_spec.function_name if (job_spec is not None and job_spec.function_name) else None
+        target_function_info = model_version._get_function_info(function_name=function_name)
+        self._function_name: str = target_function_info["target_method"]
+
+        # Serialize DataFrame queries for session-free replay
+        self._queries: list[str] = list(X.queries["queries"])
+        self._post_actions: list[str] = list(X.queries["post_actions"])
+
+    @telemetry.send_api_usage_telemetry(
+        project=_TELEMETRY_PROJECT,
+        subproject=_TELEMETRY_SUBPROJECT,
+    )
+    def to_sql(self) -> str:
+        """Generate the SQL statement to run a batch inference job.
+
+        Returns:
+            A SQL string suitable for use as a DAGTask definition.
+        """
+        self._validate()
+        spec_dict = self._build_spec_dict()
+        yaml_str = yaml.safe_dump(spec_dict, default_flow_style=False, sort_keys=False)
+        # Use dollar-quoted string to avoid escaping issues with single quotes in YAML content
+        return f"CALL SYSTEM$DEPLOY_MODEL($${yaml_str}$$)"
+
+    def _build_spec_dict(self) -> dict[str, Any]:
+        """Construct the full deployment spec dictionary.
+
+        Raises:
+            ValueError: If warehouse is not set in the job spec.
+
+        Returns:
+            A dictionary matching the ModelJobDeploymentSpec schema.
+        """
+        if self._job_spec.warehouse is None:
+            raise ValueError(
+                "warehouse must be set in JobSpec for task-based batch inference. "
+                "The session warehouse is not available in DAGTask context."
+            )
+
+        # Model section
+        models = [{"name": self._fully_qualified_model_name, "version": self._version_name}]
+
+        # Parse db.schema from the fully qualified model name for qualifying job names.
+        # Use sql_identifier to handle quoted/case-sensitive identifiers correctly.
+        db_id, schema_id, _ = sql_identifier.parse_fully_qualified_name(self._fully_qualified_model_name)
+
+        # TODO: Share job name qualification logic with service_ops.invoke_batch_job_method.
+        # Job name handling
+        job_name: Optional[str] = None
+        name_prefix: Optional[str] = None
+        if self._job_spec.job_name is not None:
+            parsed_job_db, parsed_job_schema, parsed_job_name = sql_identifier.parse_fully_qualified_name(
+                self._job_spec.job_name
+            )
+            job_db = parsed_job_db or db_id
+            job_schema = parsed_job_schema or schema_id
+            assert job_db is not None and job_schema is not None
+            job_name = identifier.get_schema_level_object_identifier(
+                job_db.identifier(), job_schema.identifier(), parsed_job_name.identifier()
+            )
+        elif self._job_spec.job_name_prefix is not None:
+            assert db_id is not None and schema_id is not None
+            job_name_prefix_qualified = identifier.get_schema_level_object_identifier(
+                db_id.identifier(), schema_id.identifier(), self._job_spec.job_name_prefix + "_"
+            )
+            name_prefix = job_name_prefix_qualified
+
+        function_name = self._function_name
+
+        # Output section
+        # TODO(SNOW-3351625): Propagate OutputSpec.mode (save_mode) to the deployment spec
+        # so the server can enforce OVERWRITE/ERROR semantics for repeated DAG runs.
+        # Currently the mode is only enforced client-side in run_batch() via _enforce_save_mode.
+        output_stage = self._output_spec.stage_location
+        if not output_stage.endswith("/"):
+            output_stage += "/"
+
+        # Input section
+        # TODO(SNOW-3316544): Remove input_stage_location once it's not required.
+        input_stage_location = f"{output_stage}_temporary/"
+        input_dict: dict[str, Any] = {
+            "input_stage_location": input_stage_location,
+            "queries": self._queries,
+            "post_actions": self._post_actions,
+            "input_file_pattern": "*",
+        }
+
+        # Encode params if present
+        params_encoded = batch_inference_serialization.encode_params(self._input_spec.params)
+        if params_encoded is not None:
+            input_dict["params"] = params_encoded
+
+        # Encode column handling if present
+        column_handling_encoded = batch_inference_serialization.encode_column_handling(self._input_spec.column_handling)
+        if column_handling_encoded is not None:
+            input_dict["column_handling"] = column_handling_encoded
+
+        if self._input_spec.partition_column is not None:
+            input_dict["partition_columns"] = [self._input_spec.partition_column]
+
+        output_dict: dict[str, Any] = {
+            "output_stage_location": output_stage,
+            "completion_filename": "_SUCCESS",
+        }
+
+        # Job section
+        job_dict: dict[str, Any] = {
+            "compute_pool": self._compute_pool,
+            "warehouse": self._job_spec.warehouse,
+            "function_name": function_name,
+            "input": input_dict,
+            "output": output_dict,
+            "sync": True,
+        }
+
+        if job_name is not None:
+            job_dict["name"] = job_name
+        if name_prefix is not None:
+            job_dict["name_prefix"] = name_prefix
+
+        # Resource fields — only if set
+        if self._job_spec.cpu_requests is not None:
+            job_dict["cpu"] = self._job_spec.cpu_requests
+        if self._job_spec.memory_requests is not None:
+            job_dict["memory"] = self._job_spec.memory_requests
+        if self._job_spec.gpu_requests is not None:
+            job_dict["gpu"] = self._job_spec.gpu_requests
+        if self._job_spec.num_workers is not None:
+            job_dict["num_workers"] = self._job_spec.num_workers
+        if self._job_spec.max_batch_rows is not None:
+            job_dict["max_batch_rows"] = self._job_spec.max_batch_rows
+        if self._job_spec.replicas is not None:
+            job_dict["replicas"] = self._job_spec.replicas
+
+        # Build the top-level spec
+        spec: dict[str, Any] = {
+            "models": models,
+            "job": job_dict,
+        }
+
+        # Inference engine spec OR image build
+        if self._inference_engine_options is not None:
+            engine = self._inference_engine_options["engine"]
+            engine_spec: dict[str, Any] = {"inference_engine_name": engine.value}
+            engine_args = self._inference_engine_options.get("engine_args_override")
+            if engine_args:
+                engine_spec["inference_engine_args"] = engine_args
+            job_dict["inference_engine_spec"] = engine_spec
+        else:
+            image_build: dict[str, Any] = {"compute_pool": self._compute_pool}
+            if self._job_spec.image_repo is not None:
+                image_build["image_repo"] = self._job_spec.image_repo
+            if self._job_spec.force_rebuild:
+                image_build["force_rebuild"] = True
+            spec["image_build"] = image_build
+
+        return spec
+
+    def _validate(self) -> None:
+        """Validate inputs before deployment. No-op for now.
+
+        Called by to_sql() before generating the deployment spec.
+        """
+        # TODO(SNOW-3351625): Implement client-side validation:
+        # - GPU compute pool validation if gpu_requests is set
+        # - Inference function validation
+        # - Input parameter validation
+        pass

snowflake_ml_python-1.35.0/snowflake/ml/model/_client/model/batch_inference_serialization.py

@@ -0,0 +1,56 @@
+import base64
+import datetime
+import json
+from typing import Any, Optional
+
+from pydantic import TypeAdapter
+
+from snowflake.ml.model._client.model.batch_inference_specs import ColumnHandlingOptions
+
+_UTF8_ENCODING = "utf-8"
+
+
+def encode_params(params: Optional[dict[str, Any]]) -> Optional[str]:
+    """Encode params dictionary to a base64 string.
+
+    Args:
+        params: Optional dictionary of model inference parameters.
+
+    Returns:
+        Base64 encoded JSON string of the params, or None if input is None.
+    """
+    if params is None:
+        return None
+
+    def serialize_value(v: Any) -> Any:
+        """Convert non-JSON-serializable types to JSON-compatible formats."""
+        if isinstance(v, bytes):
+            return v.hex()
+        if isinstance(v, datetime.datetime):
+            return v.isoformat()
+        if isinstance(v, list):
+            return [serialize_value(item) for item in v]
+        if isinstance(v, dict):
+            return {k: serialize_value(val) for k, val in v.items()}
+        return v
+
+    serializable_params = {k: serialize_value(v) for k, v in params.items()}
+    return base64.b64encode(json.dumps(serializable_params).encode(_UTF8_ENCODING)).decode(_UTF8_ENCODING)
+
+
+def encode_column_handling(
+    column_handling: Optional[dict[str, ColumnHandlingOptions]],
+) -> Optional[str]:
+    """Validate and encode column_handling to a base64 string.
+
+    Args:
+        column_handling: Optional dictionary mapping column names to file encoding options.
+
+    Returns:
+        Base64 encoded JSON string of the column handling options, or None if input is None.
+    """
+    if column_handling is None:
+        return None
+    adapter = TypeAdapter(dict[str, ColumnHandlingOptions])
+    validated_input = adapter.validate_python(column_handling)
+    return base64.b64encode(adapter.dump_json(validated_input)).decode(_UTF8_ENCODING)

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/model/_client/model/batch_inference_specs.py

@@ -136,6 +136,9 @@ class JobSpec(BaseModel):
             string values. Use CPU if None.
         replicas (Optional[int]): Number of SPCS job nodes used for distributed inference.
             If not specified, defaults to 1 replica.
+        block (bool): Whether the SPCS batch inference job runs synchronously
+            or asynchronously. When True, the call blocks until the job completes. When
+            False, the call returns immediately after job creation. Defaults to False.
 
     Example:
         >>> job_spec = JobSpec(
@@ -159,6 +162,7 @@ class JobSpec(BaseModel):
     memory_requests: Optional[str] = None
     gpu_requests: Optional[str] = None
     replicas: Optional[int] = None
+    block: bool = False
 
     @model_validator(mode="after")
     def _validate_job_name_exclusivity(self) -> "JobSpec":

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/model/_client/model/model_version_impl.py

@@ -845,6 +845,7 @@ class ModelVersion(lineage_node.LineageNode):
             job_name=job_spec.job_name,
             job_name_prefix=job_spec.job_name_prefix,
             replicas=job_spec.replicas,
+            block=job_spec.block,
             # input and output
             input_stage_location=input_stage_location,
             input_file_pattern="*",

{snowflake_ml_python-1.34.0 → snowflake_ml_python-1.35.0}/snowflake/ml/model/_client/ops/param_utils.py

@@ -86,14 +86,88 @@ def _validate_param_group_value(
         group_spec: The ParamGroupSpec defining the expected structure.
         value: The user-provided value to validate.
         param_path: Dot-separated path for error messages (e.g., "config.sampling").
+    """
+    if value is None:
+        return
+
+    # Shaped groups (e.g. shape=(2,)) represent a list of dicts.
+    # Validate by recursively unwrapping list dimensions first,
+    # then checking each leaf dict against the spec's children.
+    if group_spec.shape is not None:
+        _validate_shaped_param_group_value(group_spec, value, param_path, group_spec.shape)
+        return
+
+    # Unshaped groups represent a single dict — validate directly.
+    _validate_param_group_dict(group_spec, value, param_path)
+
+
+def _validate_shaped_param_group_value(
+    group_spec: core.ParamGroupSpec,
+    value: Any,
+    param_path: str,
+    remaining_shape: tuple[int, ...],
+) -> None:
+    """Validate a shaped ParamGroupSpec value by unwrapping list dimensions.
+
+    Each dimension in the shape corresponds to one level of list nesting.
+    Once all dimensions are unwrapped, each leaf is validated as a dict.
+
+    Args:
+        group_spec: The ParamGroupSpec defining the expected structure.
+        value: The user-provided value to validate.
+        param_path: Path for error messages (e.g., "config.items[0][2]").
+            May include both dot-separated segments and bracket indices.
+        remaining_shape: Remaining shape dimensions to unwrap.
 
     Raises:
-        SnowflakeMLException: If the value is not a dict, contains unknown keys,
-            or child values fail type validation.
+        SnowflakeMLException: If the value structure doesn't match the shape.
     """
-    if value is None:
+    # All shape dimensions consumed — validate the leaf value as a dict.
+    if not remaining_shape:
+        _validate_param_group_dict(group_spec, value, param_path)
         return
 
+    # Current dimension expects a list wrapper.
+    if not isinstance(value, list):
+        raise exceptions.SnowflakeMLException(
+            error_code=error_codes.INVALID_ARGUMENT,
+            original_exception=ValueError(
+                f"Parameter '{param_path}' expected a list (shape={group_spec.shape}), " f"got {type(value).__name__}."
+            ),
+        )
+
+    # -1 means variable length (skip length check); otherwise enforce exact match.
+    expected_len = remaining_shape[0]
+    if expected_len != -1 and len(value) != expected_len:
+        raise exceptions.SnowflakeMLException(
+            error_code=error_codes.INVALID_ARGUMENT,
+            original_exception=ValueError(
+                f"Parameter '{param_path}' expected length {expected_len}, got {len(value)}."
+            ),
+        )
+
+    # Recurse into each element with the next dimension.
+    for i, elem in enumerate(value):
+        _validate_shaped_param_group_value(group_spec, elem, f"{param_path}[{i}]", remaining_shape[1:])
+
+
+def _validate_param_group_dict(
+    group_spec: core.ParamGroupSpec,
+    value: Any,
+    param_path: str,
+) -> None:
+    """Validate that a value is a dict matching the group spec's children.
+
+    Args:
+        group_spec: The ParamGroupSpec defining the expected structure.
+        value: The user-provided value to validate.
+        param_path: Dot-separated path for error messages (e.g., "config.sampling").
+
+    Raises:
+        SnowflakeMLException: If the value is not a dict, contains unknown keys,
+            non-string keys, duplicate case-insensitive keys, or child values
+            fail type validation.
+    """
     if not isinstance(value, dict):
         raise exceptions.SnowflakeMLException(
             error_code=error_codes.INVALID_ARGUMENT,