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

nextmv/__about__.py

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

nextmv/__init__.py

@@ -3,8 +3,6 @@
 from .__about__ import __version__
 from .base_model import BaseModel as BaseModel
 from .base_model import from_dict as from_dict
-from .input import DEFAULT_INPUT_JSON_FILE as DEFAULT_INPUT_JSON_FILE
-from .input import INPUTS_KEY as INPUTS_KEY
 from .input import DataFile as DataFile
 from .input import Input as Input
 from .input import InputFormat as InputFormat
@@ -23,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
@@ -31,13 +30,6 @@ from .model import ModelConfiguration as ModelConfiguration
 from .options import Option as Option
 from .options import Options as Options
 from .options import Parameter as Parameter
-from .output import ASSETS_KEY as ASSETS_KEY
-from .output import DEFAULT_OUTPUT_JSON_FILE as DEFAULT_OUTPUT_JSON_FILE
-from .output import LOGS_FILE as LOGS_FILE
-from .output import LOGS_KEY as LOGS_KEY
-from .output import OUTPUTS_KEY as OUTPUTS_KEY
-from .output import SOLUTIONS_KEY as SOLUTIONS_KEY
-from .output import STATISTICS_KEY as STATISTICS_KEY
 from .output import Asset as Asset
 from .output import DataPoint as DataPoint
 from .output import LocalOutputWriter as LocalOutputWriter
@@ -66,13 +58,17 @@ from .run import Format as Format
 from .run import FormatInput as FormatInput
 from .run import FormatOutput as FormatOutput
 from .run import Metadata as Metadata
+from .run import OptionsSummaryItem as OptionsSummaryItem
+from .run import Run as Run
 from .run import RunConfiguration as RunConfiguration
 from .run import RunInformation as RunInformation
+from .run import RunInfoStatistics as RunInfoStatistics
 from .run import RunLog as RunLog
 from .run import RunQueuing as RunQueuing
 from .run import RunResult as RunResult
 from .run import RunType as RunType
 from .run import RunTypeConfiguration as RunTypeConfiguration
+from .run import StatisticsIndicator as StatisticsIndicator
 from .run import TrackedRun as TrackedRun
 from .run import TrackedRunStatus as TrackedRunStatus
 from .run import run_duration as run_duration

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
@@ -64,6 +65,7 @@ from nextmv.run import (
     Format,
     FormatInput,
     FormatOutput,
+    Run,
     RunConfiguration,
     RunInformation,
     RunLog,
@@ -128,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.
@@ -137,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(
@@ -289,7 +294,8 @@ class Application:
 
     def batch_experiment(self, batch_id: str) -> BatchExperiment:
         """
-        Get a batch experiment.
+        Get a batch experiment. This method also returns the runs of the batch
+        experiment under the `.runs` attribute.
 
         Parameters
         ----------
@@ -318,7 +324,17 @@ class Application:
             endpoint=f"{self.experiments_endpoint}/batch/{batch_id}",
         )
 
-        return BatchExperiment.from_dict(response.json())
+        exp = BatchExperiment.from_dict(response.json())
+
+        runs_response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/batch/{batch_id}/runs",
+        )
+
+        runs = [Run.from_dict(run) for run in runs_response.json().get("runs", [])]
+        exp.runs = runs
+
+        return exp
 
     def batch_experiment_metadata(self, batch_id: str) -> BatchExperimentMetadata:
         """
@@ -503,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.
@@ -551,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:
         """
@@ -736,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.
@@ -818,6 +921,28 @@ class Application:
 
         return [ManagedInput.from_dict(managed_input) for managed_input in response.json()]
 
+    def list_runs(self) -> list[Run]:
+        """
+        List all runs.
+
+        Returns
+        -------
+        list[Run]
+            List of runs.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.endpoint}/runs",
+        )
+
+        return [Run.from_dict(run) for run in response.json().get("runs", [])]
+
     def list_scenario_tests(self) -> list[BatchExperimentMetadata]:
         """
         List all batch scenario tests. Scenario tests are based on the batch
@@ -1280,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,
@@ -2202,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
 
@@ -2759,7 +2932,7 @@ class Application:
         Examples
         --------
         >>> from nextmv.cloud import Application
-        >>> from nextmv.cloud.run import TrackedRun
+        >>> from nextmv import TrackedRun
         >>> app = Application(id="app_123")
         >>> tracked_run = TrackedRun(input={"data": [...]}, output={"solution": [...]})
         >>> run_id = app.track_run(tracked_run)
@@ -2900,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,
@@ -2963,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,
@@ -3647,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:
+        # 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 must also be provided.",
+                f"If RunConfiguration.format.format_input.input_type is set to {input_type}, "
+                "then input_dir_path must be provided.",
             )
 
-        input_type = self.__extract_input_type(config_format)
-
-        if input_type is None or input_type in (InputFormat.JSON, InputFormat.TEXT):
-            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]}",
-            )
-
-    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:
         """