nextmv 0.32.0__py3-none-any.whl → 0.33.0__py3-none-any.whl

nextmv/__about__.py

@@ -1 +1 @@
-__version__ = "v0.32.0"
+__version__ = "v0.33.0"

nextmv/__init__.py

@@ -21,6 +21,7 @@ from .manifest import Manifest as Manifest
 from .manifest import ManifestBuild as ManifestBuild
 from .manifest import ManifestOption as ManifestOption
 from .manifest import ManifestPython as ManifestPython
+from .manifest import ManifestPythonArch as ManifestPythonArch
 from .manifest import ManifestPythonModel as ManifestPythonModel
 from .manifest import ManifestRuntime as ManifestRuntime
 from .manifest import ManifestType as ManifestType

nextmv/cloud/__init__.py

@@ -47,6 +47,7 @@ from .acceptance_test import MetricParams as MetricParams
 from .acceptance_test import MetricResult as MetricResult
 from .acceptance_test import MetricStatistics as MetricStatistics
 from .acceptance_test import MetricTolerance as MetricTolerance
+from .acceptance_test import MetricToleranceType as MetricToleranceType
 from .acceptance_test import MetricType as MetricType
 from .acceptance_test import ResultStatistics as ResultStatistics
 from .acceptance_test import StatisticType as StatisticType
@@ -63,6 +64,12 @@ from .batch_experiment import BatchExperimentRun as BatchExperimentRun
 from .batch_experiment import ExperimentStatus as ExperimentStatus
 from .client import Client as Client
 from .client import get_size as get_size
+from .ensemble import EnsembleDefinition as EnsembleDefinition
+from .ensemble import EvaluationRule as EvaluationRule
+from .ensemble import RuleObjective as RuleObjective
+from .ensemble import RuleTolerance as RuleTolerance
+from .ensemble import RuleToleranceType as RuleToleranceType
+from .ensemble import RunGroup as RunGroup
 from .input_set import InputSet as InputSet
 from .input_set import ManagedInput as ManagedInput
 from .instance import Instance as Instance

nextmv/cloud/acceptance_test.py

@@ -47,6 +47,7 @@ from typing import Optional
 
 from nextmv.base_model import BaseModel
 from nextmv.cloud.batch_experiment import ExperimentStatus
+from nextmv.deprecated import deprecated
 
 
 class MetricType(str, Enum):
@@ -214,6 +215,9 @@ class Comparison(str, Enum):
 
 class ToleranceType(str, Enum):
     """
+    !!! warning
+        `ToleranceType` is deprecated, use `MetricToleranceType` instead.
+
     Type of tolerance used for a metric.
 
     You can import the `ToleranceType` class directly from `cloud`:
@@ -242,6 +246,66 @@ class ToleranceType(str, Enum):
     <ToleranceType.absolute: 'absolute'>
     """
 
+    undefined = ""
+    """ToleranceType is deprecated, please use MetricToleranceType instead.
+    Undefined tolerance type."""
+    absolute = "absolute"
+    """ToleranceType is deprecated, please use MetricToleranceType instead.
+    Absolute tolerance type."""
+    relative = "relative"
+    """ToleranceType is deprecated, please use MetricToleranceType instead.
+    Relative tolerance type."""
+
+
+# Override __getattribute__ to emit deprecation warnings when enum values are accessed
+_original_getattribute = ToleranceType.__class__.__getattribute__
+
+
+def _deprecated_getattribute(cls, name: str):
+    # Only emit deprecation warning if this is specifically the ToleranceType class
+    if cls is ToleranceType and name in ("undefined", "absolute", "relative"):
+        deprecated(
+            f"ToleranceType.{name}",
+            "ToleranceType is deprecated and will be removed in a future version. "
+            "Please use MetricToleranceType instead",
+        )
+
+    return _original_getattribute(cls, name)
+
+
+ToleranceType.__class__.__getattribute__ = _deprecated_getattribute
+
+
+class MetricToleranceType(str, Enum):
+    """
+    Type of tolerance used for a metric.
+
+    You can import the `MetricToleranceType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import MetricToleranceType
+    ```
+
+    This enumeration defines the different types of tolerances that can be used
+    when comparing metrics in acceptance tests.
+
+    Attributes
+    ----------
+    undefined : str
+        Undefined tolerance type (empty string).
+    absolute : str
+        Absolute tolerance type, using a fixed value.
+    relative : str
+        Relative tolerance type, using a percentage.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import MetricToleranceType
+    >>> tol_type = MetricToleranceType.absolute
+    >>> tol_type
+    <MetricToleranceType.absolute: 'absolute'>
+    """
+
     undefined = ""
     """Undefined tolerance type."""
     absolute = "absolute"
@@ -265,22 +329,22 @@ class MetricTolerance(BaseModel):
 
     Attributes
     ----------
-    type : ToleranceType
+    type : MetricToleranceType
         Type of tolerance (absolute or relative).
     value : float
         Value of the tolerance.
 
     Examples
     --------
-    >>> from nextmv.cloud import MetricTolerance, ToleranceType
-    >>> tolerance = MetricTolerance(type=ToleranceType.absolute, value=0.1)
+    >>> from nextmv.cloud import MetricTolerance, MetricToleranceType
+    >>> tolerance = MetricTolerance(type=MetricToleranceType.absolute, value=0.1)
     >>> tolerance.type
-    <ToleranceType.absolute: 'absolute'>
+    <MetricToleranceType.absolute: 'absolute'>
     >>> tolerance.value
     0.1
     """
 
-    type: ToleranceType
+    type: MetricToleranceType
     """Type of tolerance."""
     value: float
     """Value of the tolerance."""

nextmv/cloud/application.py

@@ -46,6 +46,7 @@ from nextmv.cloud.batch_experiment import (
     to_runs,
 )
 from nextmv.cloud.client import Client, get_size
+from nextmv.cloud.ensemble import EnsembleDefinition, EvaluationRule, RunGroup
 from nextmv.cloud.input_set import InputSet, ManagedInput
 from nextmv.cloud.instance import Instance, InstanceConfiguration
 from nextmv.cloud.scenario import Scenario, ScenarioInputType, _option_sets, _scenarios_by_id
@@ -129,6 +130,8 @@ class Application:
     """Base endpoint for the application."""
     experiments_endpoint: str = "{base}/experiments"
     """Base endpoint for the experiments in the application."""
+    ensembles_endpoint: str = "{base}/ensembles"
+    """Base endpoint for managing the ensemble definitions in the application"""
 
     def __post_init__(self):
         """Initialize the endpoint and experiments_endpoint attributes.
@@ -138,6 +141,7 @@ class Application:
         """
         self.endpoint = self.endpoint.format(id=self.id)
         self.experiments_endpoint = self.experiments_endpoint.format(base=self.endpoint)
+        self.ensembles_endpoint = self.ensembles_endpoint.format(base=self.endpoint)
 
     @classmethod
     def new(
@@ -515,6 +519,30 @@ class Application:
             endpoint=f"{self.experiments_endpoint}/batch/{batch_id}",
         )
 
+    def delete_ensemble_definition(self, ensemble_definition_id: str) -> None:
+        """
+        Delete an ensemble definition.
+
+        Parameters
+        ----------
+        ensemble_definition_id : str
+            ID of the ensemble definition to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_ensemble_definition("development-ensemble-definition")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.ensembles_endpoint}/{ensemble_definition_id}",
+        )
+
     def delete_scenario_test(self, scenario_test_id: str) -> None:
         """
         Delete a scenario test.
@@ -563,6 +591,39 @@ class Application:
             endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
         )
 
+    def ensemble_definition(self, ensemble_definition_id: str) -> EnsembleDefinition:
+        """
+        Get an ensemble definition.
+
+        Parameters
+        ----------
+        ensemble_definition_id : str
+            ID of the ensemble definition to retrieve.
+
+        Returns
+        -------
+        EnsembleDefintion
+            The requested ensemble definition details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> ensemble_definition = app.ensemble_definition("instance-123")
+        >>> print(ensemble_definition.name)
+        'Production Ensemble Definition'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.ensembles_endpoint}/{ensemble_definition_id}",
+        )
+
+        return EnsembleDefinition.from_dict(response.json())
+
     @staticmethod
     def exists(client: Client, id: str) -> bool:
         """
@@ -748,6 +809,36 @@ class Application:
 
         return [BatchExperimentMetadata.from_dict(batch_experiment) for batch_experiment in response.json()]
 
+    def list_ensemble_definitions(self) -> list[EnsembleDefinition]:
+        """
+        List all ensemble_definitions.
+
+        Returns
+        -------
+        list[EnsembleDefinition]
+            List of all ensemble definitions associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> ensemble_definitions = app.list_ensemble_definitions()
+        >>> for ensemble_definition in ensemble_definitions:
+        ...     print(ensemble_definition.name)
+        'Development Ensemble Definition'
+        'Production Ensemble Definition'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.ensembles_endpoint}",
+        )
+
+        return [EnsembleDefinition.from_dict(ensemble_definition) for ensemble_definition in response.json()["items"]]
+
     def list_input_sets(self) -> list[InputSet]:
         """
         List all input sets.
@@ -1314,6 +1405,53 @@ class Application:
 
         return self.batch_experiment_with_polling(batch_id=batch_id, polling_options=polling_options)
 
+    def new_ensemble_defintion(
+        self,
+        id: str,
+        run_groups: list[RunGroup],
+        rules: list[EvaluationRule],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> EnsembleDefinition:
+        """
+        Create a new ensemble definition.
+
+        Parameters
+        ----------
+        id: str
+            ID of the ensemble defintion.
+        run_groups: list[RunGroup]
+            Information to facilitate the execution of child runs.
+        rules: list[EvaluationRule]
+            Information to facilitate the selection of
+            a result for the ensemble run from child runs.
+        name: Optional[str]
+            Name of the ensemble definition.
+        description: Optional[str]
+            Description of the ensemble definition.
+        """
+
+        if name is None:
+            name = id
+        if description is None:
+            description = name
+
+        payload = {
+            "id": id,
+            "run_groups": [run_group.to_dict() for run_group in run_groups],
+            "rules": [rule.to_dict() for rule in rules],
+            "name": name,
+            "description": description,
+        }
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.ensembles_endpoint}",
+            payload=payload,
+        )
+
+        return EnsembleDefinition.from_dict(response.json())
+
     def new_input_set(
         self,
         id: str,
@@ -2236,13 +2374,14 @@ class Application:
 
         if id is None:
             id = safe_id(prefix="version")
+        if name is None:
+            name = id
 
         payload = {
             "id": id,
+            "name": name,
         }
 
-        if name is not None:
-            payload["name"] = name
         if description is not None:
             payload["description"] = description
 
@@ -2934,6 +3073,98 @@ class Application:
             output_dir_path=output_dir_path,
         )
 
+    def update_batch_experiment(
+        self,
+        batch_experiment_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> BatchExperimentInformation:
+        """
+        Update a batch experiment.
+
+        Parameters
+        ----------
+        batch_experiment_id : str
+            ID of the batch experiment to update.
+        name : Optional[str], default=None
+            Optional name of the batch experiment.
+        description : Optional[str], default=None
+            Optional description of the batch experiment.
+
+        Returns
+        -------
+        BatchExperimentInformation
+            The information with the updated batch experiment.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {}
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PATCH",
+            endpoint=f"{self.experiments_endpoint}/batch/{batch_experiment_id}",
+            payload=payload,
+        )
+
+        return BatchExperimentInformation.from_dict(response.json())
+
+    def update_ensemble_definition(
+        self,
+        id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> EnsembleDefinition:
+        """
+        Update an ensemble definition.
+
+        Parameters
+        ----------
+        id : str
+            ID of the ensemble definition to update.
+        name : Optional[str], default=None
+            Optional name of the ensemble definition.
+        description : Optional[str], default=None
+            Optional description of the ensemble definition.
+
+        Returns
+        -------
+        EnsembleDefinition
+            The updated ensemble definition.
+
+        Raises
+        ------
+        ValueError
+            If neither name nor description is updated
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {}
+
+        if name is None and description is None:
+            raise ValueError("Must define at least one value among name and description to modify")
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PATCH",
+            endpoint=f"{self.ensembles_endpoint}/{id}",
+            payload=payload,
+        )
+
+        return EnsembleDefinition.from_dict(response.json())
+
     def update_instance(
         self,
         id: str,
@@ -2997,50 +3228,6 @@ class Application:
 
         return Instance.from_dict(response.json())
 
-    def update_batch_experiment(
-        self,
-        batch_experiment_id: str,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-    ) -> BatchExperimentInformation:
-        """
-        Update a batch experiment.
-
-        Parameters
-        ----------
-        batch_experiment_id : str
-            ID of the batch experiment to update.
-        name : Optional[str], default=None
-            Optional name of the batch experiment.
-        description : Optional[str], default=None
-            Optional description of the batch experiment.
-
-        Returns
-        -------
-        BatchExperimentInformation
-            The information with the updated batch experiment.
-
-        Raises
-        ------
-        requests.HTTPError
-            If the response status code is not 2xx.
-        """
-
-        payload = {}
-
-        if name is not None:
-            payload["name"] = name
-        if description is not None:
-            payload["description"] = description
-
-        response = self.client.request(
-            method="PATCH",
-            endpoint=f"{self.experiments_endpoint}/batch/{batch_experiment_id}",
-            payload=payload,
-        )
-
-        return BatchExperimentInformation.from_dict(response.json())
-
     def update_managed_input(
         self,
         managed_input_id: str,
@@ -3681,65 +3868,40 @@ class Application:
         """
         Auxiliary function to validate the directory path and configuration.
         """
+        input_type = self.__get_input_type(configuration)
 
-        if input_dir_path is None or input_dir_path == "":
+        # If no explicit input type is defined, there is nothing to validate.
+        if input_type is None:
             return
 
-        if configuration is None:
-            raise ValueError(
-                "If dir_path is provided, a RunConfiguration must also be provided.",
-            )
-
-        config_format = self.__extract_config_format(configuration)
-
-        if config_format is None:
-            raise ValueError(
-                "If dir_path is provided, RunConfiguration.format must also be provided.",
-            )
-
-        input_type = self.__extract_input_type(config_format)
-
-        if input_type is None or input_type in (InputFormat.JSON, InputFormat.TEXT):
+        # Validate that the input directory path is provided when explicitly required.
+        dir_types = (InputFormat.MULTI_FILE, InputFormat.CSV_ARCHIVE)
+        if input_type in dir_types and not input_dir_path:
             raise ValueError(
-                "If dir_path is provided, RunConfiguration.format.format_input.input_type must be set to a valid type. "
-                f"Valid types are: {[InputFormat.CSV_ARCHIVE, InputFormat.MULTI_FILE]}",
+                f"If RunConfiguration.format.format_input.input_type is set to {input_type}, "
+                "then input_dir_path must be provided.",
             )
 
-    def __extract_config_format(self, configuration: Union[RunConfiguration, dict[str, Any]]) -> Any:
-        """Extract format from configuration, handling both RunConfiguration objects and dicts."""
-        if isinstance(configuration, RunConfiguration):
-            return configuration.format
-
-        if isinstance(configuration, dict):
-            config_format = configuration.get("format")
-            if config_format is not None and isinstance(config_format, dict):
-                return Format.from_dict(config_format) if hasattr(Format, "from_dict") else config_format
-
-            return config_format
-
-        raise ValueError("Configuration must be a RunConfiguration object or a dict.")
-
-    def __extract_input_type(self, config_format: Any) -> Any:
-        """Extract input type from config format."""
-        if isinstance(config_format, dict):
-            format_input = config_format.get("format_input") or config_format.get("input")
-            if format_input is None:
-                raise ValueError(
-                    "If dir_path is provided, RunConfiguration.format.format_input must also be provided.",
-                )
+    def __get_input_type(self, config: Union[RunConfiguration, dict[str, Any]]) -> Optional[InputFormat]:
+        """
+        Auxiliary function to extract the input type from the run configuration.
+        """
 
-            if isinstance(format_input, dict):
-                return format_input.get("input_type") or format_input.get("type")
+        if config is None:
+            return None
 
-            return getattr(format_input, "input_type", None)
+        if isinstance(config, dict):
+            config = RunConfiguration.from_dict(config)
 
-        # Handle Format object
-        if config_format.format_input is None:
-            raise ValueError(
-                "If dir_path is provided, RunConfiguration.format.format_input must also be provided.",
-            )
+        if (
+            isinstance(config, RunConfiguration)
+            and config.format is not None
+            and config.format.format_input is not None
+            and config.format.format_input.input_type is not None
+        ):
+            return config.format.format_input.input_type
 
-        return config_format.format_input.input_type
+        return None
 
     def __package_inputs(self, dir_path: str) -> str:
         """

nextmv/cloud/ensemble.py

@@ -0,0 +1,248 @@
+"""
+Classes for working with Nextmv Cloud Ensemble Runs.
+
+This module provides classes for interacting with ensemble runs in Nextmv Cloud.
+It details the core data structures for ensemble definitions.
+
+Classes
+-------
+RunGroup
+    A structure to group execution of child runs for an ensemble run.
+RuleObjective
+    An enum that specifies the supported evaluation rule objectives.
+ToleranceType
+    An enum that specifies the supported tolerance types for evaluation rules.
+RuleTolerance
+    A structure for defining tolerance thresholds for an evaluation rule
+EvaluationRule
+    A structure to evaluate run results for an ensemble run.
+EnsembleDefinition
+    Representation of a Nextmv Cloud Ensemble Definition for an application.
+"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Optional
+
+from nextmv.base_model import BaseModel
+
+
+class RunGroup(BaseModel):
+    """A structure to group child runs for an ensemble run.
+
+    You can import the `RunGroup` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunGroup
+    ```
+
+    This class represents a grouping of child runs that share a configuration
+    for ensemble run executions.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the run group.
+    instance_id : str
+        ID of the app instance that this run group executes on.
+    options : dict, optional
+        Runtime options/parameters for the application.
+    repetitions : int, optional
+        The number of times the run is to be repeated on the instance and with
+        the options defined in the run group
+    """
+
+    id: str
+    """The unique identifier of the run group."""
+    instance_id: str
+    """ID of the app instance that this run group executes on."""
+    options: Optional[dict] = None
+    """Runtime options/parameters for the application."""
+    repetitions: Optional[int] = None
+    """The number of times the run is to be repeated on the instance and with
+    the options defined in the run group"""
+
+
+class RuleObjective(str, Enum):
+    """The value of this data determines how a value of a run is optimized to
+    determined which ensemble child run is the "best" for a given metric and
+    rule, as well as which other ones are within tolerance of that run for the
+    purposes of selecting a result for the ensemble run from among the child runs.
+
+    You can import the `RuleObjective` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleObjective
+    ```
+
+    This enum specifies the supported evaluation rule objectives.
+
+    Attributes
+    ----------
+    MAXIMIZE : str
+        Maximize the value of the evaluated metric.
+    MINIMIZE : str
+        Minimize the value of the evaluated metric.
+    """
+
+    MAXIMIZE = "maximize"
+    """Maximize the value of the evaluated metric."""
+    MINIMIZE = "minimize"
+    """Minimize the value of the evaluated metric."""
+
+
+class RuleToleranceType(str, Enum):
+    """The type of comparison used to determine if a run metric is within
+    tolerance of a the "best" run for that rule and metric
+
+    You can import the `RuleToleranceType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleToleranceType
+    ```
+
+    This enum specifies the supported tolerance types.
+
+    Attributes
+    ----------
+    ABSOLUTE : str
+        Uses the absolute difference between the value of the "best" run and
+        the run being evaluated for tolerance
+    RELATIVE : str
+        Uses the the percentage of the "best" run by which the run being
+        evaluted for tolerance differs. A value of `1` is 100%.
+    """
+
+    ABSOLUTE = "absolute"
+    """Uses the absolute difference between the value of the "best" run and
+    the run being evaluated for tolerance"""
+    RELATIVE = "relative"
+    """Uses the the percentage of the "best" run by which the run being
+    evaluted for tolerance differs. A value of `1` is 100%."""
+
+
+class RuleTolerance(BaseModel):
+    """A structure used to determine if a run is within tolerance of of the best
+    run (as determined by the objective of the `EvaluationRule` it is defined on).
+
+    You can import the `RuleTolerance` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleTolerance
+    ```
+
+    This class represents the tolerance on a particular evaluation rule by
+    which a child run may be selected as the result of an ensemble run.
+
+    value : float
+        The value within which runs can deviate from the "best" run
+        for that metric to be considered within tolerance of it.
+    type : ToleranceType
+        The method by which runs are determined to be within tolerance.
+    """
+
+    value: float
+    """The value within which runs can deviate from the "best" run
+    for that metric to be considered within tolerance of it."""
+    type: RuleToleranceType
+    """The method by which runs are determined to be within tolerance."""
+
+
+class EvaluationRule(BaseModel):
+    """A structure to evaluate run results for an ensemble run.
+
+    You can import the `EvaluationRule` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import EvaluationRule
+    ```
+
+    This class represents a rule by which the child runs for an ensemble run
+    will be evaluated for the purpose of selecting an optimal result for the
+    ensemble run.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the evaluation rule.
+    statistics_path : str
+        The path within the statistics of a run output (conforming to Nextmv
+        statistics convention and flattened to a string starting with `$` and
+        delimited by `.` e.g. `$.result.value`.)
+    objective : RuleObjective
+        The objective by which runs are optimized for this rule
+    tolerance : RuleTolerance
+        The tolerance by which runs can be accepted as a potential result
+        for an evaluation rule
+    index : int, optional
+        The index (non-negative integer) of the evalutation rule. Lower indicies
+        are evaluated first.
+    """
+
+    id: str
+    """The unique identifier of the evaluation rule."""
+    statistics_path: str
+    """The path within the statistics of a run output (conforming to Nextmv
+    statistics convention and flattened to a string starting with `$` and
+    delimited by `.` e.g. `$.result.value`.)"""
+    objective: RuleObjective
+    """The objective by which runs are optimized for this rule"""
+    tolerance: RuleTolerance
+    """The tolerance by which runs can be accepted as a potential result
+    for an evaluation rule"""
+    index: int
+    """The index (non-negative integer) of the evalutation rule. Lower indicies
+    are evaluated first."""
+
+
+class EnsembleDefinition(BaseModel):
+    """An ensemble definition for an application.
+
+    You can import the `EnsembleDefinition` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import EnsembleDefinition
+    ```
+
+    A Nextmv Cloud ensemble definition represents a structure by which an
+    application can coordinate and execute, and determine the optimal result of
+    an ensemble run.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the ensemble definition.
+    application_id : str
+        ID of the application that this ensemble definition belongs to.
+    name : str
+        Human-readable name of the ensemble definition.
+    description : str
+        Detailed description of the ensemble definition.
+    run_groups : list[RunGroup], optional
+        The run groups that structure the execution of an ensemble run
+    rules : list[EvaluationRule], optional
+        The rules by which ensemble child runs are evaluated
+        to find an optimal result.
+    created_at : datetime
+        Timestamp when the ensemble definition was created.
+    updated_at : datetime
+        Timestamp when the ensemble definition was last updated.
+    """
+
+    id: str
+    """The unique identifier of the ensemble definition."""
+    application_id: str
+    """ID of the application that this ensemble definition belongs to."""
+    name: str = ""
+    """Human-readable name of the ensemble definition."""
+    description: str = ""
+    """Detailed description of the ensemble definition."""
+    run_groups: list[RunGroup]
+    """The run groups that structure the execution of an ensemble run"""
+    rules: list[EvaluationRule]
+    """The rules by which ensemble child runs are evaluated
+    to find an optimal result."""
+    created_at: datetime
+    """Timestamp when the ensemble definition was created."""
+    updated_at: datetime
+    """Timestamp when the ensemble definition was last updated."""

nextmv/cloud/package.py

@@ -222,7 +222,7 @@ def __handle_python(
     __install_dependencies(manifest, app_dir, temp_dir)
 
 
-def __install_dependencies(
+def __install_dependencies(  # noqa: C901 # complexity
     manifest: Manifest,
     app_dir: str,
     temp_dir: str,
@@ -253,31 +253,58 @@ def __install_dependencies(
         if not os.path.isfile(os.path.join(app_dir, pip_requirements)):
             raise FileNotFoundError(f"pip requirements file '{pip_requirements}' not found in '{app_dir}'")
 
+    platform_filter = []
+    if not manifest.python.arch or manifest.python.arch == "arm64":
+        platform_filter.extend(
+            [
+                "--platform=manylinux2014_aarch64",
+                "--platform=manylinux_2_17_aarch64",
+                "--platform=manylinux_2_24_aarch64",
+                "--platform=manylinux_2_28_aarch64",
+                "--platform=linux_aarch64",
+            ]
+        )
+    elif manifest.python.arch == "amd64":
+        platform_filter.extend(
+            [
+                "--platform=manylinux2014_x86_64",
+                "--platform=manylinux_2_17_x86_64",
+                "--platform=manylinux_2_24_x86_64",
+                "--platform=manylinux_2_28_x86_64",
+                "--platform=linux_x86_64",
+            ]
+        )
+    else:
+        raise Exception(f"unknown architecture '{manifest.python.arch}' specified in manifest")
+
+    version_filter = ["--python-version=3.11"]
+    if manifest.python.version:
+        __confirm_python_bundling_version(manifest.python.version)
+        version_filter = [f"--python-version={manifest.python.version}"]
+
     py_cmd = __get_python_command()
     dep_dir = os.path.join(".nextmv", "python", "deps")
-    command = [
-        py_cmd,
-        "-m",
-        "pip",
-        "install",
-        "-r",
-        pip_requirements,
-        "--platform=manylinux2014_aarch64",
-        "--platform=manylinux_2_17_aarch64",
-        "--platform=manylinux_2_24_aarch64",
-        "--platform=manylinux_2_28_aarch64",
-        "--platform=linux_aarch64",
-        "--only-binary=:all:",
-        "--python-version=3.11",
-        "--implementation=cp",
-        "--upgrade",
-        "--no-warn-conflicts",
-        "--target",
-        os.path.join(temp_dir, dep_dir),
-        "--no-user",  # We explicitly avoid user mode (mainly to fix issues with Windows store Python installations)
-        "--no-input",
-        "--quiet",
-    ]
+    command = (
+        [
+            py_cmd,
+            "-m",
+            "pip",
+            "install",
+            "-r",
+            pip_requirements,
+            "--only-binary=:all:",
+            "--implementation=cp",
+            "--upgrade",
+            "--no-warn-conflicts",
+            "--target",
+            os.path.join(temp_dir, dep_dir),
+            "--no-user",  # We explicitly avoid user mode (mainly to fix issues with Windows store Python installations)
+            "--no-input",
+            "--quiet",
+        ]
+        + platform_filter
+        + version_filter
+    )
     result = subprocess.run(
         command,
         cwd=app_dir,
@@ -381,6 +408,17 @@ def __confirm_python_version(output: str) -> None:
     raise Exception("python version 3.9 or higher is required")
 
 
+def __confirm_python_bundling_version(version: str) -> None:
+    # Only accept versions in the form "major.minor" where both are integers
+    re_version = re.compile(r"^(\d+)\.(\d+)$")
+    match = re_version.fullmatch(version)
+    if match:
+        major, minor = int(match.group(1)), int(match.group(2))
+        if major == 3 and minor >= 9:
+            return
+    raise Exception(f"python version 3.9 or higher is required for bundling, got {version}")
+
+
 def __compress_tar(source: str, target: str) -> tuple[str, int]:
     """Compress the source directory into a tar.gz file in the target"""
 

nextmv/local/executor.py

@@ -32,6 +32,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 import tempfile
 from datetime import datetime, timezone
 from typing import Any, Optional, Union
@@ -143,7 +144,7 @@ def execute_run(
             # supporting a Python-first experience, so we are not summoning
             # applications that are not Python-based.
             entrypoint = os.path.join(temp_src, manifest.entrypoint)
-            args = ["python", entrypoint] + options_args(options)
+            args = [sys.executable, entrypoint] + options_args(options)
 
             result = subprocess.run(
                 args,

nextmv/manifest.py

@@ -49,7 +49,7 @@ from enum import Enum
 from typing import Any, Optional, Union
 
 import yaml
-from pydantic import AliasChoices, Field
+from pydantic import AliasChoices, Field, field_validator
 
 from nextmv.base_model import BaseModel
 from nextmv.input import InputFormat
@@ -166,6 +166,43 @@ class ManifestRuntime(str, Enum):
     Based on the python runtime, it provisions (pre-installs) the Hexaly solver
     to run Python applications.
     """
+    CUOPT = "ghcr.io/nextmv-io/runtime/cuopt:latest"
+    """
+    A runtime providing the NVIDIA cuOpt solver.
+    """
+
+
+class ManifestPythonArch(str, Enum):
+    """
+    Target architecture for bundling Python apps.
+
+    You can import the `ManifestPythonArch` class directly from `nextmv`:
+
+    ```python
+    from nextmv import ManifestPythonArch
+    ```
+
+    Attributes
+    ----------
+    ARM64 : str
+        ARM 64-bit architecture.
+    AMD64 : str
+        AMD 64-bit architecture.
+
+    Examples
+    --------
+    >>> from nextmv import ManifestPythonArch
+    >>> arch = ManifestPythonArch.ARM64
+    >>> arch
+    <ManifestPythonArch.ARM64: 'arm64'>
+    >>> str(arch)
+    'arm64'
+    """
+
+    ARM64 = "arm64"
+    """ARM 64-bit architecture."""
+    AMD64 = "amd64"
+    """AMD 64-bit architecture."""
 
 
 class ManifestBuild(BaseModel):
@@ -325,6 +362,12 @@ class ManifestPython(BaseModel):
     Contains (additional) Python dependencies that will be bundled with the
     app.
     """
+    arch: Optional[ManifestPythonArch] = None
+    """The architecture this model is meant to run on. One of "arm64" or "amd64". Uses
+    "arm64" if not specified."""
+    version: Optional[Union[str, float]] = None
+    """The Python version this model is meant to run with. Uses "3.11" if not specified.
+    """
     model: Optional[ManifestPythonModel] = None
     """Information about an encoded decision model.
 
@@ -332,6 +375,17 @@ class ManifestPython(BaseModel):
     from the app bundle.
     """
 
+    @field_validator("version", mode="before")
+    @classmethod
+    def validate_version(cls, v: Optional[Union[str, float]]) -> Optional[str]:
+        # We allow the version to be a float in the manifest for convenience, but we want
+        # to store it as a string internally.
+        if v is None:
+            return None
+        if isinstance(v, float):
+            return str(v)
+        return v
+
 
 class ManifestOptionUI(BaseModel):
     """
@@ -1025,7 +1079,12 @@ class Manifest(BaseModel):
 
     def model_post_init(self, __context) -> None:
         if self.entrypoint is None:
-            if self.runtime in (ManifestRuntime.PYTHON, ManifestRuntime.HEXALY, ManifestRuntime.PYOMO):
+            if self.runtime in (
+                ManifestRuntime.PYTHON,
+                ManifestRuntime.HEXALY,
+                ManifestRuntime.PYOMO,
+                ManifestRuntime.CUOPT,
+            ):
                 self.entrypoint = "./main.py"
             elif self.runtime == ManifestRuntime.DEFAULT:
                 self.entrypoint = "./main"

{nextmv-0.32.0.dist-info → nextmv-0.33.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.32.0
+Version: 0.33.0
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/

{nextmv-0.32.0.dist-info → nextmv-0.33.0.dist-info}/RECORD

@@ -1,12 +1,12 @@
-nextmv/__about__.py,sha256=8eaqWsF6AYp-9Iqzy05LB4Lu1iuUyTkZ5v8LPco9uLM,24
+nextmv/__about__.py,sha256=VyKoqs7qvl1UtyON_wE484wOoQ1-D2LWfsRhOrha9gg,24
 nextmv/__entrypoint__.py,sha256=dA0iwwHtrq6Z9w9FxmxKLoBGLyhe7jWtUAU-Y3PEgHg,1094
-nextmv/__init__.py,sha256=pW2HMcJnNSFqF_tj77TtqpddEeCosTKS7NxGNPDp7mU,3620
+nextmv/__init__.py,sha256=uM80mRRs2Ht2dP60DvxR11HmunFJ7EL7XUJHtKQi2qI,3683
 nextmv/_serialization.py,sha256=JlSl6BL0M2Esf7F89GsGIZ__Pp8RnFRNM0UxYhuuYU4,2853
 nextmv/base_model.py,sha256=qmJ4AsYr9Yv01HQX_BERrn3229gyoZrYyP9tcyqNfeU,2311
 nextmv/deprecated.py,sha256=kEVfyQ-nT0v2ePXTNldjQG9uH5IlfQVy3L4tztIxwmU,1638
 nextmv/input.py,sha256=m9sVfO9ZL3F5i1l8amEtlWlbkekyUP4C3y9DduHWGFs,40211
 nextmv/logger.py,sha256=kNIbu46MisrzYe4T0hNMpWfRTKKacDVvbtQcNys_c_E,2513
-nextmv/manifest.py,sha256=wzGDrGleIgYvRvKyy73acjd68cGdCLD_7x_Dy3UhCaI,44266
+nextmv/manifest.py,sha256=jCu5RUl6bip4kTDh4zaD4PTYNOIGHWKm34kfXD_rpzw,45898
 nextmv/model.py,sha256=vI3pSV3iTwjRPflar7nAg-6h98XRUyi9II5O2J06-Kc,15018
 nextmv/options.py,sha256=yPJu5lYMbV6YioMwAXv7ctpZUggLXKlZc9CqIbUFvE4,37895
 nextmv/output.py,sha256=HdvWYG3gIzwoXquulaEVI4LLchXJDjkbag0BkBPM0vQ,55128
@@ -14,15 +14,16 @@ nextmv/polling.py,sha256=nfefvWI1smm-lIzaXE-4DMlojp6KXIvVi88XLJYUmo8,9724
 nextmv/run.py,sha256=lAWWkLml1C7wkXSvN8orBjudoz72Qv5ZCHCWY9e7xaY,45813
 nextmv/safe.py,sha256=VAK4fGEurbLNji4Pg5Okga5XQSbI4aI9JJf95_68Z20,3867
 nextmv/status.py,sha256=SCDLhh2om3yeO5FxO0x-_RShQsZNXEpjHNdCGdb3VUI,2787
-nextmv/cloud/__init__.py,sha256=5B2aMKffI_WSFlVlT-oO7ISMqxJeN9XEoqmy7ghKmOI,4651
-nextmv/cloud/acceptance_test.py,sha256=1IQ2w7Imu_NAKknLQYNIIV9i_XIf8tmNHVTAOBEtsU8,25675
+nextmv/cloud/__init__.py,sha256=2wI72lhWq81BYv1OpS0OOTT5-3sivpX0H4z5ANPoLMc,5051
+nextmv/cloud/acceptance_test.py,sha256=ZEzCMrfJF-nUFr1nEr4IDgcoyavPhnanjFuPBJ79tAk,27731
 nextmv/cloud/account.py,sha256=jIdGNyI3l3dVh2PuriAwAOrEuWRM150WgzxcBMVBNRw,6058
-nextmv/cloud/application.py,sha256=xUipgYYzqZpda0242d96zft78ZJsbz7KG361hiTBJvQ,134954
+nextmv/cloud/application.py,sha256=zbirm_bbihnzhKsO8gAO_dJRAJV4FtXsQsSaismgt-I,139298
 nextmv/cloud/batch_experiment.py,sha256=13ciRpgBabMMTyazfdfEAymD3rTPrTAAorECsANxxuA,10397
 nextmv/cloud/client.py,sha256=E0DiUb377jvEnpXlRnfT1PGCI0Jm0lTUoX5VqeU91lk,18165
+nextmv/cloud/ensemble.py,sha256=glrRgyRFcEH12fNUhEl1FOo6xOTDEaF478dxfX0wj2Y,8604
 nextmv/cloud/input_set.py,sha256=NkzA6_hwgD-YwoirzwvZrObIoBTfurry7Os3jo4DyXc,4236
 nextmv/cloud/instance.py,sha256=SS4tbp0LQMWDaeYpwcNxJei82oi_Hozv1t5i3QGjASY,4024
-nextmv/cloud/package.py,sha256=cG75DptN4sxXaT8ruDh2EY2duaK5Jwg16X2LV0BP8ts,13021
+nextmv/cloud/package.py,sha256=Xmt-daAeN9QJKpquV28IiZa2eYCX0P3wSS564JHvrtY,14495
 nextmv/cloud/scenario.py,sha256=JRFTDiFBcrgud6wE2qDHUu5oO-Ur3zbPYhhB6ONCxTo,14263
 nextmv/cloud/secrets.py,sha256=fA5cX0jfTsPVZWV7433wzETGlXpWRLHGswuObx9e6FQ,6820
 nextmv/cloud/url.py,sha256=Fz70ywkWdCLmP21ZBmJwZi5kDbjpmsX_VlwVF_xQeHg,1836
@@ -38,12 +39,12 @@ nextmv/default_app/src/main.py,sha256=WWeN_xl_mcPhICl3rSCvdEjRkFXGmAnej88FhS-fAm
 nextmv/default_app/src/visuals.py,sha256=WYK_YBnLmYo3TpVev1CpoNCuW5R7hk9QIkeCmvMn1Fs,1014
 nextmv/local/__init__.py,sha256=6BsoqlK4dw6X11_uKzz9gBPfxKpdiol2FYO8R3X73SE,116
 nextmv/local/application.py,sha256=qq14ihKxymg5NHqhU56qTu6lVmMYWLGYUJC4MrhWB68,45815
-nextmv/local/executor.py,sha256=PFeEZaGhEq9mCaeJbrFBStDpsTWv3j6Z89_SjbnphiE,24321
+nextmv/local/executor.py,sha256=ohAUrIRohcH_qGglK1hSFR0W6bPBSuMAcMwVkW5G4vM,24338
 nextmv/local/geojson_handler.py,sha256=7FavJdkUonop-yskjis0x3qFGB8A5wZyoBUblw-bVhw,12540
 nextmv/local/local.py,sha256=wUHuoAXqJIZpTJBh056hmQuiPEjlZvLTR2BC6Ino-WI,2619
 nextmv/local/plotly_handler.py,sha256=bLb50e3AkVr_W-F6S7lXfeRdN60mG2jk3UElNmhoMWU,1930
 nextmv/local/runner.py,sha256=hwkITHrQG_J9TzxufnaP1mjLWG-iSsNQD66UFZY4pp4,8602
-nextmv-0.32.0.dist-info/METADATA,sha256=1GjISld5ZhyMzugNVUIH8ecX9sLHJU_p3e8qfao2A84,16008
-nextmv-0.32.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nextmv-0.32.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.32.0.dist-info/RECORD,,
+nextmv-0.33.0.dist-info/METADATA,sha256=JRt0lALKQ1i0E_J2AhgozeUtC7kv_YGHsqK_-VDePsw,16008
+nextmv-0.33.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nextmv-0.33.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.33.0.dist-info/RECORD,,