nextmv 0.29.4.dev0__py3-none-any.whl → 0.29.5.dev0__py3-none-any.whl

nextmv/__about__.py

@@ -1 +1 @@
-__version__ = "v0.29.4-dev.0"
+__version__ = "v0.29.5.dev.0"

nextmv/cloud/__init__.py

@@ -46,6 +46,7 @@ from .run import ErrorLog as ErrorLog
 from .run import ExternalRunResult as ExternalRunResult
 from .run import Format as Format
 from .run import FormatInput as FormatInput
+from .run import FormatOutput as FormatOutput
 from .run import Metadata as Metadata
 from .run import RunConfiguration as RunConfiguration
 from .run import RunInformation as RunInformation

nextmv/cloud/application.py

@@ -56,13 +56,14 @@ from nextmv.cloud.run import (
     ExternalRunResult,
     Format,
     FormatInput,
+    FormatOutput,
     RunConfiguration,
     RunInformation,
     RunLog,
     RunResult,
     TrackedRun,
 )
-from nextmv.cloud.safe import _name_and_id
+from nextmv.cloud.safe import _name_and_id, _safe_id
 from nextmv.cloud.scenario import Scenario, ScenarioInputType, _option_sets, _scenarios_by_id
 from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
 from nextmv.cloud.status import StatusV2
@@ -71,7 +72,7 @@ from nextmv.input import Input, InputFormat
 from nextmv.logger import log
 from nextmv.model import Model, ModelConfiguration
 from nextmv.options import Options
-from nextmv.output import Output
+from nextmv.output import Output, OutputFormat
 
 # Maximum size of the run input/output in bytes. This constant defines the
 # maximum allowed size for run inputs and outputs. When the size exceeds this
@@ -1588,7 +1589,10 @@ class Application:
         if format is not None:
             payload["format"] = format.to_dict() if isinstance(format, Format) else format
         else:
-            payload["format"] = Format(format_input=FormatInput(input_type=InputFormat.JSON)).to_dict()
+            payload["format"] = Format(
+                format_input=FormatInput(input_type=InputFormat.JSON),
+                format_output=FormatOutput(output_type=OutputFormat.JSON),
+            ).to_dict()
 
         response = self.client.request(
             method="POST",
@@ -1610,7 +1614,7 @@ class Application:
         batch_experiment_id: Optional[str] = None,
         external_result: Optional[Union[ExternalRunResult, dict[str, Any]]] = None,
         json_configurations: Optional[dict[str, Any]] = None,
-        dir_path: Optional[str] = None,
+        input_dir_path: Optional[str] = None,
     ) -> str:
         """
         Submit an input to start a new run of the application. Returns the
@@ -1627,14 +1631,14 @@ class Application:
             input data is extracted from the `.data` property.
 
             If you want to work with `nextmv.InputFormat.CSV_ARCHIVE` or
-            `nextmv.InputFormat.MULTI_FILE`, you should use the `dir_path`
+            `nextmv.InputFormat.MULTI_FILE`, you should use the `input_dir_path`
             argument instead. This argument takes precedence over the `input`.
-            If `dir_path` is specified, this function looks for files in that
+            If `input_dir_path` is specified, this function looks for files in that
             directory and tars them, to later be uploaded using the
-            `upload_large_input` method. If both the `dir_path` and `input`
+            `upload_large_input` method. If both the `input_dir_path` and `input`
             arguments are provided, the `input` is ignored.
 
-            When `dir_path` is specified, the `configuration` argument must
+            When `input_dir_path` is specified, the `configuration` argument must
             also be provided. More specifically, the
             `RunConfiguration.format.format_input.input_type` parameter
             dictates what kind of input is being submitted to the Nextmv Cloud.
@@ -1686,12 +1690,12 @@ class Application:
         json_configurations: Optional[dict[str, Any]]
             Optional configurations for JSON serialization. This is used to
             customize the serialization before data is sent.
-        dir_path: Optional[str]
+        input_dir_path: Optional[str]
             Path to a directory containing input files. If specified, the
             function will package the files in the directory into a tar file
             and upload it as a large input. This is useful for input formats
             like `nextmv.InputFormat.CSV_ARCHIVE` or `nextmv.InputFormat.MULTI_FILE`.
-            If both `input` and `dir_path` are specified, the `input` is
+            If both `input` and `input_dir_path` are specified, the `input` is
             ignored, and the files in the directory are used instead.
 
         Returns
@@ -1708,17 +1712,17 @@ class Application:
             not `JSON`. If the final `options` are not of type `dict[str,str]`.
         """
 
-        self.__validate_dir_path_and_configuration(dir_path, configuration)
+        self.__validate_dir_path_and_configuration(input_dir_path, configuration)
 
         tar_file = ""
-        if dir_path is not None and dir_path != "":
-            if not os.path.exists(dir_path):
-                raise ValueError(f"Directory {dir_path} does not exist.")
+        if input_dir_path is not None and input_dir_path != "":
+            if not os.path.exists(input_dir_path):
+                raise ValueError(f"Directory {input_dir_path} does not exist.")
 
-            if not os.path.isdir(dir_path):
-                raise ValueError(f"Path {dir_path} is not a directory.")
+            if not os.path.isdir(input_dir_path):
+                raise ValueError(f"Path {input_dir_path} is not a directory.")
 
-            tar_file = self.__package_inputs(dir_path)
+            tar_file = self.__package_inputs(input_dir_path)
 
         input_data = None
         if isinstance(input, BaseModel):
@@ -1775,7 +1779,7 @@ class Application:
             )
         else:
             configuration = RunConfiguration()
-            configuration.resolve(input=input, dir_path=dir_path)
+            configuration.resolve(input=input, dir_path=input_dir_path)
             configuration_dict = configuration.to_dict()
 
         payload["configuration"] = configuration_dict
@@ -1814,7 +1818,8 @@ class Application:
         batch_experiment_id: Optional[str] = None,
         external_result: Optional[Union[ExternalRunResult, dict[str, Any]]] = None,
         json_configurations: Optional[dict[str, Any]] = None,
-        dir_path: Optional[str] = None,
+        input_dir_path: Optional[str] = None,
+        output_dir_path: Optional[str] = ".",
     ) -> RunResult:
         """
         Submit an input to start a new run of the application and poll for the
@@ -1833,14 +1838,14 @@ class Application:
             input data is extracted from the `.data` property.
 
             If you want to work with `nextmv.InputFormat.CSV_ARCHIVE` or
-            `nextmv.InputFormat.MULTI_FILE`, you should use the `dir_path`
+            `nextmv.InputFormat.MULTI_FILE`, you should use the `input_dir_path`
             argument instead. This argument takes precedence over the `input`.
-            If `dir_path` is specified, this function looks for files in that
+            If `input_dir_path` is specified, this function looks for files in that
             directory and tars them, to later be uploaded using the
-            `upload_large_input` method. If both the `dir_path` and `input`
+            `upload_large_input` method. If both the `input_dir_path` and `input`
             arguments are provided, the `input` is ignored.
 
-            When `dir_path` is specified, the `configuration` argument must
+            When `input_dir_path` is specified, the `configuration` argument must
             also be provided. More specifically, the
             `RunConfiguration.format.format_input.input_type` parameter
             dictates what kind of input is being submitted to the Nextmv Cloud.
@@ -1897,13 +1902,17 @@ class Application:
         json_configurations: Optional[dict[str, Any]]
             Optional configurations for JSON serialization. This is used to
             customize the serialization before data is sent.
-        dir_path: Optional[str]
+        input_dir_path: Optional[str]
             Path to a directory containing input files. If specified, the
             function will package the files in the directory into a tar file
             and upload it as a large input. This is useful for input formats
             like `nextmv.InputFormat.CSV_ARCHIVE` or `nextmv.InputFormat.MULTI_FILE`.
-            If both `input` and `dir_path` are specified, the `input` is
+            If both `input` and `input_dir_path` are specified, the `input` is
             ignored, and the files in the directory are used instead.
+        output_dir_path : Optional[str], default="."
+            Path to a directory where non-JSON output files will be saved. This is
+            required if the output is non-JSON. If the directory does not exist, it
+            will be created. Uses the current directory by default.
 
         Returns
         ----------
@@ -1936,12 +1945,13 @@ class Application:
             batch_experiment_id=batch_experiment_id,
             external_result=external_result,
             json_configurations=json_configurations,
-            dir_path=dir_path,
+            input_dir_path=input_dir_path,
         )
 
         return self.run_result_with_polling(
             run_id=run_id,
             polling_options=polling_options,
+            output_dir_path=output_dir_path,
         )
 
     def new_scenario_test(
@@ -2215,10 +2225,13 @@ class Application:
         if exist_ok and self.version_exists(version_id=id):
             return self.version(version_id=id)
 
-        payload = {}
+        if id is None:
+            id = _safe_id(prefix="version")
+
+        payload = {
+            "id": id,
+        }
 
-        if id is not None:
-            payload["id"] = id
         if name is not None:
             payload["name"] = name
         if description is not None:
@@ -2501,7 +2514,7 @@ class Application:
         )
         return RunLog.from_dict(response.json())
 
-    def run_result(self, run_id: str) -> RunResult:
+    def run_result(self, run_id: str, output_dir_path: Optional[str] = ".") -> RunResult:
         """
         Get the result of a run.
 
@@ -2511,6 +2524,10 @@ class Application:
         ----------
         run_id : str
             ID of the run to get results for.
+        output_dir_path : Optional[str], default="."
+            Path to a directory where non-JSON output files will be saved. This is
+            required if the output is non-JSON. If the directory does not exist, it
+            will be created. Uses the current directory by default.
 
         Returns
         -------
@@ -2531,12 +2548,17 @@ class Application:
 
         run_information = self.run_metadata(run_id=run_id)
 
-        return self.__run_result(run_id=run_id, run_information=run_information)
+        return self.__run_result(
+            run_id=run_id,
+            run_information=run_information,
+            output_dir_path=output_dir_path,
+        )
 
     def run_result_with_polling(
         self,
         run_id: str,
         polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+        output_dir_path: Optional[str] = ".",
     ) -> RunResult:
         """
         Get the result of a run with polling.
@@ -2551,6 +2573,10 @@ class Application:
             ID of the run to retrieve the result for.
         polling_options : PollingOptions, default=_DEFAULT_POLLING_OPTIONS
             Options to use when polling for the run result.
+        output_dir_path : Optional[str], default="."
+            Path to a directory where non-JSON output files will be saved. This is
+            required if the output is non-JSON. If the directory does not exist, it
+            will be created. Uses the current directory by default.
 
         Returns
         -------
@@ -2592,7 +2618,11 @@ class Application:
 
         run_information = poll(polling_options=polling_options, polling_func=polling_func)
 
-        return self.__run_result(run_id=run_id, run_information=run_information)
+        return self.__run_result(
+            run_id=run_id,
+            run_information=run_information,
+            output_dir_path=output_dir_path,
+        )
 
     def scenario_test(self, scenario_test_id: str) -> BatchExperiment:
         """
@@ -2707,6 +2737,7 @@ class Application:
         tracked_run: TrackedRun,
         polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
         instance_id: Optional[str] = None,
+        output_dir_path: Optional[str] = ".",
     ) -> RunResult:
         """
         Track an external run and poll for the result. This is a convenience
@@ -2723,6 +2754,10 @@ class Application:
         instance_id: Optional[str]
             Optional instance ID if you want to associate your tracked run with
             an instance.
+        output_dir_path : Optional[str], default="."
+            Path to a directory where non-JSON output files will be saved. This is
+            required if the output is non-JSON. If the directory does not exist, it
+            will be created. Uses the current directory by default.
 
         Returns
         -------
@@ -2747,12 +2782,13 @@ class Application:
         return self.run_result_with_polling(
             run_id=run_id,
             polling_options=polling_options,
+            output_dir_path=output_dir_path,
         )
 
     def update_instance(
         self,
         id: str,
-        name: str,
+        name: Optional[str] = None,
         version_id: Optional[str] = None,
         description: Optional[str] = None,
         configuration: Optional[InstanceConfiguration] = None,
@@ -2764,14 +2800,14 @@ class Application:
         ----------
         id : str
             ID of the instance to update.
-        name : str
-            Name of the instance.
+        name : Optional[str], default=None
+            Optional name of the instance.
         version_id : Optional[str], default=None
-            ID of the version to associate the instance with.
+            Optional ID of the version to associate the instance with.
         description : Optional[str], default=None
-            Description of the instance.
+            Optional description of the instance.
         configuration : Optional[InstanceConfiguration], default=None
-            Configuration to use for the instance.
+            Optional configuration to use for the instance.
 
         Returns
         -------
@@ -2784,12 +2820,21 @@ class Application:
             If the response status code is not 2xx.
         """
 
-        payload = {}
+        # Get the instance as it currently exsits.
+        instance = self.instance(id)
+        instance_dict = instance.to_dict()
+
+        payload = {
+            "name": instance_dict["name"],
+            "version_id": instance_dict["version_id"],
+            "description": instance_dict["description"],
+            "configuration": instance_dict["configuration"],
+        }
 
-        if version_id is not None:
-            payload["version_id"] = version_id
         if name is not None:
             payload["name"] = name
+        if version_id is not None:
+            payload["version_id"] = version_id
         if description is not None:
             payload["description"] = description
         if configuration is not None:
@@ -2806,8 +2851,8 @@ class Application:
     def update_batch_experiment(
         self,
         batch_experiment_id: str,
-        name: str,
-        description: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
     ) -> BatchExperimentInformation:
         """
         Update a batch experiment.
@@ -2816,10 +2861,10 @@ class Application:
         ----------
         batch_experiment_id : str
             ID of the batch experiment to update.
-        name : str
-            Name of the batch experiment.
-        description : str
-            Description of the batch experiment.
+        name : Optional[str], default=None
+            Optional name of the batch experiment.
+        description : Optional[str], default=None
+            Optional description of the batch experiment.
 
         Returns
         -------
@@ -2832,10 +2877,13 @@ class Application:
             If the response status code is not 2xx.
         """
 
-        payload = {
-            "name": name,
-            "description": description,
-        }
+        payload = {}
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
         response = self.client.request(
             method="PATCH",
             endpoint=f"{self.experiments_endpoint}/batch/{batch_experiment_id}",
@@ -2847,9 +2895,9 @@ class Application:
     def update_managed_input(
         self,
         managed_input_id: str,
-        name: str,
-        description: str,
-    ) -> None:
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> ManagedInput:
         """
         Update a managed input.
 
@@ -2857,15 +2905,15 @@ class Application:
         ----------
         managed_input_id : str
             ID of the managed input to update.
-        name : str
-            Name of the managed input.
-        description : str
-            Description of the managed input.
+        name : Optional[str], default=None
+            Optional new name for the managed input.
+        description : Optional[str], default=None
+            Optional new description for the managed input.
 
         Returns
         -------
-        None
-            No return value.
+        ManagedInput
+            The updated managed input.
 
         Raises
         ------
@@ -2873,21 +2921,32 @@ class Application:
             If the response status code is not 2xx.
         """
 
+        managed_input = self.managed_input(managed_input_id)
+        managed_input_dict = managed_input.to_dict()
+
         payload = {
-            "name": name,
-            "description": description,
+            "name": managed_input_dict["name"],
+            "description": managed_input_dict["description"],
         }
-        _ = self.client.request(
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
             method="PUT",
             endpoint=f"{self.endpoint}/inputs/{managed_input_id}",
             payload=payload,
         )
 
+        return ManagedInput.from_dict(response.json())
+
     def update_scenario_test(
         self,
         scenario_test_id: str,
-        name: str,
-        description: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
     ) -> BatchExperimentInformation:
         """
         Update a scenario test.
@@ -2900,10 +2959,10 @@ class Application:
         ----------
         scenario_test_id : str
             ID of the scenario test to update.
-        name : str
-            New name for the scenario test.
-        description : str
-            New description for the scenario test.
+        name : Optional[str], default=None
+            Optional new name for the scenario test.
+        description : Optional[str], default=None
+            Optional new description for the scenario test.
 
         Returns
         -------
@@ -2935,9 +2994,9 @@ class Application:
     def update_secrets_collection(
         self,
         secrets_collection_id: str,
-        name: str,
-        description: str,
-        secrets: list[Secret],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        secrets: Optional[list[Secret]] = None,
     ) -> SecretsCollectionSummary:
         """
         Update a secrets collection.
@@ -2950,13 +3009,13 @@ class Application:
         ----------
         secrets_collection_id : str
             ID of the secrets collection to update.
-        name : str
-            New name for the secrets collection.
-        description : str
-            New description for the secrets collection.
-        secrets : list[Secret]
-            List of secrets to update. Each secret should be an instance of the
-            Secret class containing a key and value.
+        name : Optional[str], default=None
+            Optional new name for the secrets collection.
+        description : Optional[str], default=None
+            Optional new description for the secrets collection.
+        secrets : Optional[list[Secret]], default=None
+            Optional list of secrets to update. Each secret should be an
+            instance of the Secret class containing a key and value.
 
         Returns
         -------
@@ -2988,14 +3047,22 @@ class Application:
         'api-secrets'
         """
 
-        if len(secrets) == 0:
-            raise ValueError("secrets must be provided")
+        collection = self.secrets_collection(secrets_collection_id)
+        collection_dict = collection.to_dict()
 
         payload = {
-            "name": name,
-            "description": description,
-            "secrets": [secret.to_dict() for secret in secrets],
+            "name": collection_dict["name"],
+            "description": collection_dict["description"],
+            "secrets": collection_dict["secrets"],
         }
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if secrets is not None and len(secrets) > 0:
+            payload["secrets"] = [secret.to_dict() for secret in secrets]
+
         response = self.client.request(
             method="PUT",
             endpoint=f"{self.endpoint}/secrets/{secrets_collection_id}",
@@ -3229,6 +3296,7 @@ class Application:
         self,
         run_id: str,
         run_information: RunInformation,
+        output_dir_path: Optional[str] = ".",
     ) -> RunResult:
         """
         Get the result of a run.
@@ -3245,6 +3313,10 @@ class Application:
             ID of the run to retrieve the result for.
         run_information : RunInformation
             Information about the run, including metadata such as output size.
+        output_dir_path : Optional[str], default="."
+            Path to a directory where non-JSON output files will be saved. This is
+            required if the output is non-JSON. If the directory does not exist, it
+            will be created. Uses the current directory by default.
 
         Returns
         -------
@@ -3265,10 +3337,13 @@ class Application:
         a download URL and fetch the output data separately.
         """
         query_params = None
-        large_output = False
-        if run_information.metadata.output_size > _MAX_RUN_SIZE:
+        use_presigned_url = False
+        if (
+            run_information.metadata.format.format_output.output_type != OutputFormat.JSON
+            or run_information.metadata.output_size > _MAX_RUN_SIZE
+        ):
             query_params = {"format": "url"}
-            large_output = True
+            use_presigned_url = True
 
         response = self.client.request(
             method="GET",
@@ -3278,7 +3353,7 @@ class Application:
         result = RunResult.from_dict(response.json())
         result.console_url = self.__console_url(result.id)
 
-        if not large_output:
+        if not use_presigned_url or result.metadata.status_v2 != StatusV2.succeeded:
             return result
 
         download_url = DownloadURL.from_dict(response.json()["output"])
@@ -3287,7 +3362,24 @@ class Application:
             endpoint=download_url.url,
             headers={"Content-Type": "application/json"},
         )
-        result.output = download_response.json()
+
+        # See whether we can attach the output directly or need to save to the given
+        # directory
+        if run_information.metadata.format.format_output.output_type != OutputFormat.JSON:
+            if not output_dir_path or output_dir_path == "":
+                raise ValueError(
+                    "If the output format is not JSON, an output_dir_path must be provided.",
+                )
+            if not os.path.exists(output_dir_path):
+                os.makedirs(output_dir_path, exist_ok=True)
+            # Save .tar.gz file to a temp directory and extract contents to output_dir_path
+            with tempfile.TemporaryDirectory() as tmpdirname:
+                temp_tar_path = os.path.join(tmpdirname, f"{run_id}.tar.gz")
+                with open(temp_tar_path, "wb") as f:
+                    f.write(download_response.content)
+                shutil.unpack_archive(temp_tar_path, output_dir_path)
+        else:
+            result.output = download_response.json()
 
         return result
 
@@ -3325,7 +3417,14 @@ class Application:
         }
 
         if manifest.configuration is not None and manifest.configuration.options is not None:
-            activation_request["requirements"]["options"] = manifest.configuration.options.to_dict()
+            options = manifest.configuration.options.to_dict()
+            if "format" in options and isinstance(options["format"], list):
+                # the endpoint expects a dictionary with a template key having a list of strings
+                # the app.yaml however defines format as a list of strings, so we need to convert it here
+                options["format"] = {
+                    "template": options["format"],
+                }
+            activation_request["requirements"]["options"] = options
 
         response = self.client.request(
             method="PUT",

nextmv/cloud/manifest.py

@@ -347,6 +347,9 @@ class ManifestOptionUI(BaseModel):
         A list of team roles to which this option will be hidden in the UI. For
         example, if you want to hide an option from the "operator" role, you can
         pass `hidden_from=["operator"]`.
+    display_name : str, optional
+        An optional display name for the option. This is useful for making
+        the option more user-friendly in the UI.
 
     Examples
     --------
@@ -360,6 +363,10 @@ class ManifestOptionUI(BaseModel):
     """The type of control to use for the option in the Nextmv Cloud UI."""
     hidden_from: Optional[list[str]] = None
     """A list of team roles for which this option will be hidden in the UI."""
+    display_name: Optional[str] = None
+    """An optional display name for the option. This is useful for making
+    the option more user-friendly in the UI.
+    """
 
 
 class ManifestOption(BaseModel):
@@ -484,8 +491,9 @@ class ManifestOption(BaseModel):
             ui=ManifestOptionUI(
                 control_type=option.control_type,
                 hidden_from=option.hidden_from,
+                display_name=option.display_name,
             )
-            if option.control_type or option.hidden_from
+            if option.control_type or option.hidden_from or option.display_name
             else None,
         )
 
@@ -535,6 +543,7 @@ class ManifestOption(BaseModel):
             additional_attributes=self.additional_attributes,
             control_type=self.ui.control_type if self.ui else None,
             hidden_from=self.ui.hidden_from if self.ui else None,
+            display_name=self.ui.display_name if self.ui else None,
         )
 
 
@@ -593,6 +602,10 @@ class ManifestOptions(BaseModel):
         is a parameter that configures the decision model.
     validation: Optional[ManifestValidation], default=None
         Optional validation rules for all options.
+    format: Optional[list[str]], default=None
+        A list of strings that define how options are transformed into command
+        line arguments. Use `{{name}}` to refer to the option name and
+        `{{value}}` to refer to the option value.
 
 
     Examples
@@ -621,9 +634,21 @@ class ManifestOptions(BaseModel):
 
     An option is a parameter that configures the decision model.
     """
+    format: Optional[list[str]] = None
+    """A list of strings that define how options are transformed into command line arguments.
+
+    Use `{{name}}` to refer to the option name and `{{value}}` to refer to the option value.
+    For example, `["-{{name}}", "{{value}}"]` will transform an option named `max_vehicles`
+    with a value of `10` into the command line argument `-max_vehicles 10`.
+    """
 
     @classmethod
-    def from_options(cls, options: Options, validation: OptionsEnforcement = None) -> "ManifestOptions":
+    def from_options(
+        cls,
+        options: Options,
+        validation: OptionsEnforcement = None,
+        format: Optional[list[str]] = None,
+    ) -> "ManifestOptions":
         """
         Create a `ManifestOptions` from a `nextmv.Options`.
 
@@ -634,6 +659,14 @@ class ManifestOptions(BaseModel):
         validation : Optional[OptionsEnforcement], default=None
             Optional validation rules for the options. If provided, it will be
             used to set the `validation` attribute of the `ManifestOptions`.
+        format : Optional[list[str]], default=None
+            A list of strings that define how options are transformed into
+            command line arguments. Use `{{name}}` to refer to the option name
+            and `{{value}}` to refer to the option value.
+
+            For example, `["-{{name}}", "{{value}}"]` will transform an option
+            named `max_vehicles` with a value of `10` into the command line
+            argument `-max_vehicles 10`.
 
         Returns
         -------
@@ -655,6 +688,7 @@ class ManifestOptions(BaseModel):
             strict=validation.strict if validation else False,
             validation=ManifestValidation(enforce="all" if validation and validation.validation_enforce else "none"),
             items=items,
+            format=format,
         )
 
 

nextmv/cloud/run.py

@@ -14,6 +14,8 @@ RunLog
     Log of a run.
 FormatInput
     Input format for a run configuration.
+FormatOutput
+    Output format for a run configuration.
 Format
     Format for a run configuration.
 RunType
@@ -110,6 +112,83 @@ def run_duration(start: Union[datetime, float], end: Union[datetime, float]) ->
     raise TypeError("Start and end must be either datetime or float.")
 
 
+class FormatInput(BaseModel):
+    """
+    Input format for a run configuration.
+
+    You can import the `FormatInput` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import FormatInput
+    ```
+
+    Parameters
+    ----------
+    input_type : InputFormat, optional
+        Type of the input format. Defaults to `InputFormat.JSON`.
+    """
+
+    input_type: InputFormat = Field(
+        serialization_alias="type",
+        validation_alias=AliasChoices("type", "input_type"),
+        default=InputFormat.JSON,
+    )
+    """Type of the input format."""
+
+
+class FormatOutput(BaseModel):
+    """
+    Output format for a run configuration.
+
+    You can import the `FormatOutput` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import FormatOutput
+    ```
+
+    Parameters
+    ----------
+    output_type : OutputFormat, optional
+        Type of the output format. Defaults to `OutputFormat.JSON`.
+    """
+
+    output_type: OutputFormat = Field(
+        serialization_alias="type",
+        validation_alias=AliasChoices("type", "output_type"),
+        default=OutputFormat.JSON,
+    )
+    """Type of the output format."""
+
+
+class Format(BaseModel):
+    """
+    Format for a run configuration.
+
+    You can import the `Format` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Format
+    ```
+
+    Parameters
+    ----------
+    format_input : FormatInput
+        Input format for the run configuration.
+    """
+
+    format_input: FormatInput = Field(
+        serialization_alias="input",
+        validation_alias=AliasChoices("input", "format_input"),
+    )
+    """Input format for the run configuration."""
+    format_output: Optional[FormatOutput] = Field(
+        serialization_alias="output",
+        validation_alias=AliasChoices("output", "format_output"),
+        default=None,
+    )
+    """Output format for the run configuration."""
+
+
 class Metadata(BaseModel):
     """
     Metadata of a run, whether it was successful or not.
@@ -160,6 +239,8 @@ class Metadata(BaseModel):
     """Size of the input in bytes."""
     output_size: float
     """Size of the output in bytes."""
+    format: Format
+    """Format of the input and output of the run."""
     status: Status
     """Deprecated: use status_v2."""
     status_v2: StatusV2
@@ -279,53 +360,6 @@ class RunLog(BaseModel):
     """Log of the run."""
 
 
-class FormatInput(BaseModel):
-    """
-    Input format for a run configuration.
-
-    You can import the `FormatInput` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import FormatInput
-    ```
-
-    Parameters
-    ----------
-    input_type : InputFormat, optional
-        Type of the input format. Defaults to `InputFormat.JSON`.
-    """
-
-    input_type: InputFormat = Field(
-        serialization_alias="type",
-        validation_alias=AliasChoices("type", "input_type"),
-        default=InputFormat.JSON,
-    )
-    """Type of the input format."""
-
-
-class Format(BaseModel):
-    """
-    Format for a run configuration.
-
-    You can import the `Format` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import Format
-    ```
-
-    Parameters
-    ----------
-    format_input : FormatInput
-        Input format for the run configuration.
-    """
-
-    format_input: FormatInput = Field(
-        serialization_alias="input",
-        validation_alias=AliasChoices("input", "format_input"),
-    )
-    """Input format for the run configuration."""
-
-
 class RunType(str, Enum):
     """
     The actual type of the run.
@@ -491,7 +525,10 @@ class RunConfiguration(BaseModel):
         if self.format is not None:
             return
 
-        self.format = Format(format_input=FormatInput(input_type=InputFormat.JSON))
+        self.format = Format(
+            format_input=FormatInput(input_type=InputFormat.JSON),
+            format_output=FormatOutput(output_type=OutputFormat.JSON),
+        )
 
         if isinstance(input, dict):
             self.format.format_input.input_type = InputFormat.JSON
@@ -504,6 +541,19 @@ class RunConfiguration(BaseModel):
         elif isinstance(input, Input):
             self.format.format_input.input_type = input.input_format
 
+        # As input and output are symmetric, we set the output according to the input
+        # format.
+        if self.format.format_input.input_type == InputFormat.JSON:
+            self.format.format_output = FormatOutput(output_type=OutputFormat.JSON)
+        elif self.format.format_input.input_type == InputFormat.TEXT:  # Text still maps to json
+            self.format.format_output = FormatOutput(output_type=OutputFormat.JSON)
+        elif self.format.format_input.input_type == InputFormat.CSV_ARCHIVE:
+            self.format.format_output = FormatOutput(output_type=OutputFormat.CSV_ARCHIVE)
+        elif self.format.format_input.input_type == InputFormat.MULTI_FILE:
+            self.format.format_output = FormatOutput(output_type=OutputFormat.MULTI_FILE)
+        else:
+            self.format.format_output = FormatOutput(output_type=OutputFormat.JSON)
+
 
 class ExternalRunResult(BaseModel):
     """

nextmv/cloud/safe.py

@@ -81,3 +81,33 @@ def _name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
     safe_name = _start_case(safe_id)
 
     return safe_name, safe_id
+
+
+def _safe_id(prefix: str) -> str:
+    """
+    Generate a safe ID from a prefix.
+
+    Parameters
+    ----------
+    prefix : str
+        Prefix to use for the ID.
+
+    Returns
+    -------
+    str
+        A safe ID.
+    """
+
+    random_slug = _nanoid(8)
+    # Space available for user text once prefix, random slug and separator "-"
+    # are accounted for
+    safe_id_max = (
+        ENTITY_ID_CHAR_COUNT_MAX - INDEX_TAG_CHAR_COUNT - (len(random_slug) + 1)  # +1 for the hyphen before the slug
+    )
+
+    if len(prefix) > safe_id_max:
+        return prefix[: safe_id_max - 1] + f"-{random_slug}"
+
+    safe_id = f"{prefix}-{random_slug}"
+
+    return safe_id

nextmv/model.py

@@ -160,7 +160,6 @@ class ModelConfiguration:
     """Enforcement of options for the model."""
 
 
-
 class Model:
     """
     Base class for defining decision models that run in Nextmv Cloud.

nextmv/options.py

@@ -227,6 +227,9 @@ class Option:
         A list of team roles to which this option will be hidden in the UI. For
         example, if you want to hide an option from the "operator" role, you can
         pass `hidden_from=["operator"]`.
+    display_name : str, optional
+        An optional display name for the option. This is useful for making
+        the option more user-friendly in the UI.
 
     Examples
     --------
@@ -284,6 +287,11 @@ class Option:
     example, if you want to hide an option from the "operator" role, you can
     pass `hidden_from=["operator"]`.
     """
+    display_name: Optional[str] = None
+    """
+    An optional display name for the option. This is useful for making
+    the option more user-friendly in the UI.
+    """
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "Option":
@@ -324,6 +332,7 @@ class Option:
             additional_attributes=data.get("additional_attributes"),
             control_type=data.get("control_type"),
             hidden_from=data.get("hidden_from"),
+            display_name=data.get("display_name"),
         )
 
     def to_dict(self) -> dict[str, Any]:
@@ -355,6 +364,7 @@ class Option:
             "additional_attributes": self.additional_attributes,
             "control_type": self.control_type,
             "hidden_from": self.hidden_from,
+            "display_name": self.display_name,
         }
 
 
@@ -980,6 +990,9 @@ class Options:
         if isinstance(option, Option) and option.hidden_from:
             description += f" (hidden from: {', '.join(option.hidden_from)})"
 
+        if isinstance(option, Option) and option.display_name is not None:
+            description += f" (display name: {option.display_name})"
+
         if option.description is not None and option.description != "":
             description += f": {option.description}"
 
@@ -1051,6 +1064,7 @@ class Options:
         else:
             raise TypeError(f"expected an <Option> (or deprecated <Parameter>) object, but got {type(option)}")
 
+
 class OptionsEnforcement:
     """
     OptionsEnforcement is a class that provides rules for how the options

{nextmv-0.29.4.dev0.dist-info → nextmv-0.29.5.dev0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.29.4.dev0
+Version: 0.29.5.dev0
 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/

{nextmv-0.29.4.dev0.dist-info → nextmv-0.29.5.dev0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-nextmv/__about__.py,sha256=1f2rCUHTiaPCOAFL0cbI3-MIHXTQtlwhbflKmSzQOuo,30
+nextmv/__about__.py,sha256=fH2N4VgXGHNLupMl8aEtSxm93zKJU7HumfTMlmPMKeE,30
 nextmv/__entrypoint__.py,sha256=dA0iwwHtrq6Z9w9FxmxKLoBGLyhe7jWtUAU-Y3PEgHg,1094
 nextmv/__init__.py,sha256=FsF0pEkOSBuPY5EKu7NsBxro7jswGmOmaw61kZEudXY,1930
 nextmv/_serialization.py,sha256=JlSl6BL0M2Esf7F89GsGIZ__Pp8RnFRNM0UxYhuuYU4,2853
@@ -6,21 +6,21 @@ nextmv/base_model.py,sha256=qmJ4AsYr9Yv01HQX_BERrn3229gyoZrYyP9tcyqNfeU,2311
 nextmv/deprecated.py,sha256=kEVfyQ-nT0v2ePXTNldjQG9uH5IlfQVy3L4tztIxwmU,1638
 nextmv/input.py,sha256=iTMIdhSi4H-Xot44CYaUH110WDcpWDsJ5JXxSMGIZaY,40030
 nextmv/logger.py,sha256=kNIbu46MisrzYe4T0hNMpWfRTKKacDVvbtQcNys_c_E,2513
-nextmv/model.py,sha256=SVoJLN_f5knXjaPLlyWWvzIqX_qKu1txn6pYfKPwt14,15019
-nextmv/options.py,sha256=-9ru7nzqMsFf0aAAfR5OuMvChXYT6aho5sGghHKu8Ds,37323
+nextmv/model.py,sha256=vI3pSV3iTwjRPflar7nAg-6h98XRUyi9II5O2J06-Kc,15018
+nextmv/options.py,sha256=yPJu5lYMbV6YioMwAXv7ctpZUggLXKlZc9CqIbUFvE4,37895
 nextmv/output.py,sha256=vcBqtP1hJLYyUvfk_vl1Ejbk3q5KxOmlTz4Lnqqnyd0,54141
-nextmv/cloud/__init__.py,sha256=7BCh3z-XkbIcMvFHmbj2wA8OquIovjrAZL7O9kA9VZc,3868
+nextmv/cloud/__init__.py,sha256=cGRkIcn1evTdgw7lEH2k4MPTZnq37XIF3ovbuDjUWGI,3914
 nextmv/cloud/acceptance_test.py,sha256=Bcfdmh2fkPeBx8FDCngeUo2fjV_LhsUdygnzDQCDbYY,26898
 nextmv/cloud/account.py,sha256=eukiYQha4U2fkIjg4SgdoawKE1kU5G7GPyDJVrn8hHA,6064
-nextmv/cloud/application.py,sha256=kWmmufaNP7t5ijaliiJTJ1Bt5URx3ETJOAk80tOgrEc,124634
+nextmv/cloud/application.py,sha256=P5LYXNYlaJYTZiCbJxxG3pvT6KLHS8ZK8HO1R46Lju4,130127
 nextmv/cloud/batch_experiment.py,sha256=Rmcwe1uAVz2kRrAMQqLYC5d__L_IqPXbF__RE3uQTAY,8196
 nextmv/cloud/client.py,sha256=E0DiUb377jvEnpXlRnfT1PGCI0Jm0lTUoX5VqeU91lk,18165
 nextmv/cloud/input_set.py,sha256=2dqmf5z-rZjTKwtBRvnUdfPfKv28It5uTCX0C70uP4Y,4242
 nextmv/cloud/instance.py,sha256=SS4tbp0LQMWDaeYpwcNxJei82oi_Hozv1t5i3QGjASY,4024
-nextmv/cloud/manifest.py,sha256=k_i_KlQ33Lsz9hhirWDRbXMdyEh-aM-4aWOhIBhiGAA,35781
+nextmv/cloud/manifest.py,sha256=5FqXtT1q7qmyQxqB5rG33y97WFZ6erL1f9kRel575RQ,37456
 nextmv/cloud/package.py,sha256=f0OjdlIOsI2LpmgSxdFf6YaA8Ucs9yAm_3bO0Cp8LH4,13027
-nextmv/cloud/run.py,sha256=YPBVjbnc6Ebgjxm5Rw1eY2-MiYx3KC7fQyqKWXY9auY,20836
-nextmv/cloud/safe.py,sha256=idifvV8P_79Zo2hIC_qxqZt9LUmD5TLQ9ikKwRUvd34,2522
+nextmv/cloud/run.py,sha256=-I1S5fLIFLH1P9xViv5bOS2LbO9-w6tnB8cBGU0_yTo,22743
+nextmv/cloud/safe.py,sha256=hWh_quD2KSazTV5SOAddOsFLsY4oWBzajOUcCeHOjc8,3180
 nextmv/cloud/scenario.py,sha256=JRFTDiFBcrgud6wE2qDHUu5oO-Ur3zbPYhhB6ONCxTo,14263
 nextmv/cloud/secrets.py,sha256=fA5cX0jfTsPVZWV7433wzETGlXpWRLHGswuObx9e6FQ,6820
 nextmv/cloud/status.py,sha256=blvykRCTCTBkaqH88j4dzdQLhU2v1Ig62-_va98zw20,2789
@@ -31,7 +31,7 @@ nextmv/default_app/requirements.txt,sha256=wRE_HkYYWzCGnYZ2NuatHXul4gCHvU3iUAdsx
 nextmv/default_app/src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nextmv/default_app/src/main.py,sha256=HlO8UwZbZYiAQyrZDSR_T4NBcwP1gIjdTdwkJP_dn8I,847
 nextmv/default_app/src/visuals.py,sha256=WYK_YBnLmYo3TpVev1CpoNCuW5R7hk9QIkeCmvMn1Fs,1014
-nextmv-0.29.4.dev0.dist-info/METADATA,sha256=XsQhLGI72ou40xO8l5pZIP6DYXySXALFa8n5qCLqvtQ,15831
-nextmv-0.29.4.dev0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nextmv-0.29.4.dev0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.29.4.dev0.dist-info/RECORD,,
+nextmv-0.29.5.dev0.dist-info/METADATA,sha256=JOL30ADklPJ0SrmbxPzQvq1J8x15ETOJJU1H5J6amHg,15831
+nextmv-0.29.5.dev0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nextmv-0.29.5.dev0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.29.5.dev0.dist-info/RECORD,,