nextmv 0.32.0__tar.gz → 0.33.0.dev0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.32.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.32.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.32.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.32.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
@@ -129,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.
@@ -138,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(
@@ -515,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.
@@ -563,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:
         """
@@ -748,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.
@@ -1314,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,
@@ -2236,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
 
@@ -2934,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,
@@ -2997,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.33.0.dev0/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-0.32.0 → nextmv-0.33.0.dev0}/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-0.32.0/nextmv/__about__.py

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