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

nextmv/cloud/application/__init__.py

@@ -46,7 +46,9 @@ from nextmv.cloud.application._switchback import ApplicationSwitchbackMixin
 from nextmv.cloud.application._utils import _is_not_exist_error
 from nextmv.cloud.application._version import ApplicationVersionMixin
 from nextmv.cloud.client import Client
+from nextmv.cloud.instance import Instance
 from nextmv.cloud.url import UploadURL
+from nextmv.cloud.version import Version
 from nextmv.logger import log
 from nextmv.manifest import Manifest
 from nextmv.model import Model, ModelConfiguration
@@ -250,7 +252,7 @@ class Application(
     def new(
         cls,
         client: Client,
-        name: str,
+        name: str | None = None,
         id: str | None = None,
         description: str | None = None,
         is_workflow: bool | None = None,
@@ -268,13 +270,13 @@ class Application(
         ----------
         client : Client
             Client to use for interacting with the Nextmv Cloud API.
-        name : str
-            Name of the application.
-        id : str, optional
+        name : str | None = None
+            Name of the application. Uses the ID as the name if not provided.
+        id : str | None = None
             ID of the application. Will be generated if not provided.
-        description : str, optional
+        description : str | None = None
             Description of the application.
-        is_workflow : bool, optional
+        is_workflow : bool | None = None
             Whether the application is a Decision Workflow.
         exist_ok : bool, default=False
             If True and an application with the same ID already exists,
@@ -296,7 +298,10 @@ class Application(
         >>> app = Application.new(client=client, name="My New App", id="my-app")
         """
 
-        if id is None:
+        if exist_ok and (id is None or id == ""):
+            raise ValueError("If exist_ok is True, id must be provided")
+
+        if id is None or id == "":
             id = safe_id("app")
 
         if exist_ok and cls.exists(client=client, id=id):
@@ -307,6 +312,9 @@ class Application(
 
             return cls.from_dict({"client": client} | response.json())
 
+        if name is None or name == "":
+            name = id
+
         payload = {
             "name": name,
             "id": id,
@@ -399,10 +407,14 @@ class Application(
         model: Model | None = None,
         model_configuration: ModelConfiguration | None = None,
         rich_print: bool = False,
-        no_version: bool = False,
+        auto_create: bool = False,
         version_id: str | None = None,
         version_name: str | None = None,
         version_description: str | None = None,
+        instance_id: str | None = None,
+        instance_name: str | None = None,
+        instance_description: str | None = None,
+        update_default_instance: bool = False,
     ) -> None:
         """
         Push an app to Nextmv Cloud.
@@ -420,14 +432,16 @@ class Application(
         `nextmv.Model`. The model is encoded, some dependencies and
         accompanying files are packaged, and the app is pushed to Nextmv Cloud.
 
-        The default behavior of this function is to create a new application
-        version _after_ the app has been pushed. You can set the `no_version`
-        argument to `True` to skip this step. The `version_id`, `version_name`,
-        and `version_description` arguments can be used to customize the version
-        that is created. If the `version_id` is not specified, a randomly
-        generated ID will be used. If the `version_name` is not specified, a
-        generic name with a timestamp will be used. Lastly, if no description is
-        specified, then a generic description will also be used.
+        By default, this function only pushes the app. If you want to
+        automatically create a new version and instance after pushing, set
+        `auto_create=True`. The `version_id`, `version_name`, and
+        `version_description` arguments allow you to customize the new version
+        that is created. If not specified, defaults will be generated (random
+        ID, timestamped name/description). Similarly, `instance_id`,
+        `instance_name`, and `instance_description` can be used to customize
+        the new instance. If `update_default_instance` is True, the
+        application's default instance will be updated to the newly created
+        instance.
 
         Parameters
         ----------
@@ -447,21 +461,30 @@ class Application(
             with `model`.
         rich_print : bool, default=False
             Whether to use rich printing when verbose output is enabled.
-        no_version : bool, default=False
-            If True, do not create a new version after pushing the app.
+        auto_create : bool, default=False
+            If True, automatically create a new version and instance after
+            pushing the app.
         version_id : Optional[str], default=None
             ID of the version to create after pushing the app. If None, a unique
             ID will be generated.
         version_name : Optional[str], default=None
-            Name of the version to create after pushing the app. If None, a name
-            with a timestamp will be generated.
+            Name of the version to create after pushing the app. If None, a
+            name will be generated.
         version_description : Optional[str], default=None
             Description of the version to create after pushing the app. If None, a
             generic description with a timestamp will be generated.
-
-        Returns
-        -------
-        None
+        instance_id : Optional[str], default=None
+            ID of the instance to create after pushing the app. If None, a unique
+            ID will be generated.
+        instance_name : Optional[str], default=None
+            Name of the instance to create after pushing the app. If None, a
+            name will be generated.
+        instance_description : Optional[str], default=None
+            Description of the instance to create after pushing the app. If None,
+            a generic description with a timestamp will be generated.
+        update_default_instance : bool, default=False
+            If True, update the application's default instance to the newly
+            created instance.
 
         Raises
         ------
@@ -565,44 +588,43 @@ class Application(
         except OSError as e:
             raise Exception(f"error deleting output directory: {e}") from e
 
-        if no_version:
-            if verbose:
-                if rich_print:
-                    rich.print(
-                        f":white_check_mark: Push completed for Nextmv application [magenta]{self.id}[/magenta] "
-                        "without creating a new version.",
-                        file=sys.stderr,
-                    )
-                else:
-                    log("✅ Push completed without creating a new version for Nextmv application.")
-
+        if not auto_create:
             return
 
-        now = datetime.now(timezone.utc)
-        if version_id is None:
-            version_id = safe_id(prefix="version") + f"-{now.strftime('%Y%m%d-%H%M%S')}"
-        if version_name is None:
-            version_name = f"Version {version_id}"
-        if version_description is None:
-            version_description = f"Version created automatically from push at {now.strftime('%Y-%m-%dT%H:%M:%SZ')}"
-
-        version = self.new_version(
-            id=version_id,
-            name=version_name,
-            description=version_description,
-        )
-        version_dict = version.to_dict()
-
         if verbose:
             if rich_print:
                 rich.print(
-                    f":white_check_mark: Automatically created new version [magenta]{version.id}[/magenta].",
+                    f":hourglass_flowing_sand: Push completed for Nextmv application [magenta]{self.id}[/magenta], "
+                    "creating a new version and instance...",
                     file=sys.stderr,
                 )
-                rich.print_json(data=version_dict)
             else:
-                log(f'✅ Automatically created new version "{version.id}".')
-                log(json.dumps(version_dict, indent=2))
+                log("⌛️ Push completed for the Nextmv application, creating a new version and instance...")
+
+        now = datetime.now(timezone.utc)
+        version = self.__version_on_push(
+            now=now,
+            version_id=version_id,
+            version_name=version_name,
+            version_description=version_description,
+            verbose=verbose,
+            rich_print=rich_print,
+        )
+        instance = self.__instance_on_push(
+            now=now,
+            version_id=version.id,
+            instance_id=instance_id,
+            instance_name=instance_name,
+            instance_description=instance_description,
+            verbose=verbose,
+            rich_print=rich_print,
+        )
+        self.__update_on_push(
+            instance=instance,
+            update_default_instance=update_default_instance,
+            verbose=verbose,
+            rich_print=rich_print,
+        )
 
     def update(
         self,
@@ -845,6 +867,8 @@ class Application(
                     output_config = multi_config["output_configuration"] = {}
                     if content.multi_file.output.statistics:
                         output_config["statistics_path"] = content.multi_file.output.statistics
+                    if content.multi_file.output.metrics:
+                        output_config["metrics_path"] = content.multi_file.output.metrics
                     if content.multi_file.output.assets:
                         output_config["assets_path"] = content.multi_file.output.assets
                     if content.multi_file.output.solutions:
@@ -919,6 +943,120 @@ class Application(
                 log(f'💥️ Successfully pushed to application: "{self.id}".')
                 log(json.dumps(data, indent=2))
 
+    def __version_on_push(
+        self,
+        now: datetime,
+        version_id: str | None = None,
+        version_name: str | None = None,
+        version_description: str | None = None,
+        verbose: bool = False,
+        rich_print: bool = False,
+    ) -> Version:
+        if version_description is None or version_description == "":
+            version_description = f"Version created automatically from push at {now.strftime('%Y-%m-%dT%H:%M:%SZ')}"
+
+        version = self.new_version(
+            id=version_id,
+            name=version_name,
+            description=version_description,
+        )
+        version_dict = version.to_dict()
+
+        if not verbose:
+            return version
+
+        if rich_print:
+            rich.print(
+                f":white_check_mark: Automatically created new version [magenta]{version.id}[/magenta].",
+                file=sys.stderr,
+            )
+            rich.print_json(data=version_dict)
+
+            return version
+
+        log(f'✅ Automatically created new version "{version.id}".')
+        log(json.dumps(version_dict, indent=2))
+
+        return version
+
+    def __instance_on_push(
+        self,
+        now: datetime,
+        version_id: str,
+        instance_id: str | None = None,
+        instance_name: str | None = None,
+        instance_description: str | None = None,
+        verbose: bool = False,
+        rich_print: bool = False,
+    ) -> Instance:
+        if instance_description is None or instance_description == "":
+            instance_description = f"Instance created automatically from push at {now.strftime('%Y-%m-%dT%H:%M:%SZ')}"
+
+        instance = self.new_instance(
+            version_id=version_id,
+            id=instance_id,
+            name=instance_name,
+            description=instance_description,
+        )
+        instance_dict = instance.to_dict()
+
+        if not verbose:
+            return instance
+
+        if rich_print:
+            rich.print(
+                f":white_check_mark: Automatically created new instance [magenta]{instance.id}[/magenta] "
+                f"using version [magenta]{version_id}[/magenta].",
+                file=sys.stderr,
+            )
+            rich.print_json(data=instance_dict)
+
+            return instance
+
+        log(f'✅ Automatically created new instance "{instance.id}" using version "{version_id}".')
+        log(json.dumps(instance_dict, indent=2))
+
+        return instance
+
+    def __update_on_push(
+        self,
+        instance: Instance,
+        update_default_instance: bool = False,
+        verbose: bool = False,
+        rich_print: bool = False,
+    ) -> None:
+        if not update_default_instance:
+            return
+
+        if verbose:
+            if rich_print:
+                rich.print(
+                    f":hourglass_flowing_sand: Updating default instance for app [magenta]{self.id}[/magenta]...",
+                    file=sys.stderr,
+                )
+            else:
+                log("⌛️ Updating default instance for the Nextmv application...")
+
+        updated_app = self.update(default_instance_id=instance.id)
+        if not verbose:
+            return
+
+        if rich_print:
+            rich.print(
+                f":white_check_mark: Updated default instance to "
+                f"[magenta]{updated_app.default_instance_id}[/magenta] for application "
+                f"[magenta]{self.id}[/magenta].",
+                file=sys.stderr,
+            )
+            rich.print_json(data=updated_app.to_dict())
+
+            return
+
+        log(
+            f'✅ Updated default instance to "{updated_app.default_instance_id}" for application "{self.id}".',
+        )
+        log(json.dumps(updated_app.to_dict(), indent=2))
+
 
 def list_applications(client: Client) -> list[Application]:
     """

nextmv/cloud/application/_batch_scenario.py

@@ -10,7 +10,6 @@ from nextmv.cloud.batch_experiment import (
     BatchExperimentMetadata,
     BatchExperimentRun,
     ExperimentStatus,
-    to_runs,
 )
 from nextmv.cloud.input_set import InputSet, ManagedInput
 from nextmv.cloud.scenario import Scenario, ScenarioInputType, _option_sets, _scenarios_by_id
@@ -258,7 +257,6 @@ class ApplicationBatchMixin:
         self: "Application",
         name: str | None = None,
         input_set_id: str | None = None,
-        instance_ids: list[str] | None = None,
         description: str | None = None,
         id: str | None = None,
         option_sets: dict[str, dict[str, str]] | None = None,
@@ -274,9 +272,6 @@ class ApplicationBatchMixin:
             Name of the batch experiment. If not provided, the ID will be used as the name.
         input_set_id: str | None
             ID of the input set to use for the batch experiment.
-        instance_ids: list[str]
-            This argument is deprecated, use `runs` instead.
-            List of instance IDs to use for the batch experiment.
         description: Optional[str]
             Optional description of the batch experiment.
         id: Optional[str]
@@ -304,11 +299,11 @@ class ApplicationBatchMixin:
         """
 
         # Generate ID if not provided
-        if id is None:
+        if id is None or id == "":
             id = safe_id("batch")
 
         # Use ID as name if name not provided
-        if name is None:
+        if name is None or name == "":
             name = id
 
         payload = {
@@ -317,11 +312,6 @@ class ApplicationBatchMixin:
         }
         if input_set_id is not None:
             payload["input_set_id"] = input_set_id
-        if instance_ids is not None:
-            input_set = self.input_set(input_set_id)
-            runs = to_runs(instance_ids, input_set)
-            payload_runs = [run.to_dict() for run in runs]
-            payload["runs"] = payload_runs
         if description is not None:
             payload["description"] = description
         if option_sets is not None:
@@ -346,7 +336,6 @@ class ApplicationBatchMixin:
         self: "Application",
         name: str | None = None,
         input_set_id: str | None = None,
-        instance_ids: list[str] | None = None,
         description: str | None = None,
         id: str | None = None,
         option_sets: dict[str, dict[str, str]] | None = None,
@@ -368,9 +357,6 @@ class ApplicationBatchMixin:
             Name of the batch experiment. If not provided, the ID will be used as the name.
         input_set_id: str
             ID of the input set to use for the batch experiment.
-        instance_ids: list[str]
-            List of instance IDs to use for the batch experiment. This argument
-            is deprecated, use `runs` instead.
         description: Optional[str]
             Optional description of the batch experiment.
         id: Optional[str]
@@ -402,7 +388,6 @@ class ApplicationBatchMixin:
         batch_id = self.new_batch_experiment(
             name=name,
             input_set_id=input_set_id,
-            instance_ids=instance_ids,
             description=description,
             id=id,
             option_sets=option_sets,
@@ -481,11 +466,11 @@ class ApplicationBatchMixin:
             raise ValueError("At least one scenario must be provided")
 
         # Generate ID if not provided
-        if id is None:
+        if id is None or id == "":
             id = safe_id("scenario")
 
         # Use ID as name if name not provided
-        if name is None:
+        if name is None or name == "":
             name = id
 
         scenarios_by_id = _scenarios_by_id(scenarios)

nextmv/cloud/application/_instance.py

@@ -194,15 +194,15 @@ class ApplicationInstanceMixin:
         'Production Instance'
         """
 
-        if exist_ok and id is None:
+        if exist_ok and (id is None or id == ""):
             raise ValueError("If exist_ok is True, id must be provided")
 
         if exist_ok and self.instance_exists(instance_id=id):
             return self.instance(instance_id=id)
 
-        if id is None:
+        if id is None or id == "":
             id = safe_id(prefix="instance")
-        if name is None:
+        if name is None or name == "":
             name = id
 
         payload = {

nextmv/cloud/application/_managed_input.py

@@ -147,9 +147,9 @@ class ApplicationManagedInputMixin:
         if upload_id is None and run_id is None:
             raise ValueError("Either upload_id or run_id must be specified")
 
-        if id is None:
+        if id is None or id == "":
             id = safe_id(prefix="managed-input")
-        if name is None:
+        if name is None or name == "":
             name = id
 
         payload = {

nextmv/cloud/application/_run.py

@@ -21,7 +21,14 @@ from nextmv.cloud.url import DownloadURL
 from nextmv.input import Input, InputFormat
 from nextmv.logger import log
 from nextmv.options import Options
-from nextmv.output import ASSETS_KEY, STATISTICS_KEY, Asset, Output, OutputFormat, Statistics
+from nextmv.output import (
+    ASSETS_KEY,
+    STATISTICS_KEY,
+    Asset,
+    Output,
+    OutputFormat,
+    Statistics,
+)
 from nextmv.polling import DEFAULT_POLLING_OPTIONS, PollingOptions, poll
 from nextmv.run import (
     ExternalRunResult,

nextmv/cloud/application/_shadow.py

@@ -204,11 +204,11 @@ class ApplicationShadowMixin:
             shadow_test_id = safe_id("shadow")
 
         # Use ID as name if name not provided
-        if name is None:
+        if name is None or name == "":
             name = shadow_test_id
 
         payload = {
-            "id": id,
+            "id": shadow_test_id,
             "name": name,
             "comparisons": comparisons,
             "termination_events": termination_events.to_dict(),

nextmv/cloud/application/_switchback.py

@@ -172,9 +172,11 @@ class ApplicationSwitchbackMixin:
         comparison : TestComparisonSingle
             Comparison defining the baseline and candidate instances.
         unit_duration_minutes : float
-            Duration of each interval in minutes.
+            Duration of each interval in minutes. The value must be between 1
+            and 10080.
         units : int
-            Total number of intervals in the switchback test.
+            Total number of intervals in the switchback test. The value must be
+            between 1 and 1000.
         switchback_test_id : Optional[str], default=None
             Optional ID for the switchback test. Will be generated if not
             provided.
@@ -197,16 +199,22 @@ class ApplicationSwitchbackMixin:
             If the response status code is not 2xx.
         """
 
+        if unit_duration_minutes < 1 or unit_duration_minutes > 10080:
+            raise ValueError("unit_duration_minutes must be between 1 and 10080")
+
+        if units < 1 or units > 1000:
+            raise ValueError("units must be between 1 and 1000")
+
         # Generate ID if not provided
         if switchback_test_id is None:
             switchback_test_id = safe_id("switchback")
 
         # Use ID as name if name not provided
-        if name is None:
+        if name is None or name == "":
             name = switchback_test_id
 
         payload = {
-            "id": id,
+            "id": switchback_test_id,
             "name": name,
             "comparison": comparison,
             "generate_random_plan": {

nextmv/cloud/application/_version.py

@@ -132,15 +132,16 @@ class ApplicationVersionMixin:
         ... )
         """
 
-        if exist_ok and id is None:
+        if exist_ok and (id is None or id == ""):
             raise ValueError("If exist_ok is True, id must be provided")
 
         if exist_ok and self.version_exists(version_id=id):
             return self.version(version_id=id)
 
-        if id is None:
+        if id is None or id == "":
             id = safe_id(prefix="version")
-        if name is None:
+
+        if name is None or name == "":
             name = id
 
         payload = {

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

@@ -90,7 +90,7 @@ class TerminationEvents(BaseModel):
 
     maximum_runs: int
     """
-    Maximum number of runs for the test. Min should be 1, max should be 300.
+    Maximum number of runs for the test. Value must be between 1 and 300.
     """
     time: datetime | None = None
     """
@@ -99,8 +99,8 @@ class TerminationEvents(BaseModel):
     """
 
     def model_post_init(self, __context):
-        if self.maximum_runs < 1:
-            raise ValueError("maximum_runs must be at least 1")
+        if self.maximum_runs < 1 or self.maximum_runs > 300:
+            raise ValueError("maximum_runs must be between 1 and 300")
 
 
 class ShadowTestMetadata(BaseModel):
@@ -151,7 +151,10 @@ class ShadowTestMetadata(BaseModel):
     """The current status of the shadow test."""
 
 
-class ShadowTest(ShadowTestMetadata):
+# This class uses some fields defined in ShadowTestMetadata. We are not
+# using inheritance to help the user understand the full structure when using
+# tools like intellisense.
+class ShadowTest(BaseModel):
     """
     A Nextmv Cloud shadow test definition.
 
@@ -166,6 +169,20 @@ class ShadowTest(ShadowTestMetadata):
 
     Parameters
     ----------
+    shadow_test_id : str, optional
+        The unique identifier of the shadow test.
+    name : str, optional
+        Name of the shadow test.
+    description : str, optional
+        Description of the shadow test.
+    app_id : str, optional
+        ID of the application to which the shadow test belongs.
+    created_at : datetime, optional
+        Creation date of the shadow test.
+    updated_at : datetime, optional
+        Last update date of the shadow test.
+    status : ExperimentStatus, optional
+        The current status of the shadow test.
     completed_at : datetime, optional
         Completion date of the shadow test, if applicable.
     comparisons : list[TestComparison], optional
@@ -174,8 +191,30 @@ class ShadowTest(ShadowTestMetadata):
         Start events for the shadow test.
     termination_events : TerminationEvents, optional
         Termination events for the shadow test.
+    grouped_distributional_summaries : list[dict[str, Any]], optional
+        Grouped distributional summaries of the shadow test.
+    runs : list[Run], optional
+        List of runs in the shadow test.
     """
 
+    shadow_test_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "shadow_test_id"),
+        default=None,
+    )
+    """The unique identifier of the shadow test."""
+    name: str | None = None
+    """Name of the shadow test."""
+    description: str | None = None
+    """Description of the shadow test."""
+    app_id: str | None = None
+    """ID of the application to which the shadow test belongs."""
+    created_at: datetime | None = None
+    """Creation date of the shadow test."""
+    updated_at: datetime | None = None
+    """Last update date of the shadow test."""
+    status: ExperimentStatus | None = None
+    """The current status of the shadow test."""
     completed_at: datetime | None = None
     """Completion date of the shadow test, if applicable."""
     comparisons: list[TestComparison] | None = None