nextmv 0.40.0__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cli/cloud/batch/list.py

@@ -0,0 +1,63 @@
+"""
+This module defines the cloud batch 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 batch experiments to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    List all Nextmv Cloud batch experiments for an application.
+
+    This command retrieves all batch experiments associated with the specified
+    application.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - List all batch experiments for application [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud batch list --app-id hare-app[/dim]
+
+    - List all batch experiments and save to a file.
+        $ [dim]nextmv cloud batch list --app-id hare-app --output experiments.json[/dim]
+
+    - List all batch experiments using a specific profile.
+        $ [dim]nextmv cloud batch list --app-id hare-app --profile prod[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Listing batch experiments...")
+    batch_experiments = cloud_app.list_batch_experiments()
+    batch_experiments_dict = [exp.to_dict() for exp in batch_experiments]
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(batch_experiments_dict, f, indent=2)
+
+        success(msg=f"Batch experiments list saved to [magenta]{output}[/magenta].")
+
+        return
+
+    print_json(batch_experiments_dict)

nextmv/cli/cloud/batch/metadata.py

@@ -0,0 +1,66 @@
+"""
+This module defines the cloud batch metadata 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, BatchExperimentIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def metadata(
+    app_id: AppIDOption,
+    batch_experiment_id: BatchExperimentIDOption,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the batch experiment metadata to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Get metadata for a Nextmv Cloud batch experiment.
+
+    This command retrieves metadata for a specific batch experiment, including
+    status, creation date, and other high-level information without the full
+    run details.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Get metadata for batch experiment [magenta]bunny-warren-optimization[/magenta] from application
+      [magenta]hare-app[/magenta].
+        $ [dim]nextmv cloud batch metadata --app-id hare-app --batch-experiment-id bunny-warren-optimization[/dim]
+
+    - Get metadata and save to a file.
+        $ [dim]nextmv cloud batch metadata --app-id hare-app --batch-experiment-id lettuce-delivery \\
+            --output metadata.json[/dim]
+
+    - Get metadata using a specific profile.
+        $ [dim]nextmv cloud batch metadata --app-id hare-app --batch-experiment-id hop-schedule --profile prod[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    in_progress(msg="Getting batch experiment metadata...")
+    batch_metadata = cloud_app.batch_experiment_metadata(batch_id=batch_experiment_id)
+    batch_metadata_dict = batch_metadata.to_dict()
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(batch_metadata_dict, f, indent=2)
+
+        success(msg=f"Batch experiment metadata saved to [magenta]{output}[/magenta].")
+        return
+
+    print_json(batch_metadata_dict)

nextmv/cli/cloud/batch/update.py

@@ -0,0 +1,95 @@
+"""
+This module defines the cloud batch update 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, BatchExperimentIDOption, ProfileOption
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def update(
+    app_id: AppIDOption,
+    batch_experiment_id: BatchExperimentIDOption,
+    description: Annotated[
+        str | None,
+        typer.Option(
+            "--description",
+            "-d",
+            help="Updated description of the batch experiment.",
+            metavar="DESCRIPTION",
+        ),
+    ] = None,
+    name: Annotated[
+        str | None,
+        typer.Option(
+            "--name",
+            "-n",
+            help="Updated name of the batch experiment.",
+            metavar="NAME",
+        ),
+    ] = None,
+    output: Annotated[
+        str | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Saves the updated batch experiment information to this location.",
+            metavar="OUTPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Update a Nextmv Cloud batch experiment.
+
+    Update the name and/or description of a batch experiment. Any fields not
+    specified will remain unchanged.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Update the name of a batch experiment.
+        $ [dim]nextmv cloud batch update --app-id hare-app --batch-experiment-id carrot-feast \\
+            --name "Spring Carrot Harvest"[/dim]
+
+    - Update the description of a batch experiment.
+        $ [dim]nextmv cloud batch update --app-id hare-app --batch-experiment-id bunny-hop-routes \\
+            --description "Optimizing hop paths through the meadow"[/dim]
+
+    - Update both name and description and save the result.
+        $ [dim]nextmv cloud batch update --app-id hare-app --batch-experiment-id lettuce-delivery \\
+            --name "Warren Lettuce Express" --description "Fast lettuce delivery to all burrows" \\
+            --output updated-batch.json[/dim]
+    """
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+
+    in_progress(msg="Updating batch experiment...")
+    batch_experiment = cloud_app.update_batch_experiment(
+        batch_experiment_id=batch_experiment_id,
+        name=name,
+        description=description,
+    )
+
+    batch_experiment_dict = batch_experiment.to_dict()
+    success(
+        f"Batch experiment [magenta]{batch_experiment_id}[/magenta] updated successfully "
+        f"in application [magenta]{app_id}[/magenta]."
+    )
+
+    if output is not None and output != "":
+        with open(output, "w") as f:
+            json.dump(batch_experiment_dict, f, indent=2)
+
+        success(msg=f"Updated batch experiment information saved to [magenta]{output}[/magenta].")
+        return
+
+    print_json(batch_experiment_dict)

nextmv/cli/cloud/data/__init__.py

@@ -0,0 +1,26 @@
+"""
+This module defines the cloud data command tree for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.cloud.data.upload import app as upload_app
+
+# Set up subcommand application.
+app = typer.Typer()
+app.add_typer(upload_app)
+
+
+@app.callback()
+def callback() -> None:
+    """
+    Upload data for Nextmv Cloud application components.
+
+    When data is too large (exceeds [magenta]5 MiB[/magenta]), or you are
+    working with the [magenta]multi-file[/magenta] content format, you can use
+    this command to upload information to Nextmv Cloud. Requires a pre-signed
+    upload URL, which can be obtained using the [code]nextmv cloud upload
+    create[/code] command. Use the [magenta].upload_url[/magenta] field from the
+    command output.
+    """
+    pass

nextmv/cli/cloud/data/upload.py

@@ -0,0 +1,162 @@
+"""
+This module defines the cloud data upload command for the Nextmv CLI.
+"""
+
+import json
+import sys
+import tarfile
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from nextmv.cli.configuration.config import build_app
+from nextmv.cli.message import error, in_progress, success
+from nextmv.cli.options import AppIDOption, ProfileOption
+from nextmv.cloud.application import Application
+
+# Set up subcommand application.
+app = typer.Typer()
+
+
+@app.command()
+def upload(
+    app_id: AppIDOption,
+    upload_url: Annotated[
+        str,
+        typer.Option(
+            "--upload-url",
+            "-u",
+            help="Pre-signed URL for uploading the data.",
+            metavar="UPLOAD_URL",
+        ),
+    ],
+    input: Annotated[
+        str | None,
+        typer.Option(
+            "--input",
+            "-i",
+            help="The input path to use. File or directory depending on content format. "
+            "Uses [magenta]stdin[/magenta] if not defined. "
+            "Can be a [magenta].tar.gz[/magenta] file for multi-file content format.",
+            metavar="INPUT_PATH",
+        ),
+    ] = None,
+    profile: ProfileOption = None,
+) -> None:
+    """
+    Upload data for Nextmv Cloud application components.
+
+    When data is too large, or is not in a text-based content format, you can
+    use this command to upload information for a Nextmv Cloud application. Data
+    is used for starting new runs, tracking runs, performing experiments, and
+    more.
+
+    The --upload-url flag is required to specify the pre-signed
+    upload URL. It can be obtained using the [code]nextmv cloud upload
+    create[/code] command. Use the [magenta].upload_url[/magenta] field from
+    the command output.
+
+    The data input should be given through [magenta]stdin[/magenta] or the
+    --input flag. When using the --input flag, the value can be one of the
+    following:
+
+    - [yellow]<FILE_PATH>[/yellow]: path to a [magenta]file[/magenta] containing
+      the data. Use with the [magenta]json[/magenta], and
+      [magenta]text[/magenta] content formats.
+    - [yellow]<DIR_PATH>[/yellow]: path to a [magenta]directory[/magenta]
+      containing data files. Use with the [magenta]multi-file[/magenta]
+      content format.
+    - [yellow]<.tar.gz PATH>[/yellow]: path to a [magenta].tar.gz[/magenta] file
+      containing tarred data files. Use with the [magenta]multi-file[/magenta]
+      content format.
+
+    [bold][underline]Examples[/underline][/bold]
+
+    - Upload data from [magenta]stdin[/magenta] for application
+      [magenta]hare-app[/magenta].
+        $ [dim]echo '{"key": "value"}' | nextmv cloud data upload --app-id hare-app --upload-url <URL>[/dim]
+
+    - Upload data from a [magenta]JSON[/magenta] file.
+        $ [dim]nextmv cloud data upload --app-id hare-app --upload-url <URL> --input data.json[/dim]
+
+    - Upload data from a [magenta]text[/magenta] file.
+        $ [dim]nextmv cloud data upload --app-id hare-app --upload-url <URL> --input data.txt[/dim]
+
+    - Upload [magenta]multi-file[/magenta] data from a directory.
+        $ [dim]nextmv cloud data upload --app-id hare-app --upload-url <URL> --input ./data_directory[/dim]
+
+    - Upload [magenta]multi-file[/magenta] data from a
+      [magenta].tar.gz[/magenta] file.
+        $ [dim]nextmv cloud data upload --app-id hare-app --upload-url <URL> --input data.tar.gz[/dim]
+
+    - Upload data using a specific profile.
+        $ [dim]nextmv cloud data upload --app-id hare-app --upload-url <URL> --input data.json \\
+            --profile production[/dim]
+    """
+
+    # Validate that input is provided.
+    stdin = sys.stdin.read().strip() if sys.stdin.isatty() is False else None
+    if stdin is None and (input is None or input == ""):
+        error("Input data must be provided via the --input flag or [magenta]stdin[/magenta].")
+
+    cloud_app = build_app(app_id=app_id, profile=profile)
+    data_kwarg = resolve_data_kwarg(
+        stdin=stdin,
+        input=input,
+        cloud_app=cloud_app,
+    )
+
+    in_progress(msg="Uploading data...")
+    cloud_app.upload_data(upload_url=upload_url, **data_kwarg)
+    success(msg="Data uploaded successfully.")
+
+
+def resolve_data_kwarg(stdin: str | None, input: str | None, cloud_app: Application) -> dict[str, Any]:
+    """
+    Gets the keyword argument related to the data that is needed for the
+    upload. It handles stdin, file, and directory inputs.
+
+    Parameters
+    ----------
+    stdin : str | None
+        The stdin input data, if provided.
+    input : str | None
+        The input path, if provided.
+    cloud_app : Application
+        The Nextmv Cloud application instance.
+
+    Returns
+    -------
+    dict[str, Any]
+        The keyword argument with the resolved data.
+    """
+
+    if stdin is not None:
+        # Handle the case where stdin is provided as JSON for a JSON app.
+        try:
+            input_data = json.loads(stdin)
+        except json.JSONDecodeError:
+            input_data = stdin
+
+        return {"data": input_data}
+
+    input_path = Path(input)
+
+    # If the input is a file, we need to determine if it is a tar file or a
+    # regular file. If it is a regular file, we need to read its content.
+    if input_path.is_file():
+        if tarfile.is_tarfile(input_path):
+            return {"tar_file": str(input_path)}
+
+        input_data = input_path.read_text()
+
+        return {"data": input_data}
+
+    # If the input is a directory, we need to tar the contents.
+    if input_path.is_dir():
+        tar_path = cloud_app._package_inputs(dir_path=str(input_path))
+
+        return {"tar_file": tar_path}
+
+    error(f"Input path [magenta]{input}[/magenta] does not exist.")

nextmv/cli/cloud/ensemble/__init__.py

@@ -0,0 +1,33 @@
+"""
+This module defines the cloud ensemble command tree for the Nextmv CLI.
+"""
+
+import typer
+
+from nextmv.cli.cloud.ensemble.create import app as create_app
+from nextmv.cli.cloud.ensemble.delete import app as delete_app
+from nextmv.cli.cloud.ensemble.get import app as get_app
+from nextmv.cli.cloud.ensemble.list import app as list_app
+from nextmv.cli.cloud.ensemble.update import app as update_app
+
+# Set up subcommand application.
+app = typer.Typer()
+app.add_typer(create_app)
+app.add_typer(delete_app)
+app.add_typer(get_app)
+app.add_typer(list_app)
+app.add_typer(update_app)
+
+
+@app.callback()
+def callback() -> None:
+    """
+    Create and manage Nextmv Cloud ensemble definitions.
+
+    An ensemble definition defines how to coordinate and execute multiple child
+    runs for an application, and how to determine the optimal result from those
+    runs. You can configure run groups to specify which instances to run on and
+    with what options, as well as evaluation rules to determine the best result
+    based on specified metrics.
+    """
+    pass