nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cli/cloud/ensemble/create.py

@@ -0,0 +1,413 @@
+"""
+This module defines the cloud ensemble create command for the Nextmv CLI.
+"""
+
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import enum_values, error, in_progress, print_json
+from nextmv.cli.options import AppIDOption, ProfileOption
+from nextmv.cloud.ensemble import EvaluationRule, RuleObjective, RuleTolerance, RuleToleranceType, RunGroup
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command(
+    # AVOID USING THE HELP PARAMETER WITH TYPER COMMAND DECORATOR. For
+    # consistency, commands should be documented using docstrings. We were
+    # forced to use help here to work around f-string limitations in
+    # docstrings.
+    help=f"""
+    Create a new Nextmv Cloud ensemble definition.
+
+    An ensemble definition coordinates the execution of multiple child runs for
+    an application and determines the optimal result from those runs. Each
+    ensemble definition contains run groups and evaluation rules.
+
+    [bold][underline]Run Groups[/underline][/bold]
+
+    Run groups are provided as [magenta]json[/magenta] objects using the
+    --run-groups flag. Each run group specifies how child runs are executed.
+
+    You can provide run groups in three ways:
+    - A single run group as a [magenta]json[/magenta] object.
+    - Multiple run groups by repeating the --run-groups flag.
+    - Multiple run groups as a [magenta]json[/magenta] array in a single --run-groups flag.
+
+    Each run group must have the following fields:
+    - [magenta]id[/magenta]: Unique identifier for the run group (required).
+    - [magenta]instance_id[/magenta]: The instance to execute runs on (required).
+    - [magenta]options[/magenta]: Runtime options/parameters (optional). Options should be provided as a
+      [magenta]json[/magenta] object with [magenta]string[/magenta] key-value pairs.
+    - [magenta]repetitions[/magenta]: Number of times to repeat the run (optional).
+
+    Object format:
+    [dim]{{
+        "id": "rg1",
+        "instance_id": "inst-123",
+        "options": {{"param": "value"}},
+        "repetitions": 5
+    }}[/dim]
+
+    [bold][underline]Evaluation Rules[/underline][/bold]
+
+    Evaluation rules are provided as [magenta]json[/magenta] objects using the
+    --rules flag. Each rule determines how to evaluate and select the best
+    result from the child runs.
+
+    You can provide rules in three ways:
+    - A single rule as a [magenta]json[/magenta] object.
+    - Multiple rules by repeating the --rules flag.
+    - Multiple rules as a [magenta]json[/magenta] array in a single --rules flag.
+
+    Each rule must have the following fields:
+    - [magenta]id[/magenta]: Unique identifier for the rule (required).
+    - [magenta]statistics_path[/magenta]: JSONPath to the metric (e.g., [magenta]$.result.value[/magenta]) (required).
+    - [magenta]objective[/magenta]: Objective for the evaluation (required).
+      Allowed values: {enum_values(RuleObjective)}.
+    - [magenta]tolerance[/magenta]: Object with the following fields (required):
+        - [magenta]value[/magenta]: Tolerance value (float).
+        - [magenta]type[/magenta]: Tolerance type. Allowed values: {enum_values(RuleToleranceType)}.
+    - [magenta]index[/magenta]: Evaluation order - lower indices evaluated first (required).
+
+    Object format:
+    [dim]{{
+        "id": "rule1",
+        "statistics_path": "$.result.value",
+        "objective": "minimize",
+        "tolerance": {{"value": 0.1, "type": "relative"}},
+        "index": 0
+    }}[/dim]
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Create an ensemble definition with a single run group and rule.
+        $ [dim]RUN_GROUP='{{
+            "id": "rg1",
+            "instance_id": "inst-123"
+        }}'
+        RULE='{{
+            "id": "rule1",
+            "statistics_path": "$.result.value",
+            "objective": "minimize",
+            "tolerance": {{"value": 0.1, "type": "relative"}},
+            "index": 0
+        }}'
+        nextmv cloud ensemble create --app-id hare-app --run-groups "$RUN_GROUP" --rules "$RULE"[/dim]
+
+    - Create with multiple run groups by repeating the flag.
+        $ [dim]RUN_GROUP_1='{{
+            "id": "rg1",
+            "instance_id": "inst-123"
+        }}'
+        RUN_GROUP_2='{{
+            "id": "rg2",
+            "instance_id": "inst-456",
+            "options": {{"param": "value"}}
+        }}'
+        RULE='{{
+            "id": "rule1",
+            "statistics_path": "$.result.value",
+            "objective": "minimize",
+            "tolerance": {{"value": 0.1, "type": "relative"}},
+            "index": 0
+        }}'
+        nextmv cloud ensemble create --app-id hare-app --run-groups "$RUN_GROUP_1" --run-groups "$RUN_GROUP_2" \\
+            --rules "$RULE"[/dim]
+
+    - Create with multiple items in a single JSON array.
+        $ [dim]RUN_GROUPS='[
+            {{"id": "rg1", "instance_id": "inst-123"}},
+            {{"id": "rg2", "instance_id": "inst-456"}}
+        ]'
+        RULES='[{{
+            "id": "rule1",
+            "statistics_path": "$.result.value",
+            "objective": "minimize",
+            "tolerance": {{"value": 0.1, "type": "relative"}},
+            "index": 0
+        }}]'
+        nextmv cloud ensemble create --app-id hare-app --run-groups "$RUN_GROUPS" --rules "$RULES"[/dim]
+
+    - Create with custom ID, name, and description.
+        $ [dim]RUN_GROUP='{{
+            "id": "rg1",
+            "instance_id": "inst-123"
+        }}'
+        RULE='{{
+            "id": "rule1",
+            "statistics_path": "$.result.value",
+            "objective": "minimize",
+            "tolerance": {{"value": 0.1, "type": "relative"}},
+            "index": 0
+        }}'
+        nextmv cloud ensemble create --app-id hare-app \\
+            --ensemble-definition-id prod-ensemble --name "Production Ensemble" \\
+            --description "Production ensemble with multiple solvers" \\
+            --run-groups "$RUN_GROUP" --rules "$RULE"[/dim]
+
+    - Create with run group repetitions.
+        $ [dim]RUN_GROUP='{{
+            "id": "rg1",
+            "instance_id": "inst-123",
+            "repetitions": 5
+        }}'
+        RULE='{{
+            "id": "rule1",
+            "statistics_path": "$.result.value",
+            "objective": "minimize",
+            "tolerance": {{"value": 0.1, "type": "relative"}},
+            "index": 0
+        }}'
+        nextmv cloud ensemble create --app-id hare-app --run-groups "$RUN_GROUP" --rules "$RULE"[/dim]
+    """
+)
+def create(
+    app_id: AppIDOption,
+    run_groups: Annotated[
+        list[str],
+        typer.Option(
+            "--run-groups",
+            "-r",
+            help="Run groups to configure for the ensemble. Data should be valid [magenta]json[/magenta]. "
+            "Pass multiple run groups by repeating the flag, or providing a list of objects. "
+            "See command help for details on run group formatting.",
+            metavar="RUN_GROUPS",
+        ),
+    ],
+    rules: Annotated[
+        list[str],
+        typer.Option(
+            "--rules",
+            "-u",
+            help="Evaluation rules to configure for the ensemble. Data should be valid [magenta]json[/magenta]. "
+            "Pass multiple rules by repeating the flag, or providing a list of objects. "
+            "See command help for details on rule formatting.",
+            metavar="RULES",
+        ),
+    ],
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="An optional description for the ensemble definition.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="A name for the ensemble definition.",
+            metavar="NAME",
+        ),
+    ] = None,
+    ensemble_definition_id: Annotated[
+        str | None,
+        typer.Option(
+            "--ensemble-definition-id",
+            "-e",
+            help="The ID to assign to the new ensemble definition. If not provided, a random ID will be generated.",
+            envvar="NEXTMV_ENSEMBLE_DEFINITION_ID",
+            metavar="ENSEMBLE_DEFINITION_ID",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Creating ensemble definition...")
+
+    # Build the run groups and rules lists from the CLI options
+    run_groups_list = build_run_groups(run_groups)
+    rules_list = build_rules(rules)
+
+    ensemble_definition = cloud_app.new_ensemble_definition(
+        run_groups=run_groups_list,
+        rules=rules_list,
+        id=ensemble_definition_id,
+        name=name,
+        description=description,
+    )
+    print_json(ensemble_definition.to_dict())
+
+
+def build_run_groups(run_groups: list[str]) -> list[RunGroup]:
+    """
+    Builds the run groups list from the CLI option(s).
+
+    Parameters
+    ----------
+    run_groups : list[str]
+        List of run groups provided via the CLI.
+
+    Returns
+    -------
+    list[RunGroup]
+        The built run groups list.
+    """
+    import json
+
+    run_groups_list = []
+
+    for run_group_str in run_groups:
+        try:
+            run_group_data = json.loads(run_group_str)
+
+            # Handle the case where the value is a list of run groups.
+            if isinstance(run_group_data, list):
+                for ix, item in enumerate(run_group_data):
+                    if item.get("id") is None or item.get("instance_id") is None:
+                        error(
+                            f"Invalid run group format at index [magenta]{ix}[/magenta] in "
+                            f"[magenta]{run_group_str}[/magenta]. Each run group must have "
+                            "[magenta]id[/magenta] and [magenta]instance_id[/magenta] fields."
+                        )
+
+                    run_group = RunGroup(
+                        id=item["id"],
+                        instance_id=item["instance_id"],
+                        options=item.get("options"),
+                        repetitions=item.get("repetitions"),
+                    )
+                    run_groups_list.append(run_group)
+
+            # Handle the case where the value is a single run group.
+            elif isinstance(run_group_data, dict):
+                if run_group_data.get("id") is None or run_group_data.get("instance_id") is None:
+                    error(
+                        f"Invalid run group format in [magenta]{run_group_str}[/magenta]. "
+                        "Each run group must have [magenta]id[/magenta] and [magenta]instance_id[/magenta] fields."
+                    )
+
+                run_group = RunGroup(
+                    id=run_group_data["id"],
+                    instance_id=run_group_data["instance_id"],
+                    options=run_group_data.get("options"),
+                    repetitions=run_group_data.get("repetitions"),
+                )
+                run_groups_list.append(run_group)
+
+            else:
+                error(
+                    f"Invalid run group format: [magenta]{run_group_str}[/magenta]. "
+                    "Expected [magenta]json[/magenta] object or array."
+                )
+
+        except (json.JSONDecodeError, KeyError, ValueError) as e:
+            error(f"Invalid run group format: [magenta]{run_group_str}[/magenta]. Error: {e}")
+
+    return run_groups_list
+
+
+def build_rules(rules: list[str]) -> list[EvaluationRule]:
+    """
+    Builds the rules list from the CLI option(s).
+
+    Parameters
+    ----------
+    rules : list[str]
+        List of rules provided via the CLI.
+
+    Returns
+    -------
+    list[EvaluationRule]
+        The built rules list.
+    """
+    import json
+
+    rules_list = []
+
+    for rule_str in rules:
+        try:
+            rule_data = json.loads(rule_str)
+
+            # Handle the case where the value is a list of rules.
+            if isinstance(rule_data, list):
+                for ix, item in enumerate(rule_data):
+                    validate_rule_data(item, rule_str, ix)
+                    rule = create_evaluation_rule(item)
+                    rules_list.append(rule)
+
+            # Handle the case where the value is a single rule.
+            elif isinstance(rule_data, dict):
+                validate_rule_data(rule_data, rule_str)
+                rule = create_evaluation_rule(rule_data)
+                rules_list.append(rule)
+
+            else:
+                error(
+                    f"Invalid rule format: [magenta]{rule_str}[/magenta]. "
+                    "Expected [magenta]json[/magenta] object or array."
+                )
+
+        except (json.JSONDecodeError, KeyError, ValueError) as e:
+            error(f"Invalid rule format: [magenta]{rule_str}[/magenta]. Error: {e}")
+
+    return rules_list
+
+
+def validate_rule_data(data: dict, rule_str: str, index: int | None = None) -> None:
+    """
+    Validates that rule data contains all required fields.
+
+    Parameters
+    ----------
+    data : dict
+        The rule data to validate.
+    rule_str : str
+        The original rule string for error messages.
+    index : int | None
+        The index if this is part of a list, for error messages.
+    """
+    required_fields = ["id", "statistics_path", "objective", "tolerance", "index"]
+    missing_fields = [field for field in required_fields if data.get(field) is None]
+
+    if missing_fields:
+        index_msg = f" at index [magenta]{index}[/magenta]" if index is not None else ""
+        error(
+            f"Invalid rule format{index_msg} in [magenta]{rule_str}[/magenta]. "
+            f"Missing required fields: [magenta]{', '.join(missing_fields)}[/magenta]."
+        )
+
+    # Validate tolerance structure
+    tolerance = data.get("tolerance")
+    if not isinstance(tolerance, dict) or tolerance.get("value") is None or tolerance.get("type") is None:
+        index_msg = f" at index [magenta]{index}[/magenta]" if index is not None else ""
+        error(
+            f"Invalid tolerance format{index_msg} in [magenta]{rule_str}[/magenta]. "
+            "Tolerance must have [magenta]value[/magenta] and [magenta]type[/magenta] fields."
+        )
+
+
+def create_evaluation_rule(data: dict) -> EvaluationRule:
+    """
+    Creates an EvaluationRule from validated data.
+
+    Parameters
+    ----------
+    data : dict
+        The validated rule data.
+
+    Returns
+    -------
+    EvaluationRule
+        The created evaluation rule.
+    """
+    tolerance_data = data["tolerance"]
+    tolerance = RuleTolerance(
+        value=float(tolerance_data["value"]),
+        type=RuleToleranceType(tolerance_data["type"]),
+    )
+
+    return EvaluationRule(
+        id=data["id"],
+        statistics_path=data["statistics_path"],
+        objective=RuleObjective(data["objective"]),
+        tolerance=tolerance,
+        index=int(data["index"]),
+    )

nextmv/cli/cloud/ensemble/delete.py

@@ -0,0 +1,63 @@
+"""
+This module defines the cloud ensemble delete command for the Nextmv CLI.
+"""
+
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.confirm import get_confirmation
+from nextmv.cli.message import info, success
+from nextmv.cli.options import AppIDOption, EnsembleDefinitionIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def delete(
+    app_id: AppIDOption,
+    ensemble_definition_id: EnsembleDefinitionIDOption,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Agree to deletion confirmation prompt. Useful for non-interactive sessions.",
+        ),
+    ] = False,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Deletes a Nextmv Cloud ensemble definition.
+
+    This action is permanent and cannot be undone. Use the --yes
+    flag to skip the confirmation prompt.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Delete the ensemble definition with the ID [magenta]prod-ensemble[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud ensemble delete --app-id hare-app --ensemble-definition-id prod-ensemble[/dim]
+
+    - Delete the ensemble definition without confirmation prompt.
+        $ [dim]nextmv cloud ensemble delete --app-id hare-app --ensemble-definition-id prod-ensemble --yes[/dim]
+    """
+
+    if not yes:
+        confirm = get_confirmation(
+            f"Are you sure you want to delete ensemble definition [magenta]{ensemble_definition_id}[/magenta] "
+            f"from application [magenta]{app_id}[/magenta]? This action cannot be undone.",
+        )
+
+        if not confirm:
+            info(f"Ensemble definition [magenta]{ensemble_definition_id}[/magenta] will not be deleted.")
+            return
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    cloud_app.delete_ensemble_definition(ensemble_definition_id=ensemble_definition_id)
+    success(
+        f"Ensemble definition [magenta]{ensemble_definition_id}[/magenta] deleted successfully "
+        f"from application [magenta]{app_id}[/magenta]."
+    )

nextmv/cli/cloud/ensemble/get.py

@@ -0,0 +1,65 @@
+"""
+This module defines the cloud ensemble get command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, EnsembleDefinitionIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def get(
+    app_id: AppIDOption,
+    ensemble_definition_id: EnsembleDefinitionIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the ensemble definition information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get a Nextmv Cloud ensemble definition.
+
+    This command is useful to get the attributes of an existing Nextmv Cloud
+    ensemble definition by its ID.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get the ensemble definition with the ID [magenta]prod-ensemble[/magenta] from
+      application [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud ensemble get --app-id hare-app \\
+        --ensemble-definition-id prod-ensemble[/dim]
+
+    - Get the ensemble definition with the ID [magenta]prod-ensemble[/magenta] and
+      save the information to an [magenta]ensemble.json[/magenta] file.
+        $ [dim]nextmv cloud ensemble get --app-id hare-app \\
+            --ensemble-definition-id prod-ensemble --output ensemble.json[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting ensemble definition...")
+    ensemble_definition = cloud_app.ensemble_definition(ensemble_definition_id=ensemble_definition_id)
+    ensemble_definition_dict = ensemble_definition.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(ensemble_definition_dict, f, indent=2)
+
+        success(msg=f"Ensemble definition information saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(ensemble_definition_dict)

nextmv/cli/cloud/ensemble/list.py

@@ -0,0 +1,63 @@
+"""
+This module defines the cloud ensemble list command for the Nextmv CLI.
+"""
+
+import json
+from typing import Annotated
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import in_progress, print_json, success
+from nextmv.cli.options import AppIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def list(
+    app_id: AppIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the list of ensemble definitions to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    List all Nextmv Cloud ensemble definitions for an application.
+
+    This command retrieves all ensemble definitions associated with the specified
+    application.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - List all ensemble definitions for application [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud ensemble list --app-id hare-app[/dim]
+
+    - List all ensemble definitions and save to a file.
+        $ [dim]nextmv cloud ensemble list --app-id hare-app --output ensembles.json[/dim]
+
+    - List all ensemble definitions using a specific profile.
+        $ [dim]nextmv cloud ensemble list --app-id hare-app --profile prod[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing ensemble definitions...")
+    ensembles = cloud_app.list_ensemble_definitions()
+    ensembles_dict = [ensemble.to_dict() for ensemble in ensembles]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(ensembles_dict, f, indent=2)
+
+        success(msg=f"Ensemble definitions list saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(ensembles_dict)