nextmv 0.28.4__tar.gz → 0.29.0.dev0__tar.gz

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.28.4
+Version: 0.29.0.dev0
 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
+Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/
 Project-URL: Repository, https://github.com/nextmv-io/nextmv-py
 Author-email: Nextmv <tech@nextmv.io>
 Maintainer-email: Nextmv <tech@nextmv.io>

nextmv-0.29.0.dev0/nextmv/__about__.py

@@ -0,0 +1 @@
+__version__ = "v0.29.0.dev0"

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/nextmv/__init__.py

@@ -3,12 +3,16 @@
 from .__about__ import __version__
 from .base_model import BaseModel as BaseModel
 from .base_model import from_dict as from_dict
+from .input import DataFile as DataFile
 from .input import Input as Input
 from .input import InputFormat as InputFormat
 from .input import InputLoader as InputLoader
 from .input import LocalInputLoader as LocalInputLoader
+from .input import csv_data_file as csv_data_file
+from .input import json_data_file as json_data_file
 from .input import load as load
 from .input import load_local as load_local
+from .input import text_data_file as text_data_file
 from .logger import log as log
 from .logger import redirect_stdout as redirect_stdout
 from .logger import reset_stdout as reset_stdout
@@ -27,9 +31,13 @@ from .output import ResultStatistics as ResultStatistics
 from .output import RunStatistics as RunStatistics
 from .output import Series as Series
 from .output import SeriesData as SeriesData
+from .output import SolutionFile as SolutionFile
 from .output import Statistics as Statistics
 from .output import Visual as Visual
 from .output import VisualSchema as VisualSchema
+from .output import csv_solution_file as csv_solution_file
+from .output import json_solution_file as json_solution_file
+from .output import text_solution_file as text_solution_file
 from .output import write as write
 from .output import write_local as write_local
 

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/nextmv/cloud/application.py

@@ -23,8 +23,11 @@ poll
 """
 
 import json
+import os
 import random
 import shutil
+import tarfile
+import tempfile
 import time
 from collections.abc import Callable
 from dataclasses import dataclass
@@ -1494,6 +1497,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,
     ) -> str:
         """
         Submit an input to start a new run of the application. Returns the
@@ -1503,11 +1507,35 @@ class Application:
         ----------
         input: Union[Input, dict[str, Any], BaseModel, str]
             Input to use for the run. This can be a `nextmv.Input` object,
-            `dict`, `BaseModel` or `str`. If `nextmv.Input` is used, then the
-            input is extracted from the `.data` property. Note that for now,
-            `InputFormat.CSV_ARCHIVE` is not supported as an
-            `input.input_format`. If an input is too large, it will be uploaded
-            with the `upload_large_input` method.
+            `dict`, `BaseModel` or `str`.
+
+            If `nextmv.Input` is used, and the `input_format` is either
+            `nextmv.InputFormat.JSON` or `nextmv.InputFormat.TEXT`, then the
+            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`
+            argument instead. This argument takes precedence over the `input`.
+            If `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`
+            arguments are provided, the `input` is ignored.
+
+            When `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.
+            Make sure that this parameter is specified when working with the
+            following input formats:
+
+            - `nextmv.InputFormat.CSV_ARCHIVE`
+            - `nextmv.InputFormat.MULTI_FILE`
+
+            When working with JSON or text data, use the `input` argument
+            directly.
+
+            In general, if an input is too large, it will be uploaded with the
+            `upload_large_input` method.
         instance_id: Optional[str]
             ID of the instance to use for the run. If not provided, the default
             instance ID associated to the Class (`default_instance_id`) is
@@ -1560,26 +1588,36 @@ class Application:
             not `JSON`. If the final `options` are not of type `dict[str,str]`.
         """
 
+        self.__validate_dir_path_and_configuration(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 not os.path.isdir(dir_path):
+                raise ValueError(f"Path {dir_path} is not a directory.")
+
+            tar_file = self.__package_inputs(dir_path)
+
         input_data = None
         if isinstance(input, BaseModel):
             input_data = input.to_dict()
         elif isinstance(input, dict) or isinstance(input, str):
             input_data = input
         elif isinstance(input, Input):
-            if input.input_format == InputFormat.CSV_ARCHIVE:
-                raise ValueError("csv-archive is not supported")
             input_data = input.data
 
         input_size = 0
         if input_data is not None:
             input_size = get_size(input_data)
 
-        upload_url_required = input_size > _MAX_RUN_SIZE
+        upload_url_required = input_size > _MAX_RUN_SIZE or tar_file != ""
         upload_id_used = upload_id is not None
 
         if not upload_id_used and upload_url_required:
             upload_url = self.upload_url()
-            self.upload_large_input(input=input_data, upload_url=upload_url)
+            self.upload_large_input(input=input_data, upload_url=upload_url, tar_file=tar_file)
             upload_id = upload_url.upload_id
             upload_id_used = True
 
@@ -2797,9 +2835,10 @@ class Application:
 
     def upload_large_input(
         self,
-        input: Union[dict[str, Any], str],
+        input: Optional[Union[dict[str, Any], str]],
         upload_url: UploadURL,
         json_configurations: Optional[dict[str, Any]] = None,
+        tar_file: Optional[str] = None,
     ) -> None:
         """
         Upload large input data to the provided upload URL.
@@ -2810,14 +2849,19 @@ class Application:
 
         Parameters
         ----------
-        input : Union[dict[str, Any], str]
+        input : Optional[Union[dict[str, Any], str]]
             Input data to upload. Can be either a dictionary that will be
             converted to JSON, or a pre-formatted JSON string.
         upload_url : UploadURL
             Upload URL object containing the pre-signed URL to use for uploading.
         json_configurations : Optional[dict[str, Any]], default=None
             Optional configurations for JSON serialization. If provided, these
-            configurations will be used when serializing the data via `json.dumps`.
+            configurations will be used when serializing the data via
+            `json.dumps`.
+        tar_file : Optional[str], default=None
+            If provided, this will be used to upload a tar file instead of
+            a JSON string or dictionary. This is useful for uploading large
+            files that are already packaged as a tarball.
 
         Returns
         -------
@@ -2841,12 +2885,13 @@ class Application:
         >>> app.upload_large_input(input=json_str, upload_url=url)
         """
 
-        if isinstance(input, dict):
+        if input is not None and isinstance(input, dict):
             input = deflated_serialize_json(input, json_configurations=json_configurations)
 
         self.client.upload_to_presigned_url(
             url=upload_url.upload_url,
             data=input,
+            tar_file=tar_file,
         )
 
     def upload_url(self) -> UploadURL:
@@ -3185,6 +3230,73 @@ class Application:
 
         raise ValueError(f"Unknown scenario input type: {scenario.scenario_input.scenario_input_type}")
 
+    def __validate_dir_path_and_configuration(
+        self,
+        dir_path: Optional[str],
+        configuration: Optional[RunConfiguration],
+    ) -> None:
+        """
+        Auxiliary function to validate the directory path and configuration.
+        """
+        if dir_path is None or dir_path == "":
+            return
+
+        if configuration is None:
+            raise ValueError(
+                "If dir_path is provided, a RunConfiguration must also be provided.",
+            )
+
+        if configuration.format is None:
+            raise ValueError(
+                "If dir_path is provided, RunConfiguration.format must also be provided.",
+            )
+
+        if configuration.format.format_input is None:
+            raise ValueError(
+                "If dir_path is provided, RunConfiguration.format.format_input must also be provided.",
+            )
+
+        input_type = configuration.format.format_input.input_type
+        if input_type is None or input_type in (InputFormat.JSON, InputFormat.TEXT):
+            raise ValueError(
+                "If dir_path is provided, RunConfiguration.format.format_input.input_type must be set to a valid type."
+                f"Valid types are: {[InputFormat.CSV_ARCHIVE, InputFormat.MULTI_FILE]}",
+            )
+
+    def __package_inputs(self, dir_path: str) -> str:
+        """
+        This is an auxiliary function for packaging the inputs found in the
+        provided `dir_path`. All the files found in the directory are tarred and
+        g-zipped. This function returns the tar file path that contains the
+        packaged inputs.
+        """
+
+        # Create a temporary directory for the output
+        output_dir = tempfile.mkdtemp(prefix="nextmv-inputs-out-")
+
+        # Define the output tar file name and path
+        tar_filename = "inputs.tar.gz"
+        tar_file_path = os.path.join(output_dir, tar_filename)
+
+        # Create the tar.gz file
+        with tarfile.open(tar_file_path, "w:gz") as tar:
+            for root, _, files in os.walk(dir_path):
+                for file in files:
+                    if file == tar_filename:
+                        continue
+
+                    file_path = os.path.join(root, file)
+
+                    # Skip directories, only process files
+                    if os.path.isdir(file_path):
+                        continue
+
+                    # Create relative path for the archive
+                    arcname = os.path.relpath(file_path, start=dir_path)
+                    tar.add(file_path, arcname=arcname)
+
+        return tar_file_path
+
 
 def poll(  # noqa: C901
     polling_options: PollingOptions,

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/nextmv/cloud/client.py

@@ -323,7 +323,11 @@ class Client:
         return response
 
     def upload_to_presigned_url(
-        self, data: Union[dict[str, Any], str], url: str, json_configurations: Optional[dict[str, Any]] = None
+        self,
+        data: Optional[Union[dict[str, Any], str]],
+        url: str,
+        json_configurations: Optional[dict[str, Any]] = None,
+        tar_file: Optional[str] = None,
     ) -> None:
         """
         Uploads data to a presigned URL.
@@ -333,7 +337,7 @@ class Client:
 
         Parameters
         ----------
-        data : dict[str, Any] or str
+        data : Union[dict[str, Any], str], optional
             The data to upload. If a dictionary is provided, it will be
             JSON-serialized. If a string is provided, it will be uploaded
             as is.
@@ -344,6 +348,11 @@ class Client:
             customization of the Python `json.dumps` function, such as
             specifying `indent` for pretty printing or `default` for custom
             serialization functions.
+        tar_file : str, optional
+            If provided, this will be used to upload a tar file instead of
+            a JSON string or dictionary. This is useful for uploading large
+            files that are already packaged as a tarball. If this is provided,
+            `data` is expected to be `None`.
 
         Raises
         ------
@@ -361,12 +370,13 @@ class Client:
         """
 
         upload_data: Optional[str] = None
-        if isinstance(data, dict):
-            upload_data = deflated_serialize_json(data, json_configurations=json_configurations)
-        elif isinstance(data, str):
-            upload_data = data
-        else:
-            raise ValueError("data must be a dictionary or a string")
+        if data is not None:
+            if isinstance(data, dict):
+                upload_data = deflated_serialize_json(data, json_configurations=json_configurations)
+            elif isinstance(data, str):
+                upload_data = data
+            else:
+                raise ValueError("data must be a dictionary or a string")
 
         session = requests.Session()
         retries = Retry(
@@ -379,12 +389,21 @@ class Client:
         )
         adapter = HTTPAdapter(max_retries=retries)
         session.mount("https://", adapter)
+
         kwargs: dict[str, Any] = {
             "url": url,
             "timeout": self.timeout,
-            "data": upload_data,
         }
 
+        if upload_data is not None:
+            kwargs["data"] = upload_data
+        elif tar_file is not None:
+            if not os.path.exists(tar_file):
+                raise ValueError(f"tar_file {tar_file} does not exist")
+            kwargs["data"] = open(tar_file, "rb")
+        else:
+            raise ValueError("either data or tar_file must be provided")
+
         response = session.put(**kwargs)
 
         try:

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/nextmv/cloud/manifest.py

@@ -16,10 +16,14 @@ ManifestPythonModel
     Class for model-specific instructions for Python apps.
 ManifestPython
     Class for Python-specific instructions in the manifest.
+ManifestOptionUI
+    Class for UI attributes of options in the manifest.
 ManifestOption
     Class representing an option for the decision model in the manifest.
 ManifestOptions
     Class containing a list of options for the decision model.
+ManifestValidation
+    Class for validation rules for options in the manifest.
 ManifestConfiguration
     Class for configuration settings for the decision model.
 Manifest
@@ -40,7 +44,7 @@ from pydantic import AliasChoices, Field
 
 from nextmv.base_model import BaseModel
 from nextmv.model import _REQUIREMENTS_FILE, ModelConfiguration
-from nextmv.options import Option, Options
+from nextmv.options import Option, Options, OptionsEnforcement
 
 MANIFEST_FILE_NAME = "app.yaml"
 """Name of the app manifest file.
@@ -318,6 +322,43 @@ class ManifestPython(BaseModel):
     from the app bundle.
     """
 
+class ManifestOptionUI(BaseModel):
+    """
+    UI attributes for an option in the manifest.
+
+    You can import the `ManifestOptionUI` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ManifestOptionUI
+    ```
+
+    Parameters
+    ----------
+    control_type : str, optional
+        The type of control to use for the option in the Nextmv Cloud UI. This is
+        useful for defining how the option should be presented in the Nextmv
+        Cloud UI. Current control types include "input", "select", "slider", and
+        "toggle". This attribute is not used in the local `Options` class, but
+        it is used in the Nextmv Cloud UI to define the type of control to use for
+        the option. This will be validated by the Nextmv Cloud, and availability
+        is based on options_type.
+    hidden_from : list[str], optional
+        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"]`.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import ManifestOptionUI
+    >>> ui_config = ManifestOptionUI(control_type="input")
+    >>> ui_config.control_type
+    'input'
+    """
+
+    control_type: Optional[str] = None
+    """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."""
 
 class ManifestOption(BaseModel):
     """
@@ -349,6 +390,12 @@ class ManifestOption(BaseModel):
         length of a string or the maximum value of an integer. These
         additional attributes will be shown in the help message of the
         `Options`.
+    ui : Optional[ManifestOptionUI], default=None
+        Optional UI attributes for the option. This is a dictionary that can
+        contain additional information about how the option should be displayed
+        in the Nextmv Cloud UI. This is not used in the local `Options` class,
+        but it is used in the Nextmv Cloud UI to define how the option should be
+        presented.
 
     Examples
     --------
@@ -378,12 +425,10 @@ class ManifestOption(BaseModel):
     required: bool = False
     """Whether the option is required or not"""
     additional_attributes: Optional[dict[str, Any]] = None
-    """Optional additional attributes for the option.
+    """Optional additional attributes for the option."""
+    ui: Optional[ManifestOptionUI] = None
+    """Optional UI 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":
@@ -435,6 +480,10 @@ class ManifestOption(BaseModel):
             description=option.description,
             required=option.required,
             additional_attributes=option.additional_attributes,
+            ui=ManifestOptionUI(
+                control_type=option.control_type,
+                hidden_from=option.hidden_from,
+            ) if option.control_type or option.hidden_from else None,
         )
 
     def to_option(self) -> Option:
@@ -481,8 +530,44 @@ class ManifestOption(BaseModel):
             description=self.description,
             required=self.required,
             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,
         )
 
+class ManifestValidation(BaseModel):
+    """
+    Validation rules for options in the manifest.
+
+    You can import the `ManifestValidation` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ManifestValidation
+    ```
+
+    Parameters
+    ----------
+    enforce : str, default="none"
+        The enforcement level for the validation rules. This can be set to
+        "none" or "all". If set to "none", no validation will be performed
+        on the options prior to creating a run. If set to "all", all validation
+        rules will be enforced on the options, and runs will not be created
+        if any of the rules of the options are violated.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import ManifestValidation
+    >>> validation = ManifestValidation(enforce="all")
+    >>> validation.enforce
+    'all'
+    """
+
+    enforce: str = "none"
+    """The enforcement level for the validation rules.
+    This can be set to "none" or "all". If set to "none", no validation will
+    be performed on the options prior to creating a run. If set to "all", all
+    validation rules will be enforced on the options, and runs will not be
+    created if any of the rules of the options are violated.
+    """
 
 class ManifestOptions(BaseModel):
     """
@@ -501,12 +586,16 @@ class ManifestOptions(BaseModel):
     items : Optional[list[ManifestOption]], default=None
         The actual list of options for the decision model. An option
         is a parameter that configures the decision model.
+    validation: Optional[ManifestValidation], default=None
+        Optional validation rules for all options.
+
 
     Examples
     --------
     >>> from nextmv.cloud import ManifestOptions, ManifestOption
     >>> options_config = ManifestOptions(
     ...     strict=True,
+    ...     validation=ManifestValidation(enforce="all"),
     ...     items=[
     ...         ManifestOption(name="timeout", option_type="int", default=60),
     ...         ManifestOption(name="vehicle_capacity", option_type="float", default=100.0)
@@ -520,12 +609,48 @@ class ManifestOptions(BaseModel):
 
     strict: Optional[bool] = False
     """If strict is set to `True`, only the listed options will be allowed."""
+    validation: Optional[ManifestValidation] = None
+    """Optional validation rules for all options."""
     items: Optional[list[ManifestOption]] = None
     """The actual list of options for the decision model.
 
     An option is a parameter that configures the decision model.
     """
 
+    @classmethod
+    def from_options(cls, options: Options, validation: OptionsEnforcement = None) -> "ManifestOptions":
+        """
+        Create a `ManifestOptions` from a `nextmv.Options`.
+
+        Parameters
+        ----------
+        options : nextmv.options.Options
+            The options to convert.
+        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`.
+
+        Returns
+        -------
+        ManifestOptions
+            The converted options.
+
+        Examples
+        --------
+        >>> from nextmv.options import Options, Option
+        >>> from nextmv.cloud import ManifestOptions
+        >>> sdk_options = Options(Option("max_vehicles", int, 5))
+        >>> manifest_options = ManifestOptions.from_options(sdk_options)
+        >>> manifest_options.items[0].name
+        'max_vehicles'
+        """
+
+        items = [ManifestOption.from_option(option) for option in options.options]
+        return cls(
+            strict=validation.strict if validation else False,
+            validation=ManifestValidation(enforce="all" if validation and validation.validation_enforce else "none"),
+            items=items
+        )
 
 class ManifestConfiguration(BaseModel):
     """
@@ -852,16 +977,16 @@ class Manifest(BaseModel):
 
         if model_configuration.options is not None:
             manifest.configuration = ManifestConfiguration(
-                options=ManifestOptions(
-                    strict=False,
-                    items=[ManifestOption.from_option(opt) for opt in model_configuration.options.options],
+                options=ManifestOptions.from_options(
+                    options=model_configuration.options,
+                    validation=model_configuration.options_enforcement,
                 ),
             )
 
         return manifest
 
     @classmethod
-    def from_options(cls, options: Options) -> "Manifest":
+    def from_options(cls, options: Options, validation: OptionsEnforcement = None) -> "Manifest":
         """
         Create a basic Python manifest from `nextmv.options.Options`.
 
@@ -882,6 +1007,9 @@ class Manifest(BaseModel):
         ----------
         options : nextmv.options.Options
             The options to include in the manifest.
+        validation : nextmv.options.OptionsEnforcement default=None
+            The validation rules for the options. This is used to set the
+            `validation` attribute of the `ManifestOptions`.
 
         Returns
         -------
@@ -913,11 +1041,11 @@ class Manifest(BaseModel):
             type=ManifestType.PYTHON,
             python=ManifestPython(pip_requirements="requirements.txt"),
             configuration=ManifestConfiguration(
-                options=ManifestOptions(
-                    strict=False,
-                    items=[ManifestOption.from_option(opt) for opt in options.options],
+                options= ManifestOptions.from_options(
+                    options=options,
+                    validation=validation
                 ),
-            ),
+            )
         )
 
         return manifest

{nextmv-0.28.4 → nextmv-0.29.0.dev0}/nextmv/cloud/package.py

@@ -28,7 +28,7 @@ def _package(
     model_configuration: Optional[ModelConfiguration] = None,
     verbose: bool = False,
 ) -> tuple[str, str]:
-    """Package the app into a tarball.."""
+    """Package the app into a tarball."""
 
     with tempfile.TemporaryDirectory(prefix="nextmv-temp-") as temp_dir:
         if manifest.type == ManifestType.PYTHON: