nextmv 1.0.0.dev5__py3-none-any.whl → 1.0.0.dev6__py3-none-any.whl

nextmv/cloud/application/_switchback.py

@@ -5,6 +5,7 @@ Application mixin for managing switchback tests.
 from datetime import datetime
 from typing import TYPE_CHECKING
 
+from nextmv.cloud.shadow import StopIntent
 from nextmv.cloud.switchback import SwitchbackTest, SwitchbackTestMetadata, TestComparisonSingle
 from nextmv.run import Run
 from nextmv.safe import safe_id
@@ -257,7 +258,7 @@ class ApplicationSwitchbackMixin:
             endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/start",
         )
 
-    def stop_switchback_test(self: "Application", switchback_test_id: str) -> None:
+    def stop_switchback_test(self: "Application", switchback_test_id: str, intent: StopIntent) -> None:
         """
         Stop a switchback test. The test should already have started before using
         this method.
@@ -267,15 +268,23 @@ class ApplicationSwitchbackMixin:
         switchback_test_id : str
             ID of the switchback test to stop.
 
+        intent : StopIntent
+            Intent for stopping the switchback test.
+
         Raises
         ------
         requests.HTTPError
             If the response status code is not 2xx.
         """
 
+        payload = {
+            "intent": intent.value,
+        }
+
         _ = self.client.request(
             method="PUT",
             endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/stop",
+            payload=payload,
         )
 
     def update_switchback_test(

nextmv/cloud/batch_experiment.py

@@ -30,7 +30,9 @@ class ExperimentStatus(str, Enum):
 
     You can import the `ExperimentStatus` class directly from `cloud`:
 
-    ```python from nextmv.cloud import ExperimentStatus ```
+    ```python
+    from nextmv.cloud import ExperimentStatus
+    ```
 
     This enum represents the comprehensive set of possible states for an
     experiment in Nextmv Cloud.

nextmv/cloud/client.py

@@ -303,7 +303,7 @@ class Client:
         if data is not None:
             kwargs["data"] = data
         if payload is not None:
-            if isinstance(payload, dict | list):
+            if isinstance(payload, (dict, list)):
                 data = deflated_serialize_json(payload, json_configurations=json_configurations)
                 kwargs["data"] = data
             else:

nextmv/cloud/community.py

@@ -0,0 +1,441 @@
+"""
+This module contains functionality for working with Nextmv community apps.
+
+Community apps are pre-built decision models. They are maintained in the
+following GitHub repository: https://github.com/nextmv-io/community-apps
+
+Classes
+-------
+CommunityApp
+    Representation of a Nextmv Cloud Community App.
+
+Functions
+---------
+list_community_apps
+    List the available Nextmv community apps.
+clone_community_app
+    Clone a community app locally.
+"""
+
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+from collections.abc import Callable
+from typing import Any
+
+import requests
+import rich
+import yaml
+from pydantic import AliasChoices, Field
+
+from nextmv.base_model import BaseModel
+from nextmv.cloud.client import Client
+from nextmv.logger import log
+
+# Helpful constants.
+LATEST_VERSION = "latest"
+
+
+class CommunityApp(BaseModel):
+    """
+    Information about a Nextmv community app.
+
+    You can import the `CommunityApp` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import CommunityApp
+    ```
+
+    Parameters
+    ----------
+    app_versions : list[str]
+        Available versions of the community app.
+    description : str
+        Description of the community app.
+    latest_app_version : str
+        The latest version of the community app.
+    latest_marketplace_version : str
+        The latest version of the community app in the Nextmv Marketplace.
+    marketplace_versions : list[str]
+        Available versions of the community app in the Nextmv Marketplace.
+    name : str
+        Name of the community app.
+    app_type : str
+        Type of the community app.
+    """
+
+    description: str
+    """Description of the community app."""
+    name: str
+    """Name of the community app."""
+    app_type: str = Field(
+        serialization_alias="type",
+        validation_alias=AliasChoices("type", "app_type"),
+    )
+    """Type of the community app."""
+
+    app_versions: list[str] | None = None
+    """Available versions of the community app."""
+    latest_app_version: str | None = None
+    """The latest version of the community app."""
+    latest_marketplace_version: str | None = None
+    """The latest version of the community app in the Nextmv Marketplace."""
+    marketplace_versions: list[str] | None = None
+    """Available versions of the community app in the Nextmv Marketplace."""
+
+    def has_version(self, version: str) -> bool:
+        """
+        Check if the community app has the specified version.
+
+        Parameters
+        ----------
+        version : str
+            The version to check.
+
+        Returns
+        -------
+        bool
+            True if the app has the specified version, False otherwise.
+        """
+
+        if version == LATEST_VERSION:
+            version = self.latest_app_version
+
+        if self.app_versions is not None and version in self.app_versions:
+            return True
+
+        return False
+
+
+def list_community_apps(client: Client) -> list[CommunityApp]:
+    """
+    List the available Nextmv community apps.
+
+    You can import the `list_community_apps` function directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import list_community_apps
+    ```
+
+    Parameters
+    ----------
+    manifest : dict[str, Any]
+        The community apps manifest.
+
+    Returns
+    -------
+    list[CommunityApp]
+        A list of available community apps.
+    """
+
+    manifest = _download_manifest(client)
+    dict_apps = manifest.get("apps", [])
+    apps = [CommunityApp.from_dict(app) for app in dict_apps]
+
+    return apps
+
+
+def clone_community_app(
+    client: Client,
+    app: str,
+    directory: str | None = None,
+    version: str | None = LATEST_VERSION,
+    verbose: bool = False,
+    rich_print: bool = False,
+) -> None:
+    """
+    Clone a community app locally.
+
+    By default, the `latest` version will be used. You can
+    specify a version with the `version` parameter, and customize the output
+    directory with the `directory` parameter. If you want to list the available
+    apps, use the `list_community_apps` function.
+
+    You can import the `clone_community_app` function directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import clone_community_app
+    ```
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    app : str
+        The name of the community app to clone.
+    directory : str | None, optional
+        The directory in which to clone the app. Default is the name of the app at current directory.
+    version : str | None, optional
+        The version of the community app to clone. Default is `latest`.
+    verbose : bool, optional
+        Whether to print verbose output.
+    rich_print : bool, optional
+        Whether to use rich printing for output messages.
+    """
+    comm_app = _find_app(client, app)
+
+    if version is not None and version == "":
+        raise ValueError("`version` cannot be an empty string.")
+
+    if not comm_app.has_version(version):
+        raise ValueError(f"Community app '{app}' does not have version '{version}'.")
+
+    original_version = version
+    if version == LATEST_VERSION:
+        version = comm_app.latest_app_version
+
+    # Clean and normalize directory path in an OS-independent way
+    if directory is not None and directory != "":
+        destination = os.path.normpath(directory)
+    else:
+        destination = app
+
+    full_destination = _get_valid_path(destination, os.stat)
+    os.makedirs(full_destination, exist_ok=True)
+
+    tarball = f"{app}_{version}.tar.gz"
+    s3_file_path = f"{app}/{version}/{tarball}"
+    downloaded_object = _download_object(
+        client=client,
+        file=s3_file_path,
+        path="community-apps",
+        output_dir=full_destination,
+        output_file=tarball,
+    )
+
+    # Extract the tarball to a temporary directory to handle nested structure
+    with tempfile.TemporaryDirectory() as temp_dir:
+        with tarfile.open(downloaded_object, "r:gz") as tar:
+            tar.extractall(path=temp_dir)
+
+        # Find the extracted directory (typically the app name)
+        extracted_items = os.listdir(temp_dir)
+        if len(extracted_items) == 1 and os.path.isdir(os.path.join(temp_dir, extracted_items[0])):
+            # Move contents from the extracted directory to full_destination
+            extracted_dir = os.path.join(temp_dir, extracted_items[0])
+            for item in os.listdir(extracted_dir):
+                shutil.move(os.path.join(extracted_dir, item), full_destination)
+        else:
+            # If structure is unexpected, move everything directly
+            for item in extracted_items:
+                shutil.move(os.path.join(temp_dir, item), full_destination)
+
+    # Remove the tarball after extraction
+    os.remove(downloaded_object)
+
+    if not verbose:
+        return
+
+    if rich_print:
+        rich.print(
+            f":white_check_mark: Successfully cloned the [magenta]{app}[/magenta] community app, "
+            f"using version [magenta]{original_version}[/magenta] in path: [magenta]{full_destination}[/magenta].",
+            file=sys.stderr,
+        )
+        return
+
+    log(
+        f"✅ Successfully cloned the {app} community app, using version {original_version} in path: {full_destination}."
+    )
+
+
+def _download_manifest(client: Client) -> dict[str, Any]:
+    """
+    Downloads and returns the community apps manifest.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+
+    Returns
+    -------
+    dict[str, Any]
+        The community apps manifest as a dictionary.
+
+    Raises
+    requests.HTTPError
+        If the response status code is not 2xx.
+    """
+
+    response = _download_file(client=client, directory="community-apps", file="manifest.yml")
+    manifest = yaml.safe_load(response.text)
+
+    return manifest
+
+
+def _download_file(
+    client: Client,
+    directory: str,
+    file: str,
+) -> requests.Response:
+    """
+    Gets a file from an internal bucket and return it.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    directory : str
+        The directory in the bucket where the file is located.
+    file : str
+        The name of the file to download.
+
+    Returns
+    -------
+    requests.Response
+        The response object containing the file data.
+
+    Raises
+    requests.HTTPError
+        If the response status code is not 2xx.
+    """
+
+    # Request the download URL for the file.
+    response = client.request(
+        method="GET",
+        endpoint="v0/internal/tools",
+        headers=client.headers | {"request-source": "cli"},  # Pass `client.headers` to preserve auth.
+        query_params={"file": f"{directory}/{file}"},
+    )
+
+    # Use the URL obtained to download the file.
+    body = response.json()
+    download_response = client.request(
+        method="GET",
+        endpoint=body.get("url"),
+        headers={"Content-Type": "application/json"},
+    )
+
+    return download_response
+
+
+def _download_object(client: Client, file: str, path: str, output_dir: str, output_file: str) -> str:
+    """
+    Downloads an object from the internal bucket and saves it to the specified
+    output directory.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    file : str
+        The name of the file to download.
+    path : str
+        The directory in the bucket where the file is located.
+    output_dir : str
+        The local directory where the file will be saved.
+    output_file : str
+        The name of the output file.
+
+    Returns
+    -------
+    str
+        The path to the downloaded file.
+    """
+
+    response = _download_file(client=client, directory=path, file=file)
+    file_name = os.path.join(output_dir, output_file)
+
+    with open(file_name, "wb") as f:
+        f.write(response.content)
+
+    return file_name
+
+
+def _get_valid_path(path: str, stat_fn: Callable[[str], os.stat_result], ending: str = "") -> str:
+    """
+    Validates and returns a non-existing path. If the path exists,
+    it will append a number to the path and return it. If the path does not
+    exist, it will return the path as is.
+
+    The ending parameter is used to check if the path ends with a specific
+    string. This is useful to specify if it is a file (like foo.json, in which
+    case the next iteration is foo-1.json) or a directory (like foo, in which
+    case the next iteration is foo-1).
+
+    Parameters
+    ----------
+    path : str
+        The initial path to validate.
+    stat_fn : Callable[[str], os.stat_result]
+        A function that takes a path and returns its stat result.
+    ending : str, optional
+        The expected ending of the path (e.g., file extension), by default "".
+
+    Returns
+    -------
+    str
+        A valid, non-existing path.
+
+    Raises
+    ------
+    Exception
+        If an unexpected error occurs during path validation
+    """
+    base_name = os.path.basename(path)
+    name_without_ending = base_name.removesuffix(ending) if ending else base_name
+
+    while True:
+        try:
+            stat_fn(path)
+            # If we get here, the path exists
+            # Get folder/file name number, increase it and create new path
+            name = os.path.basename(path)
+
+            # Get folder/file name number
+            parts = name.split("-")
+            last = parts[-1].removesuffix(ending) if ending else parts[-1]
+
+            # Save last folder name index to be changed
+            i = path.rfind(name)
+
+            try:
+                num = int(last)
+                # Increase number and create new path
+                if ending:
+                    temp_path = path[:i] + f"{name_without_ending}-{num + 1}{ending}"
+                else:
+                    temp_path = path[:i] + f"{base_name}-{num + 1}"
+                path = temp_path
+            except ValueError:
+                # If there is no number, add it
+                if ending:
+                    temp_path = path[:i] + f"{name_without_ending}-1{ending}"
+                else:
+                    temp_path = path[:i] + f"{name}-1"
+                path = temp_path
+
+        except FileNotFoundError:
+            # Path doesn't exist, we can use it
+            return path
+        except Exception as e:
+            # Re-raise unexpected errors
+            raise RuntimeError(f"An unexpected error occurred while validating the path: {path} ") from e
+
+
+def _find_app(client: Client, app: str) -> CommunityApp | None:
+    """
+    Finds and returns a community app from the manifest by its name.
+
+    Parameters
+    ----------
+    client : Client
+        The Nextmv Cloud client to use for the request.
+    app : str
+        The name of the community app to find.
+
+    Returns
+    -------
+    CommunityApp | None
+        The community app if found, otherwise None.
+    """
+
+    comm_apps = list_community_apps(client)
+    for comm_app in comm_apps:
+        if comm_app.name == app:
+            return comm_app
+
+    raise ValueError(f"Community app '{app}' not found.")

nextmv/cloud/shadow.py

@@ -19,6 +19,7 @@ ShadowTest
 """
 
 from datetime import datetime
+from enum import Enum
 from typing import Any
 
 from pydantic import AliasChoices, Field
@@ -227,3 +228,27 @@ class ShadowTest(BaseModel):
     """Grouped distributional summaries of the shadow test."""
     runs: list[Run] | None = None
     """List of runs in the shadow test."""
+
+
+class StopIntent(str, Enum):
+    """
+    Intent for stopping a shadow test.
+
+    You can import the `StopIntent` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import StopIntent
+    ```
+
+    Attributes
+    ----------
+    complete : str
+        The test is marked as complete.
+    cancel : str
+        The test is canceled.
+    """
+
+    complete = "complete"
+    """The test is marked as complete."""
+    cancel = "cancel"
+    """The test is canceled."""

nextmv/default_app/main.py

@@ -26,10 +26,12 @@ assets = create_visuals(name, input.data["radius"], input.data["distance"])
 output = nextmv.Output(
     options=options,
     solution={"message": message},
-    metrics={
-        "value": 1.23,
-        "custom": {"message": message},
-    },
+    statistics=nextmv.Statistics(
+        result=nextmv.ResultStatistics(
+            value=1.23,
+            custom={"message": message},
+        ),
+    ),
     assets=assets,
 )
 nextmv.write(output)

nextmv/local/executor.py

@@ -22,8 +22,6 @@ process_run_information
     Function to update run metadata including duration and status.
 process_run_logs
     Function to process and save run logs.
-process_run_metrics
-    Function to process and save run metrics.
 process_run_statistics
     Function to process and save run statistics.
 process_run_assets
@@ -59,16 +57,7 @@ from nextmv.local.local import (
 )
 from nextmv.local.plotly_handler import handle_plotly_visual
 from nextmv.manifest import Manifest, ManifestType
-from nextmv.output import (
-    ASSETS_KEY,
-    METRICS_KEY,
-    OUTPUTS_KEY,
-    SOLUTIONS_KEY,
-    STATISTICS_KEY,
-    Asset,
-    OutputFormat,
-    VisualSchema,
-)
+from nextmv.output import ASSETS_KEY, OUTPUTS_KEY, SOLUTIONS_KEY, STATISTICS_KEY, Asset, OutputFormat, VisualSchema
 from nextmv.status import StatusV2
 
 
@@ -316,7 +305,7 @@ def process_run_output(
 ) -> None:
     """
     Processes the result of the subprocess run. This function is in charge of
-    handling the run results, including solutions, statistics, metrics, logs, assets,
+    handling the run results, including solutions, statistics, logs, assets,
     and visuals.
 
     Parameters
@@ -358,13 +347,6 @@ def process_run_output(
         result=result,
         stdout_output=stdout_output,
     )
-    process_run_metrics(
-        temp_run_outputs_dir=temp_run_outputs_dir,
-        outputs_dir=outputs_dir,
-        stdout_output=stdout_output,
-        temp_src=temp_src,
-        manifest=manifest,
-    )
     process_run_statistics(
         temp_run_outputs_dir=temp_run_outputs_dir,
         outputs_dir=outputs_dir,
@@ -517,65 +499,6 @@ def process_run_logs(
 
         f.write(std_err)
 
-def process_run_metrics(
-    temp_run_outputs_dir: str,
-    outputs_dir: str,
-    stdout_output: str | dict[str, Any],
-    temp_src: str,
-    manifest: Manifest,
-) -> None:
-    """
-    Processes the metrics of the run. Checks for an outputs/metrics folder
-    or custom metrics file location from manifest. If found, copies to run
-    directory. Otherwise, attempts to extract metrics from stdout.
-
-    Parameters
-    ----------
-    temp_run_outputs_dir : str
-        The path to the temporary outputs directory.
-    outputs_dir : str
-        The path to the outputs directory in the run directory.
-    stdout_output : Union[str, dict[str, Any]]
-        The stdout output of the run, either as raw string or parsed dictionary.
-    temp_src : str
-        The path to the temporary source directory.
-    manifest : Manifest
-        The application manifest containing configuration and custom paths.
-    """
-
-    metrics_dst = os.path.join(outputs_dir, METRICS_KEY)
-    os.makedirs(metrics_dst, exist_ok=True)
-    metrics_file = f"{METRICS_KEY}.json"
-
-    # Check for custom location in manifest and override metrics_src if needed.
-    if (
-        manifest.configuration is not None
-        and manifest.configuration.content is not None
-        and manifest.configuration.content.format == OutputFormat.MULTI_FILE
-        and manifest.configuration.content.multi_file is not None
-    ):
-        metrics_src_file = os.path.join(temp_src, manifest.configuration.content.multi_file.output.metrics)
-
-        # If the custom metrics file exists, copy it to the metrics destination
-        if os.path.exists(metrics_src_file) and os.path.isfile(metrics_src_file):
-            metrics_dst_file = os.path.join(metrics_dst, metrics_file)
-            shutil.copy2(metrics_src_file, metrics_dst_file)
-            return
-
-    metrics_src = os.path.join(temp_run_outputs_dir, METRICS_KEY)
-    if os.path.exists(metrics_src) and os.path.isdir(metrics_src):
-        shutil.copytree(metrics_src, metrics_dst, dirs_exist_ok=True)
-        return
-
-    if not isinstance(stdout_output, dict):
-        return
-
-    if METRICS_KEY not in stdout_output:
-        return
-
-    with open(os.path.join(metrics_dst, metrics_file), "w") as f:
-        metrics = {METRICS_KEY: stdout_output[METRICS_KEY]}
-        json.dump(metrics, f, indent=2)
 
 def process_run_statistics(
     temp_run_outputs_dir: str,
@@ -585,9 +508,6 @@ def process_run_statistics(
     manifest: Manifest,
 ) -> None:
     """
-    !!! warning
-    `process_run_statistics` is deprecated, use `process_run_metrics` instead.
-
     Processes the statistics of the run. Checks for an outputs/statistics folder
     or custom statistics file location from manifest. If found, copies to run
     directory. Otherwise, attempts to extract statistics from stdout.
@@ -928,7 +848,7 @@ def _copy_new_or_modified_files(  # noqa: C901
     This function identifies files that are either new (not present in the original
     source) or have been modified (different content, checksum, or modification time)
     compared to the original source. It excludes files that exist in specified
-    exclusion directories to avoid copying input data, statistics, metrics, or assets as
+    exclusion directories to avoid copying input data, statistics, or assets as
     solution outputs.
 
     Parameters

nextmv/local/geojson_handler.py

@@ -111,7 +111,7 @@ def extract_coordinates(coords, all_coords) -> None:
       like Polygons and MultiPolygons
     """
     if isinstance(coords, list):
-        if len(coords) == 2 and isinstance(coords[0], int | float) and isinstance(coords[1], int | float):
+        if len(coords) == 2 and isinstance(coords[0], (int, float)) and isinstance(coords[1], (int, float)):
             # This is a coordinate pair [lon, lat]
             all_coords.append(coords)
         else: