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

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):

nextmv/cloud/ensemble.py

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

nextmv/cloud/package.py

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

nextmv/default_app/README.md

@@ -4,6 +4,7 @@ This is the basic structure of a Nextmv application.
 
 ```text
 ├── app.yaml
+├── main.py
 ├── README.md
 ├── requirements.txt
 └── src
@@ -11,7 +12,21 @@ This is the basic structure of a Nextmv application.
 
 * `app.yaml`: App manifest, containing the configuration to run the app
   remotely on Nextmv Cloud.
+* `main.py`: Entry point for the app.
 * `README.md`: Description of the app.
 * `requirements.txt`: Python dependencies for the app.
-* `src/`: Source code for the app. The `main.py` file is the entry point for
-  the app.
+* `src/`: Source code for the app.
+
+A sample input file is also provided as `input.json`.
+
+1. Install packages.
+
+    ```bash
+    pip3 install -r requirements.txt
+    ```
+
+2. Run the app.
+
+    ```bash
+    cat input.json | python3 main.py
+    ```

nextmv/default_app/app.yaml

@@ -9,5 +9,4 @@ python:
 # (e.g.: configs/*.json) is supported.
 files:
   - src/
-
-entrypoint: src/main.py
+  - main.py

nextmv/default_app/input.json

@@ -0,0 +1,5 @@
+{
+  "name": "Patches",
+  "radius": 6378,
+  "distance": 147.6
+}

nextmv/default_app/main.py

@@ -0,0 +1,37 @@
+from src.visuals import create_visuals
+
+import nextmv
+
+# Read the input from stdin.
+input = nextmv.load()
+name = input.data["name"]
+
+options = nextmv.Options(
+    nextmv.Option("details", bool, True, "Print details to logs. Default true.", False),
+)
+
+##### Insert model here
+
+# Print logs that render in the run view in Nextmv Console.
+message = f"Hello, {name}"
+nextmv.log(message)
+
+if options.details:
+    detail = f"You are {input.data['distance']} million km from the sun"
+    nextmv.log(detail)
+
+assets = create_visuals(name, input.data["radius"], input.data["distance"])
+
+# Write output and statistics.
+output = nextmv.Output(
+    options=options,
+    solution={"message": message},
+    statistics=nextmv.Statistics(
+        result=nextmv.ResultStatistics(
+            value=1.23,
+            custom={"message": message},
+        ),
+    ),
+    assets=assets,
+)
+nextmv.write(output)

nextmv/input.py

@@ -21,12 +21,10 @@ Functions
 load
     Load input data using a specified loader.
 
-Constants
----------
+Attributes
+----------
 INPUTS_KEY : str
     Key used for identifying inputs in the run.
-DEFAULT_INPUT_JSON_FILE : str
-    Constant for the default input JSON file name.
 """
 
 import copy
@@ -47,10 +45,6 @@ INPUTS_KEY = "inputs"
 """
 Inputs key constant used for identifying inputs in the run.
 """
-DEFAULT_INPUT_JSON_FILE = "input.json"
-"""
-Constant for the default input JSON file name.
-"""
 
 
 class InputFormat(str, Enum):