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

nextmv/cloud/application/_switchback.py

@@ -5,7 +5,6 @@ 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
@@ -258,7 +257,7 @@ class ApplicationSwitchbackMixin:
             endpoint=f"{self.experiments_endpoint}/switchback/{switchback_test_id}/start",
         )
 
-    def stop_switchback_test(self: "Application", switchback_test_id: str, intent: StopIntent) -> None:
+    def stop_switchback_test(self: "Application", switchback_test_id: str) -> None:
         """
         Stop a switchback test. The test should already have started before using
         this method.
@@ -268,23 +267,15 @@ 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,9 +30,7 @@ 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/shadow.py

@@ -19,7 +19,6 @@ ShadowTest
 """
 
 from datetime import datetime
-from enum import Enum
 from typing import Any
 
 from pydantic import AliasChoices, Field
@@ -228,27 +227,3 @@ 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,12 +26,10 @@ assets = create_visuals(name, input.data["radius"], input.data["distance"])
 output = nextmv.Output(
     options=options,
     solution={"message": message},
-    statistics=nextmv.Statistics(
-        result=nextmv.ResultStatistics(
-            value=1.23,
-            custom={"message": message},
-        ),
-    ),
+    metrics={
+        "value": 1.23,
+        "custom": {"message": message},
+    },
     assets=assets,
 )
 nextmv.write(output)

nextmv/local/executor.py

@@ -22,6 +22,8 @@ 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
@@ -57,7 +59,16 @@ 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, OUTPUTS_KEY, SOLUTIONS_KEY, STATISTICS_KEY, Asset, OutputFormat, VisualSchema
+from nextmv.output import (
+    ASSETS_KEY,
+    METRICS_KEY,
+    OUTPUTS_KEY,
+    SOLUTIONS_KEY,
+    STATISTICS_KEY,
+    Asset,
+    OutputFormat,
+    VisualSchema,
+)
 from nextmv.status import StatusV2
 
 
@@ -305,7 +316,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, logs, assets,
+    handling the run results, including solutions, statistics, metrics, logs, assets,
     and visuals.
 
     Parameters
@@ -347,6 +358,13 @@ 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,
@@ -499,6 +517,65 @@ 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,
@@ -508,6 +585,9 @@ 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.
@@ -848,7 +928,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, or assets as
+    exclusion directories to avoid copying input data, statistics, metrics, 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:

nextmv/manifest.py

@@ -829,7 +829,9 @@ class ManifestContentMultiFileOutput(BaseModel):
     Parameters
     ----------
     statistics : Optional[str], default=""
-        The path to the statistics file.
+        Deprecated: Use `metrics` instead. The path to the statistics file.
+    metrics : Optional[str], default=""
+        The path to the metrics file.
     assets : Optional[str], default=""
         The path to the assets file.
     solutions : Optional[str], default=""
@@ -839,16 +841,18 @@ class ManifestContentMultiFileOutput(BaseModel):
     --------
     >>> from nextmv import ManifestContentMultiFileOutput
     >>> output_config = ManifestContentMultiFileOutput(
-    ...     statistics="my-outputs/statistics.json",
+    ...     metrics="my-outputs/metrics.json",
     ...     assets="my-outputs/assets.json",
     ...     solutions="my-outputs/solutions/"
     ... )
-    >>> output_config.statistics
-    'my-outputs/statistics.json'
+    >>> output_config.metrics
+    'my-outputs/metrics.json'
     """
 
     statistics: str | None = ""
-    """The path to the statistics file."""
+    """Deprecated: Use `metrics` instead. The path to the statistics file."""
+    metrics: str | None = ""
+    """The path to the metrics file."""
     assets: str | None = ""
     """The path to the assets file."""
     solutions: str | None = ""
@@ -878,7 +882,7 @@ class ManifestContentMultiFile(BaseModel):
     >>> multi_file_config = ManifestContentMultiFile(
     ...     input=ManifestContentMultiFileInput(path="data/input/"),
     ...     output=ManifestContentMultiFileOutput(
-    ...         statistics="my-outputs/statistics.json",
+    ...         metrics="my-outputs/metrics.json",
     ...         assets="my-outputs/assets.json",
     ...         solutions="my-outputs/solutions/"
     ...     )
@@ -919,7 +923,7 @@ class ManifestContent(BaseModel):
     ...     multi_file=ManifestContentMultiFile(
     ...         input=ManifestContentMultiFileInput(path="data/input/"),
     ...         output=ManifestContentMultiFileOutput(
-    ...             statistics="my-outputs/statistics.json",
+    ...             metrics="my-outputs/metrics.json",
     ...             assets="my-outputs/assets.json",
     ...             solutions="my-outputs/solutions/"
     ...         )

nextmv/model.py

@@ -195,7 +195,7 @@ class Model:
     ...         return nextmv.Output(
     ...             options=input.options,
     ...             solution=nextroute_output.solutions[0].to_dict(),
-    ...             statistics=nextroute_output.statistics.to_dict(),
+    ...             metrics=nextroute_output.metrics.to_dict(),
     ...         )
     """
 
@@ -234,7 +234,7 @@ class Model:
         ...     return Output(
         ...         options=input.options,
         ...         solution=result,
-        ...         statistics={"processing_time": 0.5}
+        ...         metrics={"processing_time": 0.5}
         ...     )
         """
 

nextmv/options.py

@@ -695,7 +695,7 @@ class Options:
             help=argparse.SUPPRESS,
             default="1",
         )
-        args, _ = parser.parse_known_args()
+        args = parser.parse_args()
 
         for arg in vars(args):
             if arg == "fff" or arg == "f":

nextmv/output.py

@@ -8,9 +8,9 @@ destinations.
 Classes
 -------
 RunStatistics
-    Statistics about a general run.
+    Deprecated: Statistics about a general run.
 ResultStatistics
-    Statistics about a specific result.
+    Deprecated: Statistics about a specific result.
 DataPoint
     A data point representing a 2D coordinate.
 Series
@@ -18,7 +18,10 @@ Series
 SeriesData
     Data container for multiple series of data points.
 Statistics
-    Complete statistics container for a solution, including run metrics and result data.
+    Deprecated: Use metrics instead. Complete statistics container for a
+    solution, including run metrics and result data.
+Metrics
+    Metrics container for a solution.
 OutputFormat
     Enumeration of supported output formats.
 SolutionFile
@@ -46,7 +49,9 @@ Attributes
 ASSETS_KEY : str
     Assets key constant used for identifying assets in the run output.
 STATISTICS_KEY : str
-    Statistics key constant used for identifying statistics in the run output.
+    Deprecated: Use METRICS_KEY instead. Statistics key constant used for identifying statistics in the run output.
+METRICS_KEY : str
+    Metrics key constant used for identifying metrics in the run output.
 SOLUTIONS_KEY : str
     Solutions key constant used for identifying solutions in the run output.
 OUTPUTS_KEY : str
@@ -75,7 +80,11 @@ Assets key constant used for identifying assets in the run output.
 """
 STATISTICS_KEY = "statistics"
 """
-Statistics key constant used for identifying statistics in the run output.
+Deprecated: Use METRICS_KEY instead. Statistics key constant used for identifying statistics in the run output.
+"""
+METRICS_KEY = "metrics"
+"""
+Metrics key constant used for identifying metrics in the run output.
 """
 SOLUTIONS_KEY = "solutions"
 """
@@ -89,7 +98,7 @@ Outputs key constant used for identifying outputs in the run output.
 
 class RunStatistics(BaseModel):
     """
-    Statistics about a general run.
+    Deprecated: Statistics about a general run.
 
     You can import the `RunStatistics` class directly from `nextmv`:
 
@@ -129,7 +138,7 @@ class RunStatistics(BaseModel):
 
 class ResultStatistics(BaseModel):
     """
-    Statistics about a specific result.
+    Deprecated: Statistics about a specific result.
 
     You can import the `ResultStatistics` class directly from `nextmv`:
 
@@ -169,7 +178,7 @@ class ResultStatistics(BaseModel):
 
 class DataPoint(BaseModel):
     """
-    A data point representing a 2D coordinate.
+    Deprecated: A data point representing a 2D coordinate.
 
     You can import the `DataPoint` class directly from `nextmv`:
 
@@ -202,7 +211,7 @@ class DataPoint(BaseModel):
 
 class Series(BaseModel):
     """
-    A series of data points for visualization or analysis.
+    Deprecated: A series of data points for visualization or analysis.
 
     You can import the `Series` class directly from `nextmv`:
 
@@ -236,7 +245,7 @@ class Series(BaseModel):
 
 class SeriesData(BaseModel):
     """
-    Data container for multiple series of data points.
+    Deprecated: Data container for multiple series of data points.
 
     You can import the `SeriesData` class directly from `nextmv`:
 
@@ -271,6 +280,9 @@ class SeriesData(BaseModel):
 
 class Statistics(BaseModel):
     """
+    !!! warning
+    `Statistics` is deprecated, use `Metrics` instead.
+
     Complete statistics container for a solution, including run metrics and
     result data.
 
@@ -877,7 +889,9 @@ class Output:
         The solution to the decision problem. The type must match the
         `output_format`. Default is None.
     statistics : Optional[Union[Statistics, dict[str, Any]]], optional
-        Statistics of the solution. Default is None.
+        Deprecated: Use Metrics instead. Statistics of the solution. Default is None.
+    metrics : Optional[dict[str, Any]], optional
+        Metrics of the solution. Default is None.
     csv_configurations : Optional[dict[str, Any]], optional
         Configuration for writing CSV files. Default is None.
     json_configurations : Optional[dict[str, Any]], optional
@@ -916,17 +930,16 @@ class Output:
     Examples
     --------
     >>> from nextmv.output import Output, OutputFormat, Statistics, RunStatistics
-    >>> run_stats = RunStatistics(duration=30.0, iterations=100)
-    >>> stats = Statistics(run=run_stats)
+    >>> metrics = {"duration": 30.0, "iterations": 100}
     >>> solution = {"routes": [{"vehicle": 1, "stops": [1, 2, 3]}, {"vehicle": 2, "stops": [4, 5]}]}
     >>> output = Output(
     ...     output_format=OutputFormat.JSON,
     ...     solution=solution,
-    ...     statistics=stats,
+    ...     metrics=metrics,
     ...     json_configurations={"indent": 4}
     ... )
     >>> output_dict = output.to_dict()
-    >>> "solution" in output_dict and "statistics" in output_dict
+    >>> "solution" in output_dict and "metrics" in output_dict
     True
     """
 
@@ -969,11 +982,16 @@ class Output:
     """
     statistics: Statistics | dict[str, Any] | None = None
     """
+    Deprecated: Use Metrics instead.
     Statistics of the solution. These statistics can be of type `Statistics` or a
     simple dictionary. If the statistics are of type `Statistics`, they will be
     serialized to a dictionary using the `to_dict` method. If they are a
-    dictionary, they will be used as is. If the statistics are not provided, an
-    empty dictionary will be used.
+    dictionary, they will be used as is.
+    """
+    metrics: dict[str, Any] | None = None
+    """
+    Metrics of the solution. These metrics should be provided as a simple or
+    nested dictionary.
     """
     csv_configurations: dict[str, Any] | None = None
     """
@@ -1088,7 +1106,7 @@ class Output:
         # Statistics need to end up as a dict, so we achieve that based on the
         # type of statistics that were used to create the class.
         if self.statistics is None:
-            statistics = {}
+            statistics = None
         elif isinstance(self.statistics, Statistics):
             statistics = self.statistics.to_dict()
         elif isinstance(self.statistics, dict):
@@ -1098,6 +1116,18 @@ class Output:
                 f"unsupported statistics type: {type(self.statistics)}, supported types are `Statistics` or `dict`"
             )
 
+        if self.metrics is None:
+            metrics = None
+        elif isinstance(self.metrics, dict):
+            metrics = self.metrics
+        else:
+            raise TypeError(f"unsupported metrics type: {type(self.metrics)}, supported type is `dict`")
+
+        # if both metrics and statistics are None, set statistics to an
+        # empty dict for backward compatibility
+        if statistics is None and metrics is None:
+            statistics = {}
+
         # Assets need to end up as a list of dicts, so we achieve that based on
         # the type of each asset in the list.
         assets = []
@@ -1117,10 +1147,16 @@ class Output:
         output_dict = {
             "options": options,
             "solution": self.solution if self.solution is not None else {},
-            STATISTICS_KEY: statistics,
             ASSETS_KEY: assets,
         }
 
+        # Only include statistics in output if it's not None
+        if statistics is not None:
+            output_dict[STATISTICS_KEY] = statistics
+
+        if metrics is not None:
+            output_dict[METRICS_KEY] = metrics
+
         # Add the auxiliary configurations to the output dictionary if they are
         # defined and not empty.
         if (
@@ -1193,9 +1229,9 @@ class LocalOutputWriter(OutputWriter):
 
     Examples
     --------
-    >>> from nextmv.output import LocalOutputWriter, Output, Statistics
+    >>> from nextmv.output import LocalOutputWriter, Output, Metrics
     >>> writer = LocalOutputWriter()
-    >>> output = Output(solution={"result": 42}, statistics=Statistics())
+    >>> output = Output(solution={"result": 42}, metrics={"time": 1.23})
     >>> # Write to stdout
     >>> writer.write(output, path=None)
     >>> # Write to a file

nextmv/run.py

@@ -434,6 +434,9 @@ class RunInfoStatistics(BaseModel):
     """List of statistics indicators."""
 
 
+RunInfoMetrics = RunInfoStatistics
+
+
 class OptionsSummaryItem(BaseModel):
     """
     Summary item for options used in a run.
@@ -529,7 +532,9 @@ class Run(BaseModel):
     experiment_id : str, optional
         ID of the experiment associated with the run. Defaults to None.
     statistics : RunInfoStatistics, optional
-        Statistics of the run. Defaults to None.
+        Deprecated: Statistics of the run. Defaults to None.
+    metrics: RunInfoMetrics, optional
+        Metrics of the run. Defaults to None.
     input_id : str, optional
         ID of the input associated with the run. Defaults to None.
     option_set : str, optional
@@ -603,7 +608,9 @@ class Run(BaseModel):
     experiment_id: str | None = None
     """ID of the experiment associated with the run."""
     statistics: RunInfoStatistics | None = None
-    """Statistics of the run."""
+    """Deprecated: Statistics of the run."""
+    metrics: RunInfoMetrics | None = None
+    """Metrics of the run."""
     input_id: str | None = None
     """ID of the input associated with the run."""
     option_set: str | None = None
@@ -677,7 +684,9 @@ class Metadata(BaseModel):
     status_v2: StatusV2
     """Status of the run."""
     statistics: dict[str, Any] | None = None
-    """User defined statistics of the run."""
+    """Deprecated: User defined statistics of the run."""
+    metrics: dict[str, Any] | None = None
+    """User defined metrics of the run."""
 
     def run_is_finalized(self) -> bool:
         """

{nextmv-1.0.0.dev6.dist-info → nextmv-1.0.0.dev8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 1.0.0.dev6
+Version: 1.0.0.dev8
 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/
@@ -230,13 +230,11 @@ Provides-Extra: dev
 Requires-Dist: build>=1.0.3; extra == 'dev'
 Requires-Dist: folium>=0.20.0; extra == 'dev'
 Requires-Dist: mlflow>=2.19.0; extra == 'dev'
-Requires-Dist: nextpipe>=0.6.0.dev0; extra == 'dev'
 Requires-Dist: nextroute>=1.11.1; extra == 'dev'
 Requires-Dist: openpyxl>=3.1.5; extra == 'dev'
 Requires-Dist: pandas>=2.2.3; extra == 'dev'
 Requires-Dist: plotly>=6.0.1; extra == 'dev'
 Requires-Dist: pydantic>=2.5.2; extra == 'dev'
-Requires-Dist: pytest>=9.0.2; extra == 'dev'
 Requires-Dist: pyyaml>=6.0.1; extra == 'dev'
 Requires-Dist: requests>=2.31.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.7; extra == 'dev'