nextmv 0.26.3__tar.gz → 0.27.0__tar.gz

{nextmv-0.26.3 → nextmv-0.27.0}/PKG-INFO

@@ -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.27.0/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v0.27.0"

{nextmv-0.26.3 → nextmv-0.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-0.26.3 → nextmv-0.27.0}/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-0.26.3 → nextmv-0.27.0}/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-0.26.3 → nextmv-0.27.0}/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-0.26.3 → nextmv-0.27.0}/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-0.26.3 → nextmv-0.27.0}/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-0.26.3 → nextmv-0.27.0}/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.