nextmv 0.31.0__tar.gz → 0.33.0.dev0__tar.gz

{nextmv-0.31.0 → nextmv-0.33.0.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.31.0
+Version: 0.33.0.dev0
 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.dev0/nextmv/__about__.py

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

{nextmv-0.31.0 → nextmv-0.33.0.dev0}/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
@@ -31,13 +29,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 +57,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-0.31.0 → nextmv-0.33.0.dev0}/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.31.0 → nextmv-0.33.0.dev0}/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,57 @@ 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."""
+
+    def __new__(cls, value: str):
+        """Create a new ToleranceType instance and emit deprecation warning."""
+        deprecated(
+            "ToleranceType",
+            "ToleranceType is deprecated and will be removed in a future version. "
+            "Please use MetricToleranceType instead",
+        )
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        return obj
+
+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"
@@ -249,7 +304,6 @@ class ToleranceType(str, Enum):
     relative = "relative"
     """Relative tolerance type."""
 
-
 class MetricTolerance(BaseModel):
     """
     Tolerance used for a metric in an acceptance test.
@@ -265,22 +319,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.31.0 → nextmv-0.33.0.dev0}/nextmv/cloud/application.py

@@ -46,6 +46,11 @@ 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 +69,7 @@ from nextmv.run import (
     Format,
     FormatInput,
     FormatOutput,
+    Run,
     RunConfiguration,
     RunInformation,
     RunLog,
@@ -128,6 +134,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 +145,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 +298,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 +328,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 +523,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 +595,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 +813,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 +925,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 +1409,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 +2378,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 +2936,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 +3077,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 +3232,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,

{nextmv-0.31.0 → nextmv-0.33.0.dev0}/nextmv/cloud/batch_experiment.py

@@ -21,6 +21,7 @@ from typing import Any, Optional
 
 from nextmv.base_model import BaseModel
 from nextmv.cloud.input_set import InputSet
+from nextmv.run import Run
 
 
 class ExperimentStatus(str, Enum):
@@ -191,7 +192,10 @@ class BatchExperiment(BatchExperimentInformation):
     instance_ids : list[str]
         List of instance IDs used for the experiment.
     grouped_distributional_summaries : list[dict[str, Any]], optional
-        Grouped distributional summaries of the batch experiment. Defaults to None.
+        Grouped distributional summaries of the batch experiment. Defaults to
+        None.
+    runs : list[Run], optional
+        List of runs in the batch experiment. Defaults to None.
     """
 
     input_set_id: str
@@ -200,6 +204,8 @@ class BatchExperiment(BatchExperimentInformation):
     """List of instance IDs used for the experiment."""
     grouped_distributional_summaries: Optional[list[dict[str, Any]]] = None
     """Grouped distributional summaries of the batch experiment."""
+    runs: Optional[list[Run]] = None
+    """List of runs in the batch experiment."""
 
 
 class BatchExperimentRun(BaseModel):