nextmv 0.32.0__tar.gz → 0.33.0__tar.gz

{nextmv-0.32.0 → nextmv-0.33.0}/PKG-INFO

@@ -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.33.0/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v0.33.0"

{nextmv-0.32.0 → nextmv-0.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-0.32.0 → nextmv-0.33.0}/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-0.32.0 → nextmv-0.33.0}/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-0.32.0 → nextmv-0.33.0}/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:
         """