nextmv 0.26.3__py3-none-any.whl → 0.27.0__py3-none-any.whl

nextmv/__about__.py

@@ -1 +1 @@
-__version__ = "v0.26.3"
+__version__ = "v0.27.0"

nextmv/__entrypoint__.py

@@ -1,5 +1,5 @@
 """
-When working in a notebook environment, we don’t really create a `main.py` file
+When working in a notebook environment, we don't really create a `main.py` file
 with the main entrypoint of the program. Because the logic is mostly encoded
 inside the `Model` class, we need to create a `main.py` file that we can run in
 Nextmv Cloud. This file is used as that entrypoint. It is not intended for a
@@ -19,9 +19,7 @@ def main() -> None:
     manifest = cloud.Manifest.from_yaml(".")
 
     # Load the options from the manifest.
-    options = None
-    if manifest.options is not None:
-        options = manifest.extract_options()
+    options = manifest.extract_options()
 
     # Load the model.
     loaded_model = load_model(
@@ -29,7 +27,7 @@ def main() -> None:
         suppress_warnings=True,
     )
 
-    # Load the input and solve the model by using mlflow’s inference API.
+    # Load the input and solve the model by using mlflow's inference API.
     input = nextmv.load(options=options)
     output = loaded_model.predict(input)
 

nextmv/cloud/application.py

@@ -881,7 +881,7 @@ class Application:
         instance_id: Optional[str]
             ID of the instance to use for the input set. This is used to
             filter the runs associated with the input set. If not provided,
-            the application’s `default_instance_id` is used.
+            the application's `default_instance_id` is used.
         maximum_runs: Optional[int]
             Maximum number of runs to use for the input set. This is used to
             filter the runs associated with the input set. If not provided,
@@ -997,7 +997,7 @@ class Application:
         description: Optional[str] = None,
         upload_id: Optional[str] = None,
         run_id: Optional[str] = None,
-        format: Optional[Union[Format, dict[str, any]]] = None,
+        format: Optional[Union[Format, dict[str, Any]]] = None,
     ) -> ManagedInput:
         """
         Create a new managed input. There are two methods for creating a
@@ -1076,9 +1076,9 @@ class Application:
         description: Optional[str] = None,
         upload_id: Optional[str] = None,
         options: Optional[Union[Options, dict[str, str]]] = None,
-        configuration: Optional[Union[RunConfiguration, dict[str, any]]] = None,
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
         batch_experiment_id: Optional[str] = None,
-        external_result: Optional[Union[ExternalRunResult, dict[str, any]]] = None,
+        external_result: Optional[Union[ExternalRunResult, dict[str, Any]]] = None,
     ) -> str:
         """
         Submit an input to start a new run of the application. Returns the
@@ -1112,7 +1112,7 @@ class Application:
             used, the options are extracted from the `.to_cloud_dict()` method.
             Note that specifying `options` overrides the `input.options` (if
             the `input` is of type `nextmv.Input`).
-        configuration: Optional[Union[RunConfiguration, dict[str, any]]]
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]]
             Configuration to use for the run. This can be a
             `cloud.RunConfiguration` object or a dict. If the object is used,
             then the `.to_dict()` method is applied to extract the
@@ -1120,7 +1120,7 @@ class Application:
         batch_experiment_id: Optional[str]
             ID of a batch experiment to associate the run with. This is used
             when the run is part of a batch experiment.
-        external_result: Optional[Union[ExternalRunResult, dict[str, any]]]
+        external_result: Optional[Union[ExternalRunResult, dict[str, Any]]]
             External result to use for the run. This can be a
             `cloud.ExternalRunResult` object or a dict. If the object is used,
             then the `.to_dict()` method is applied to extract the
@@ -1228,9 +1228,9 @@ class Application:
         upload_id: Optional[str] = None,
         run_options: Optional[Union[Options, dict[str, str]]] = None,
         polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
-        configuration: Optional[Union[RunConfiguration, dict[str, any]]] = None,
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
         batch_experiment_id: Optional[str] = None,
-        external_result: Optional[Union[ExternalRunResult, dict[str, any]]] = None,
+        external_result: Optional[Union[ExternalRunResult, dict[str, Any]]] = None,
     ) -> RunResult:
         """
         Submit an input to start a new run of the application and poll for the
@@ -1271,7 +1271,7 @@ class Application:
             convenience method that combines the `new_run` and
             `run_result_with_polling` methods, applying polling logic to check
             when the run succeeded.
-        configuration: Optional[Union[RunConfiguration, dict[str, any]]]
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]]
             Configuration to use for the run. This can be a
             `cloud.RunConfiguration` object or a dict. If the object is used,
             then the `.to_dict()` method is applied to extract the
@@ -1279,7 +1279,7 @@ class Application:
         batch_experiment_id: Optional[str]
             ID of a batch experiment to associate the run with. This is used
             when the run is part of a batch experiment.
-        external_result: Optional[Union[ExternalRunResult, dict[str, any]]]
+        external_result: Optional[Union[ExternalRunResult, dict[str, Any]]]
             External result to use for the run. This can be a
             `cloud.ExternalRunResult` object or a dict. If the object is used,
             then the `.to_dict()` method is applied to extract the
@@ -1555,7 +1555,7 @@ class Application:
         exception will be raised.
 
         There are two ways to push an app to Nextmv Cloud:
-        1. Specifying `app_dir`, which is the path to an app’s root directory.
+        1. Specifying `app_dir`, which is the path to an app's root directory.
         This acts as an external strategy, where the app is composed of files
         in a directory and those apps are packaged and pushed to Nextmv Cloud.
         2. Specifying a `model` and `model_configuration`. This acts as an
@@ -1566,7 +1566,7 @@ class Application:
         Examples
         -------
 
-        1. Push an app using an external strategy, i.e., specifying the app’s
+        1. Push an app using an external strategy, i.e., specifying the app's
         directory:
         ```python
         import os
@@ -1640,7 +1640,7 @@ class Application:
         manifest : Optional[Manifest], optional
             The manifest for the app, by default None.
         app_dir : Optional[str], optional
-            The path to the app’s directory, by default None.
+            The path to the app's directory, by default None.
         verbose : bool, optional
             Whether to print verbose output, by default False.
         """
@@ -1793,7 +1793,7 @@ class Application:
             requests.HTTPError: If the response status code is not 2xx.
         """
 
-        def polling_func() -> tuple[any, bool]:
+        def polling_func() -> tuple[Any, bool]:
             run_information = self.run_metadata(run_id=run_id)
             if run_information.metadata.status_v2 in {
                 StatusV2.succeeded,
@@ -2327,6 +2327,10 @@ class Application:
                 "runtime": manifest.runtime,
             },
         }
+
+        if manifest.configuration is not None and manifest.configuration.options is not None:
+            activation_request["requirements"]["options"] = manifest.configuration.options.to_dict()
+
         response = self.client.request(
             method="PUT",
             endpoint=endpoint,
@@ -2402,11 +2406,11 @@ class Application:
         raise ValueError(f"Unknown scenario input type: {scenario.scenario_input.scenario_input_type}")
 
 
-def poll(polling_options: PollingOptions, polling_func: Callable[[], tuple[any, bool]]) -> any:
+def poll(polling_options: PollingOptions, polling_func: Callable[[], tuple[Any, bool]]) -> Any:
     """
     Auxiliary function for polling.
 
-    The `polling_func` is a callable that must return a `tuple[any, bool]`
+    The `polling_func` is a callable that must return a `tuple[Any, bool]`
     where the first element is the result of the polling and the second
     element is a boolean indicating if the polling was successful or should be
     retried.
@@ -2424,7 +2428,7 @@ def poll(polling_options: PollingOptions, polling_func: Callable[[], tuple[any,
 
     Returns
     -------
-    any
+    Any
         Result of the polling function.
     """
 

nextmv/cloud/manifest.py

@@ -16,8 +16,19 @@ FILE_NAME = "app.yaml"
 
 
 class ManifestType(str, Enum):
-    """Type of application in the manifest, based on the programming
-    language."""
+    """
+    Type of application in the manifest, based on the programming
+    language.
+
+    Attributes
+    ----------
+    PYTHON: str
+        Python format
+    GO: str
+        Go format
+    JAVA: str
+        Java format
+    """
 
     PYTHON = "python"
     """Python format"""
@@ -28,7 +39,23 @@ class ManifestType(str, Enum):
 
 
 class ManifestRuntime(str, Enum):
-    """Runtime (environment) where the app will be run on Nextmv Cloud."""
+    """
+    Runtime (environment) where the app will be run on Nextmv Cloud.
+
+    Attributes
+    ----------
+    DEFAULT: str
+        This runtime is used to run compiled applications such as Go binaries.
+    PYTHON: str
+        This runtime is used as the basis for all other Python runtimes and
+        Python applications.
+    JAVA: str
+        This runtime is used to run Java applications.
+    PYOMO: str
+        This runtime provisions Python packages to run Pyomo applications.
+    HEXALY: str
+        This runtime provisions Python packages to run Hexaly applications.
+    """
 
     DEFAULT = "ghcr.io/nextmv-io/runtime/default:latest"
     """This runtime is used to run compiled applications such as Go binaries."""
@@ -49,7 +76,20 @@ class ManifestRuntime(str, Enum):
 
 
 class ManifestBuild(BaseModel):
-    """Build-specific attributes."""
+    """
+    Build-specific attributes.
+
+    Attributes
+    ----------
+    command: Optional[str]
+        The command to run to build the app. This command will be executed
+        without a shell, i.e., directly. The command must exit with a status of
+        0 to continue the push process of the app to Nextmv Cloud. This command
+        is executed prior to the pre-push command.
+    environment: Optional[dict[str, Any]]
+        Environment variables to set when running the build command given as
+        key-value pairs.
+    """
 
     command: Optional[str] = None
     """
@@ -82,7 +122,19 @@ class ManifestBuild(BaseModel):
 
 
 class ManifestPythonModel(BaseModel):
-    """Model-specific instructions for a Python app."""
+    """
+    Model-specific instructions for a Python app.
+
+    Attributes
+    ----------
+    name: str
+        The name of the decision model.
+    options: Optional[list[dict[str, Any]]]
+        Options for the decision model. This is a data representation of the
+        `nextmv.Options` class. It consists of a list of dicts. Each dict
+        represents the `nextmv.Option` class. It is used to be able to
+        reconstruct an Options object from data when loading a decision model.
+    """
 
     name: str
     """The name of the decision model."""
@@ -96,7 +148,18 @@ class ManifestPythonModel(BaseModel):
 
 
 class ManifestPython(BaseModel):
-    """Python-specific instructions."""
+    """
+    Python-specific instructions.
+
+    Attributes
+    ----------
+    pip_requirements: Optional[str]
+        Path to a requirements.txt file containing (additional) Python
+        dependencies that will be bundled with the app.
+    model: Optional[ManifestPythonModel]
+        Information about an encoded decision model as handlded via mlflow. This
+        information is used to load the decision model from the app bundle.
+    """
 
     pip_requirements: Optional[str] = Field(
         serialization_alias="pip-requirements",
@@ -115,7 +178,23 @@ class ManifestPython(BaseModel):
 
 
 class ManifestOption(BaseModel):
-    """An option for the decision model that is recorded in the manifest."""
+    """
+    An option for the decision model that is recorded in the manifest.
+
+    Attributes
+    ----------
+    name: str
+        The name of the option.
+    option_type: str
+        The type of the option. This is a string representation of the
+        `nextmv.Option` class.
+    default: Optional[Any]
+        The default value of the option.
+    description: Optional[str]
+        The description of the option.
+    required: bool
+        Whether the option is required or not.
+    """
 
     name: str
     """The name of the option"""
@@ -131,8 +210,13 @@ class ManifestOption(BaseModel):
     """The description of the option"""
     required: bool = False
     """Whether the option is required or not"""
-    choices: Optional[list[Any]] = None
-    """The choices for the option"""
+    additional_attributes: Optional[dict[str, Any]] = None
+    """
+    Optional additional attributes for the option. The Nextmv Cloud may
+    perform validation on these attributes. For example, the maximum length of
+    a string or the maximum value of an integer. These additional attributes
+    will be shown in the help message of the `Options`.
+    """
 
     @classmethod
     def from_option(cls, option: Option) -> "ManifestOption":
@@ -153,9 +237,9 @@ class ManifestOption(BaseModel):
         if option_type is str:
             option_type = "string"
         elif option_type is bool:
-            option_type = "boolean"
+            option_type = "bool"
         elif option_type is int:
-            option_type = "integer"
+            option_type = "int"
         elif option_type is float:
             option_type = "float"
         else:
@@ -167,7 +251,7 @@ class ManifestOption(BaseModel):
             default=option.default,
             description=option.description,
             required=option.required,
-            choices=option.choices,
+            additional_attributes=option.additional_attributes,
         )
 
     def to_option(self) -> Option:
@@ -183,9 +267,9 @@ class ManifestOption(BaseModel):
         option_type_string = self.option_type
         if option_type_string == "string":
             option_type = str
-        elif option_type_string == "boolean":
+        elif option_type_string == "bool":
             option_type = bool
-        elif option_type_string == "integer":
+        elif option_type_string == "int":
             option_type = int
         elif option_type_string == "float":
             option_type = float
@@ -198,10 +282,47 @@ class ManifestOption(BaseModel):
             default=self.default,
             description=self.description,
             required=self.required,
-            choices=self.choices,
+            additional_attributes=self.additional_attributes,
         )
 
 
+class ManifestOptions(BaseModel):
+    """
+    Options for the decision model.
+
+    Attributes
+    ----------
+    strict: bool
+        If strict is set to `True`, only the listed options will be allowed.
+    items: list[ManifestOption]
+        Optional. The actual list of options for the decision model. An option
+        is a parameter that configures the decision model.
+    """
+
+    strict: Optional[bool] = False
+    """If strict is set to `True`, only the listed options will be allowed."""
+    items: Optional[list[ManifestOption]] = None
+    """
+    Optional. The actual list of options for the decision model. An option is a
+    parameter that configures the decision model.
+    """
+
+
+class ManifestConfiguration(BaseModel):
+    """
+    Configuration for the decision model.
+
+    Attributes
+    ----------
+    options: ManifestOptions
+        Optional. The actual list of options for the decision model. An option
+        is a parameter that configures the decision model.
+    """
+
+    options: ManifestOptions
+    """Options for the decision model."""
+
+
 class Manifest(BaseModel):
     """
     An application that runs on the Nextmv Platform must contain a file named
@@ -210,6 +331,34 @@ class Manifest(BaseModel):
 
     This class represents the app manifest and allows you to load it from a
     file or create it programmatically.
+
+    Attributes
+    ----------
+    files: list[str]
+        Mandatory. The files to include (or exclude) in the app.
+    runtime: ManifestRuntime
+        Mandatory. The runtime to use for the app, it provides the environment
+        in which the app runs.
+    type: ManifestType
+        Mandatory. Type of application, based on the programming language.
+    build: Optional[ManifestBuild]
+        Optional. Build-specific attributes. The build.command to run to build
+        the app. This command will be executed without a shell, i.e., directly.
+        The command must exit with a status of 0 to continue the push process of
+        the app to Nextmv Cloud. This command is executed prior to the pre-push
+        command. The build.environment is used to set environment variables when
+        running the build command given as key-value pairs.
+    pre_push: Optional[str]
+        Optional. A command to run before the app is pushed to the Nextmv Cloud.
+        This command can be used to compile a binary, run tests or similar tasks.
+        One difference with what is specified under build, is that the command
+        will be executed via
+    python: Optional[ManifestPython]
+        Optional. Only for Python apps. Contains further Python-specific
+        attributes.
+    configuration: Optional[ManifestConfiguration]
+        Optional. A list of options for the decision model. An option is a
+        parameter that configures the decision model.
     """
 
     files: list[str]
@@ -250,7 +399,7 @@ class Manifest(BaseModel):
     Optional. Only for Python apps. Contains further Python-specific
     attributes.
     """
-    options: Optional[list[ManifestOption]] = None
+    configuration: Optional[ManifestConfiguration] = None
     """
     Optional. A list of options for the decision model. An option is a
     parameter that configures the decision model.
@@ -292,20 +441,23 @@ class Manifest(BaseModel):
         with open(os.path.join(dirpath, FILE_NAME), "w") as file:
             yaml.dump(self.to_dict(), file)
 
-    def extract_options(self) -> Options:
+    def extract_options(self) -> Optional[Options]:
         """
-        Convert the manifest options to a `nextmv.Options` object.
+        Convert the manifest options to a `nextmv.Options` object. If the
+        manifest does not have valid options defined in
+        `.configuration.options.items`, this method simply returns a `None`.
 
         Returns
         -------
-        Options
-            The converted options.
+        Optional[Options]
+            The options extracted from the manifest. If no options are found,
+            `None` is returned.
         """
 
-        if self.options is None:
-            raise ValueError("No options found in the manifest")
+        if self.configuration is None or self.configuration.options is None or self.configuration.options.items is None:
+            return None
 
-        options = [option.to_option() for option in self.options]
+        options = [option.to_option() for option in self.configuration.options.items]
 
         return Options(*options)
 
@@ -348,7 +500,12 @@ class Manifest(BaseModel):
         )
 
         if model_configuration.options is not None:
-            manifest.options = [ManifestOption.from_option(opt) for opt in model_configuration.options.options]
+            manifest.configuration = ManifestConfiguration(
+                options=ManifestOptions(
+                    strict=False,
+                    items=[ManifestOption.from_option(opt) for opt in model_configuration.options.options],
+                ),
+            )
 
         return manifest
 
@@ -377,7 +534,12 @@ class Manifest(BaseModel):
             runtime=ManifestRuntime.PYTHON,
             type=ManifestType.PYTHON,
             python=ManifestPython(pip_requirements="requirements.txt"),
-            options=[ManifestOption.from_option(opt) for opt in options.options],
+            configuration=ManifestConfiguration(
+                options=ManifestOptions(
+                    strict=False,
+                    items=[ManifestOption.from_option(opt) for opt in options.options],
+                ),
+            ),
         )
 
         return manifest

nextmv/cloud/run.py

@@ -248,11 +248,11 @@ class TrackedRun:
 
     Attributes
     ----------
-    input : Union[Input, dict[str, any], str]
+    input : Union[Input, dict[str, Any], str]
         The input of the run being tracked. Please note that if the input
         format is JSON, then the input data must be JSON serializable. This
         field is required.
-    output : Union[Output, dict[str, any], str]
+    output : Union[Output, dict[str, Any], str]
         The output of the run being tracked. Please note that if the output
         format is JSON, then the output data must be JSON serializable. This
         field is required.
@@ -270,9 +270,9 @@ class TrackedRun:
         the log. This field is optional.
     """
 
-    input: Union[Input, dict[str, any], str]
+    input: Union[Input, dict[str, Any], str]
     """The input of the run being tracked."""
-    output: Union[Output, dict[str, any], str]
+    output: Union[Output, dict[str, Any], str]
     """The output of the run being tracked. Only JSON output_format is supported."""
     status: TrackedRunStatus
     """The status of the run being tracked"""
@@ -303,7 +303,7 @@ class TrackedRun:
             try:
                 _ = json.dumps(self.input)
             except (TypeError, OverflowError) as e:
-                raise ValueError("Input is dict[str, any] but it is not JSON serializable") from e
+                raise ValueError("Input is dict[str, Any] but it is not JSON serializable") from e
 
         if isinstance(self.output, Output):
             if self.output.output_format != OutputFormat.JSON:
@@ -312,7 +312,7 @@ class TrackedRun:
             try:
                 _ = json.dumps(self.output)
             except (TypeError, OverflowError) as e:
-                raise ValueError("Output is dict[str, any] but it is not JSON serializable") from e
+                raise ValueError("Output is dict[str, Any] but it is not JSON serializable") from e
 
     def logs_text(self) -> str:
         """

nextmv/cloud/scenario.py

@@ -211,7 +211,7 @@ def _option_sets(scenarios: list[Scenario]) -> dict[str, dict[str, dict[str, str
 def _scenarios_by_id(scenarios: list[Scenario]) -> dict[str, Scenario]:
     """
     This function maps a scenario to its ID. A scenario ID is created if it
-    wasn’t defined. This function also checks that there are no duplicate
+    wasn't defined. This function also checks that there are no duplicate
     scenario IDs.
     """
 

nextmv/input.py

@@ -92,7 +92,7 @@ class Input:
         new_options = copy.deepcopy(init_options)
         self.options = new_options
 
-    def to_dict(self) -> dict[str, any]:
+    def to_dict(self) -> dict[str, Any]:
         """
         Convert the input to a dictionary.
 
@@ -102,7 +102,7 @@ class Input:
 
         Returns
         -------
-        dict[str, any]
+        dict[str, Any]
             The input as a dictionary.
         """
 

nextmv/model.py

@@ -47,7 +47,7 @@ warnings.showwarning = custom_showwarning
 # the model requires and that we install and bundle with the app.
 _REQUIREMENTS_FILE = "model_requirements.txt"
 
-# When working in a notebook environment, we don’t really create a `main.py`
+# When working in a notebook environment, we don't really create a `main.py`
 # file with the main entrypoint of the program. Because the logic is mostly
 # encoded inside the `Model` class, we need to create a `main.py` file that we
 # can run in Nextmv Cloud. This file is used as that entrypoint.
@@ -148,7 +148,7 @@ class Model:
             saved and loaded.
         """
 
-        # mlflow is a big package. We don’t want to make it a dependency of
+        # mlflow is a big package. We don't want to make it a dependency of
         # `nextmv` because it is not always needed. We only need it if we are
         # working with the "app from model" logic, which involves working with
         # this `Model` class.
@@ -180,7 +180,7 @@ class Model:
                 params: Optional[dict[str, Any]] = None,
             ) -> Any:
                 """
-                The predict method allows us to work with mlflow’s [python_function]
+                The predict method allows us to work with mlflow's [python_function]
                 model flavor. Warning: This method should not be used or overridden
                 directly. Instead, you should implement the `solve` method.
 

nextmv/options.py

@@ -66,7 +66,7 @@ class Parameter:
     def __post_init__(self):
         deprecated(
             name="Parameter",
-            reason="`Parameter` is deprecated, use `Option` instead.",
+            reason="`Parameter` is deprecated, use `Option` instead",
         )
 
     @classmethod
@@ -164,6 +164,11 @@ class Option:
         argument, an environment variable or a default value.
     choices : list[Optional[Any]], optional
         Limits values to a specific set of choices.
+    additional_attributes : dict[str, Any], optional
+        Optional additional attributes for the option. The Nextmv Cloud may
+        perform validation on these attributes. For example, the maximum length
+        of a string or the maximum value of an integer. These additional
+        attributes will be shown in the help message of the `Options`.
     """
 
     name: str
@@ -189,6 +194,13 @@ class Option:
     """
     choices: Optional[list[Any]] = None
     """Limits values to a specific set of choices."""
+    additional_attributes: Optional[dict[str, Any]] = None
+    """
+    Optional additional attributes for the option. The Nextmv Cloud may
+    perform validation on these attributes. For example, the maximum length of
+    a string or the maximum value of an integer. These additional attributes
+    will be shown in the help message of the `Options`.
+    """
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "Option":
@@ -209,13 +221,14 @@ class Option:
         option_type_string = data["option_type"]
         option_type = getattr(builtins, option_type_string.split("'")[1])
 
-        return Option(
+        return cls(
             name=data["name"],
             option_type=option_type,
             default=data.get("default"),
             description=data.get("description"),
             required=data.get("required", False),
             choices=data.get("choices"),
+            additional_attributes=data.get("additional_attributes"),
         )
 
     def to_dict(self) -> dict[str, Any]:
@@ -235,6 +248,7 @@ class Option:
             "description": self.description,
             "required": self.required,
             "choices": self.choices,
+            "additional_attributes": self.additional_attributes,
         }
 
 
@@ -657,7 +671,7 @@ class Options:
             options_by_field_name[option.name.replace("-", "_")] = option
 
         # The ipkyernel uses a `-f` argument by default that it passes to the
-        # execution. We don’t want to ignore this argument because we get an
+        # execution. We don't want to ignore this argument because we get an
         # error. Fix source: https://stackoverflow.com/a/56349168
         parser.add_argument(
             "-f",
@@ -729,6 +743,9 @@ class Options:
 
         description += f" (type: {self._option_type(option).__name__})"
 
+        if isinstance(option, Option) and option.additional_attributes is not None:
+            description += f" (additional attributes: {option.additional_attributes})"
+
         if option.description is not None and option.description != "":
             description += f": {option.description}"
 

nextmv/output.py

@@ -249,10 +249,10 @@ class Output:
     serialized to the write location.
 
     The most important part of the output is the solution, which represents the
-    result of the decision problem. The solution’s type must match the
+    result of the decision problem. The solution's type must match the
     `output_format`:
 
-    - `OutputFormat.JSON`: the data must be `dict[str, Any]`.
+    - `OutputFormat.JSON`: the data must be `dict[str, Any]`, or `Any`.
     - `OutputFormat.CSV_ARCHIVE`: the data must be `dict[str, list[dict[str,
       Any]]]`. The keys represent the file names where the data should be
       written. The values are lists of dictionaries, where each dictionary
@@ -263,20 +263,73 @@ class Output:
     dictionary, we recommend using the `Statistics` class to ensure that the
     data is correctly formatted.
 
-    Parameters
+    The assets are used to keep track of different downloadable information that
+    is part of the output. The assets can be of type `Asset` or a simple
+    dictionary, but we recommend using the `Asset` class to ensure that the data is
+    correctly formatted.
+
+    Attributes
     ----------
-    options : Options, optional
-        Options that the `Input` were created with.
-    output_format : OutputFormat, optional
+    options : Optional[Union[Options, dict[str, Any]]]
+        Options that the `Output` was created with. These options can be of type
+        `Options` or a simple dictionary. If the options are of type `Options`,
+        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 options are not
+        provided, an empty dictionary will be used. If the options are of type
+        `dict`, then the dictionary should have the following structure:
+        ```
+        {
+            "duration": "30",
+            "threads": 4,
+        }
+        ```
+    output_format : Optional[OutputFormat]
         Format of the output data. Default is `OutputFormat.JSON`.
-    solution : Union[dict[str, Any], dict[str, list[dict[str, Any]]], optional
-        The solution to the decision problem.
-    statistics : Union[Statistics, dict[str, Any], optional
-        Statistics of the solution.
+    solution : Optional[Union[dict[str, Any], dict[str, list[dict[str, Any]]]]
+        The solution to the decision problem. The type must match the
+        `output_format`:
+        - `OutputFormat.JSON`: the data must be `dict[str, Any]`.
+        - `OutputFormat.CSV_ARCHIVE`: the data must be `dict[str,
+          list[dict[str, Any]]]`. The keys represent the file names where the
+          data should be written. The values are lists of dictionaries, where
+          each dictionary represents a row in the CSV file.
+    statistics : Optional[Union[Statistics, dict[str, Any]]]
+        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.
+    csv_configurations : Optional[dict[str, Any]]
+        Optional configuration for writing CSV files, to be used when the
+        `output_format` is `OutputFormat.CSV_ARCHIVE`. These configurations are
+        passed as kwargs to the `DictWriter` class from the `csv` module.
+    json_configurations : Optional[dict[str, Any]]
+        Optional configuration for writing JSON files, to be used when the
+        `output_format` is `OutputFormat.JSON`. These configurations are passed
+        as kwargs to the `json.dumps` function.
+    assets : Optional[list[Union[Asset, dict[str, Any]]]]
+        Optional list of assets to be included in the output. These assets can
+        be of type `Asset` or a simple dictionary. If the assets are of type
+        `Asset`, 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
+        assets are not provided, an empty list will be used.
     """
 
-    options: Optional[Options] = None
-    """Options that the `Input` were created with."""
+    options: Optional[Union[Options, dict[str, Any]]] = None
+    """
+    Options that the `Output` was created with. These options can be of type
+    `Options` or a simple dictionary. If the options are of type `Options`,
+    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 options are not
+    provided, an empty dictionary will be used. If the options are of type
+    `dict`, then the dictionary should have the following structure:
+    ```
+    {
+        "duration": "30",
+        "threads": 4,
+    }
+    ```
+    """
     output_format: Optional[OutputFormat] = OutputFormat.JSON
     """Format of the output data. Default is `OutputFormat.JSON`."""
     solution: Optional[
@@ -287,17 +340,33 @@ class Output:
     ] = None
     """The solution to the decision problem."""
     statistics: Optional[Union[Statistics, dict[str, Any]]] = None
-    """Statistics of the solution."""
+    """
+    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.
+    """
     csv_configurations: Optional[dict[str, Any]] = None
-    """Optional configuration for writing CSV files, to be used when the
-    `output_format` is OutputFormat.CSV_ARCHIVE. These configurations are
-    passed as kwargs to the `DictWriter` class from the `csv` module."""
+    """
+    Optional configuration for writing CSV files, to be used when the
+    `output_format` is `OutputFormat.CSV_ARCHIVE`. These configurations are
+    passed as kwargs to the `DictWriter` class from the `csv` module.
+    """
     json_configurations: Optional[dict[str, Any]] = None
-    """Optional configuration for writing JSON files, to be used when the
-    `output_format` is OutputFormat.JSON. These configurations are passed as
-    kwargs to the `json.dumps` function."""
-    assets: Optional[list[Asset]] = None
-    """Optional list of assets to be included in the output."""
+    """
+    Optional configuration for writing JSON files, to be used when the
+    `output_format` is `OutputFormat.JSON`. These configurations are passed as
+    kwargs to the `json.dumps` function.
+    """
+    assets: Optional[list[Union[Asset, dict[str, Any]]]] = None
+    """
+    Optional list of assets to be included in the output. These assets can be of
+    type `Asset` or a simple dictionary. If the assets are of type `Asset`, 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 assets are not provided, an
+    empty list will be used.
+    """
 
     def __post_init__(self):
         """Check that the solution matches the format given to initialize the
@@ -327,26 +396,76 @@ class Output:
                 "output_format OutputFormat.CSV_ARCHIVE, supported type is `dict`"
             )
 
-    def to_dict(self) -> dict[str, any]:
+    def to_dict(self) -> dict[str, Any]:  # noqa: C901
         """
         Convert the `Output` object to a dictionary.
 
         Returns
         -------
-        dict[str, any]
+        dict[str, Any]
             The dictionary representation of the `Output` object.
         """
 
+        # Options need to end up as a dict, so we achieve that based on the
+        # type of options that were used to create the class.
+        if self.options is None:
+            options = {}
+        elif isinstance(self.options, Options):
+            options = self.options.to_dict()
+        elif isinstance(self.options, dict):
+            options = self.options
+        else:
+            raise TypeError(f"unsupported options type: {type(self.options)}, supported types are `Options` or `dict`")
+
+        # 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 = {}
+        elif isinstance(self.statistics, Statistics):
+            statistics = self.statistics.to_dict()
+        elif isinstance(self.statistics, dict):
+            statistics = self.statistics
+        else:
+            raise TypeError(
+                f"unsupported statistics type: {type(self.statistics)}, supported types are `Statistics` or `dict`"
+            )
+
+        # 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 = []
+        if isinstance(self.assets, list):
+            for ix, asset in enumerate(self.assets):
+                if isinstance(asset, Asset):
+                    assets.append(asset.to_dict())
+                elif isinstance(asset, dict):
+                    assets.append(asset)
+                else:
+                    raise TypeError(
+                        f"unsupported asset {ix}, type: {type(asset)}; supported types are `Asset` or `dict`"
+                    )
+        elif self.assets is not None:
+            raise TypeError(f"unsupported assets type: {type(self.assets)}, supported types are `list`")
+
         output_dict = {
-            "options": self.options.to_dict() if self.options is not None else {},
+            "options": options,
             "solution": self.solution if self.solution is not None else {},
-            "statistics": self.statistics.to_dict() if self.statistics is not None else {},
-            "assets": [asset.to_dict() for asset in self.assets] if self.assets is not None else [],
+            "statistics": statistics,
+            "assets": assets,
         }
 
-        if self.output_format == OutputFormat.CSV_ARCHIVE:
+        # Add the auxiliary configurations to the output dictionary if they are
+        # defined and not empty.
+        if (
+            self.output_format == OutputFormat.CSV_ARCHIVE
+            and self.csv_configurations is not None
+            and self.csv_configurations != {}
+        ):
             output_dict["csv_configurations"] = self.csv_configurations
-        elif self.output_format == OutputFormat.JSON:
+        elif (
+            self.output_format == OutputFormat.JSON
+            and self.json_configurations is not None
+            and self.json_configurations != {}
+        ):
             output_dict["json_configurations"] = self.json_configurations
 
         return output_dict
@@ -371,24 +490,9 @@ class LocalOutputWriter(OutputWriter):
 
     def _write_json(
         output: Union[Output, dict[str, Any], BaseModel],
-        options: dict[str, Any],
-        statistics: dict[str, Any],
-        assets: list[dict[str, Any]],
+        output_dict: dict[str, Any],
         path: Optional[str] = None,
     ) -> None:
-        if isinstance(output, dict):
-            final_output = output
-        elif isinstance(output, BaseModel):
-            final_output = output.to_dict()
-        else:
-            solution = output.solution if output.solution is not None else {}
-            final_output = {
-                "options": options,
-                "solution": solution,
-                "statistics": statistics,
-                "assets": assets,
-            }
-
         json_configurations = {}
         if hasattr(output, "json_configurations") and output.json_configurations is not None:
             json_configurations = output.json_configurations
@@ -402,7 +506,7 @@ class LocalOutputWriter(OutputWriter):
             del json_configurations["default"]
 
         serialized = json.dumps(
-            final_output,
+            output_dict,
             indent=indent,
             default=custom_serial,
             **json_configurations,
@@ -416,10 +520,8 @@ class LocalOutputWriter(OutputWriter):
             file.write(serialized + "\n")
 
     def _write_archive(
-        output: Output,
-        options: dict[str, Any],
-        statistics: dict[str, Any],
-        assets: list[dict[str, Any]],
+        output: Union[Output, dict[str, Any], BaseModel],
+        output_dict: dict[str, Any],
         path: Optional[str] = None,
     ) -> None:
         dir_path = "output"
@@ -434,9 +536,9 @@ class LocalOutputWriter(OutputWriter):
 
         serialized = json.dumps(
             {
-                "options": options,
-                "statistics": statistics,
-                "assets": assets,
+                "options": output_dict.get("options", {}),
+                "statistics": output_dict.get("statistics", {}),
+                "assets": output_dict.get("assets", []),
             },
             indent=2,
         )
@@ -525,88 +627,24 @@ class LocalOutputWriter(OutputWriter):
                 f"unsupported output type: {type(output)}, supported types are `Output`, `dict`, `BaseModel`"
             )
 
-        statistics = self._extract_statistics(output)
-        options = self._extract_options(output)
-        assets = self._extract_assets(output)
+        output_dict = {}
+        if isinstance(output, Output):
+            output_dict = output.to_dict()
+        elif isinstance(output, BaseModel):
+            output_dict = output.to_dict()
+        elif isinstance(output, dict):
+            output_dict = output
+        else:
+            raise TypeError(
+                f"unsupported output type: {type(output)}, supported types are `Output`, `dict`, `BaseModel`"
+            )
 
         self.FILE_WRITERS[output_format](
             output=output,
-            options=options,
-            statistics=statistics,
-            assets=assets,
+            output_dict=output_dict,
             path=path,
         )
 
-    @staticmethod
-    def _extract_statistics(output: Union[Output, dict[str, Any]]) -> dict[str, Any]:
-        """Extract JSON-serializable statistics."""
-
-        statistics = {}
-
-        if not isinstance(output, Output):
-            return statistics
-
-        stats = output.statistics
-
-        if stats is None:
-            return statistics
-
-        if isinstance(stats, Statistics):
-            statistics = stats.to_dict()
-        elif isinstance(stats, dict):
-            statistics = stats
-        else:
-            raise TypeError(f"unsupported statistics type: {type(stats)}, supported types are `Statistics` or `dict`")
-
-        return statistics
-
-    @staticmethod
-    def _extract_options(output: Union[Output, dict[str, Any]]) -> dict[str, Any]:
-        """Extract JSON-serializable options."""
-
-        options = {}
-
-        if not isinstance(output, Output):
-            return options
-
-        opt = output.options
-
-        if opt is None:
-            return options
-
-        if isinstance(opt, Options):
-            options = opt.to_dict()
-        elif isinstance(opt, dict):
-            options = opt
-        else:
-            raise TypeError(f"unsupported options type: {type(opt)}, supported types are `Options` or `dict`")
-
-        return options
-
-    @staticmethod
-    def _extract_assets(output: Union[Output, dict[str, Any]]) -> list[dict[str, Any]]:
-        """Extract JSON-serializable assets."""
-
-        assets = []
-
-        if not isinstance(output, Output):
-            return assets
-
-        assts = output.assets
-
-        if assts is None:
-            return assets
-
-        for ix, asset in enumerate(assts):
-            if isinstance(asset, Asset):
-                assets.append(asset.to_dict())
-            elif isinstance(asset, dict):
-                assets.append(asset)
-            else:
-                raise TypeError(f"unsupported asset {ix}, type: {type(asset)}; supported types are `Asset` or `dict`")
-
-        return assets
-
 
 def write_local(
     output: Union[Output, dict[str, Any]],

{nextmv-0.26.3.dist-info → nextmv-0.27.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.26.3
+Version: 0.27.0
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://www.nextmv.io/docs/python-sdks/nextmv/installation

{nextmv-0.26.3.dist-info → nextmv-0.27.0.dist-info}/RECORD

@@ -1,30 +1,30 @@
-nextmv/__about__.py,sha256=gt8p7ptfCJk0tI0Kji01wC2fj-JYIvRQm_MEOwdRLY8,24
-nextmv/__entrypoint__.py,sha256=5K058PICm5sx4sNMqx56auMh9yWgdIESVLzfvyIXdjs,1158
+nextmv/__about__.py,sha256=dPbfXnVUa1GzXrrlZ_hOg9cbB0hO_UUubb09KvnQt_g,24
+nextmv/__entrypoint__.py,sha256=dA0iwwHtrq6Z9w9FxmxKLoBGLyhe7jWtUAU-Y3PEgHg,1094
 nextmv/__init__.py,sha256=QN5e_BFkIdBkR8DiGr9T06N6mXtowT84eRUJj3_Vfrg,1459
 nextmv/base_model.py,sha256=mdaBe-epNK1cFgP4TxbOtn3So4pCi1vMTOrIBkCBp7A,1050
 nextmv/deprecated.py,sha256=ctE39pmJEfoicR-w0EdT7FPtd0cWmP3GKth-FsNn_Ks,406
-nextmv/input.py,sha256=tppXHiJM_EzR9Z1yJPc37joBvgC0RmiAFo0Ab1X5nPA,15480
+nextmv/input.py,sha256=H3Al-VhsiTuSdYL6ld7O7AP-MGHnr8uXq-WENIC76jU,15480
 nextmv/logger.py,sha256=Jo_AmYJ02WqXmsz9XTTOXZ9uenVHrPanMMqhBogxGCw,1075
-nextmv/model.py,sha256=rwBdgmKSEp1DPv43zF0azj3QnbHO6O6wKs0PIGvVS40,9861
-nextmv/options.py,sha256=IPqAIUjoKMWmoPx_e5zDcnxu7S2HVxw-SLjjUduVvZM,25302
-nextmv/output.py,sha256=nOdPJ7yBcEteUsSD6BXYwXcyV4ROKbATQXHh43Sl-6s,23221
+nextmv/model.py,sha256=hE0BgeGfIsnR7H624VVX0Zys5utUtrH_xK1sERT0GTQ,9855
+nextmv/options.py,sha256=5NjZbllCPNKzCBfyx-8XXnsz0wkph0WFfngJMAcYjtQ,26314
+nextmv/output.py,sha256=qvFdEoNs-bhT4xjkcLS_6aHN1iU1dCILEhAf1Tafzak,26719
 nextmv/cloud/__init__.py,sha256=EEKJdSMMjW2yc9GwTpz-cmpgtu-Qs7p09k6NXIQPV0U,3726
 nextmv/cloud/acceptance_test.py,sha256=NtqGhj-UYibxGBbU2kfjr-lYcngojb_5VMvK2WZwibI,6620
 nextmv/cloud/account.py,sha256=mZUGzV-uMGBA5BC_FPtsiCMFuz5jxEZ3O1BbELZIm18,1841
-nextmv/cloud/application.py,sha256=0mTMSIze3uXMlWY7K7OYicMVox0IaC0PapLx41iVP2c,84098
+nextmv/cloud/application.py,sha256=Go9DD1eWC7zMV0s76hld0VNS5QN7GWhu0Kk2Ci_wgFU,84287
 nextmv/cloud/batch_experiment.py,sha256=Ngm1XDvvAMaU9VYU5JFNxXFnt8xjE_34H5W54kO9V5c,3768
 nextmv/cloud/client.py,sha256=JUE3vD767_FFICl1vov5Mxmircci03TBL3KmT1BOZY4,9096
 nextmv/cloud/input_set.py,sha256=HTLA2acJridZbBCAVJNom8ldNo2Rfy40YQ8Coyz3bdo,1482
 nextmv/cloud/instance.py,sha256=UfyfZXfL1ugCGAB6zwZJIAi8qxI1JCUGsluwaGdjfN4,1223
-nextmv/cloud/manifest.py,sha256=lB3rwFmIKNAncaA00DelT4tDkMkIUCWEY4QJKJsx_-U,12116
+nextmv/cloud/manifest.py,sha256=dwATuTRFJehXj2WdF3ZvEGH0gE96mK1zikkol38lMgk,18005
 nextmv/cloud/package.py,sha256=Y3RethLiXXW7Y6_QBJDJdd7mFNaYaSBMyasIeGLav8o,12287
-nextmv/cloud/run.py,sha256=BpaH5L-Vfb2NFs1YIJfi1jYEOqitiAa-5BkdTtLBue0,10906
+nextmv/cloud/run.py,sha256=0UUTmDzwI47styBeLR0MIhn4yXmOHNFt3YfbGAZVRB8,10906
 nextmv/cloud/safe.py,sha256=IUQUOlx4ulIIyP2-Fx3-gNBm9nyWOgZgaOAlRrzqaZE,2515
-nextmv/cloud/scenario.py,sha256=9gbdnQuvmerPUBCcJ-5QbLCwgbsIfBwKXE8c5359S8E,8120
+nextmv/cloud/scenario.py,sha256=Z2Kkaar45IJgkFiVCCpLqe6O3Y3AxqWVl2BGfUp3I_8,8118
 nextmv/cloud/secrets.py,sha256=kqlN4ceww_L4kVTrAU8BZykRzXINO3zhMT_BLYea6tk,1764
 nextmv/cloud/status.py,sha256=C-ax8cLw0jPeh7CPsJkCa0s4ImRyFI4NDJJxI0_1sr4,602
 nextmv/cloud/version.py,sha256=sjVRNRtohHA97j6IuyM33_DSSsXYkZPusYgpb6hlcrc,1244
-nextmv-0.26.3.dist-info/METADATA,sha256=u_djskL-Aa1rqrooo1H3qY8_8qlwSfEYoSMBKn7RwNc,14557
-nextmv-0.26.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nextmv-0.26.3.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.26.3.dist-info/RECORD,,
+nextmv-0.27.0.dist-info/METADATA,sha256=e5ip9F8XzZ5tqjBOpGo41GIfZm2HeuZX1JxuktkpDSY,14557
+nextmv-0.27.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nextmv-0.27.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.27.0.dist-info/RECORD,,