nextmv 0.23.0__py3-none-any.whl → 0.24.0__py3-none-any.whl

nextmv/cloud/batch_experiment.py

@@ -10,36 +10,68 @@ class BatchExperimentInformation(BaseModel):
     """Information about a batch experiment. This serves as a base for all the
     other batch experiment models."""
 
+    id: str
+    """ID of the batch experiment."""
     name: str
     """Name of the batch experiment."""
-    input_set_id: str
-    """ID of the input set used for the experiment."""
-    instance_ids: list[str]
-    """List of instance IDs used for the experiment."""
+    created_at: datetime
+    """Creation date of the batch experiment."""
+    updated_at: datetime
+    """Last update date of the batch experiment."""
+    status: str
+    """Status of the batch experiment."""
 
     description: Optional[str] = None
     """Description of the batch experiment."""
-    id: Optional[str] = None
-    """ID of the batch experiment."""
+    number_of_requested_runs: Optional[int] = None
+    """Number of runs requested for the batch experiment."""
+    number_of_runs: Optional[int] = None
+    """Number of runs in the batch experiment."""
+    number_of_completed_runs: Optional[int] = None
+    """Number of completed runs in the batch experiment."""
+    type: Optional[str] = None
+    """Type of the batch experiment."""
+    option_sets: Optional[dict[str, dict[str, str]]] = None
+    """Option sets used for the experiment."""
 
 
 class BatchExperiment(BatchExperimentInformation):
     """A batch experiment compares two or more instances by executing all the
     inputs contained in the input set."""
 
-    created_at: datetime
-    """Creation date of the batch experiment."""
-    status: str
-    """Status of the batch experiment."""
-
+    input_set_id: str
+    """ID of the input set used for the experiment."""
+    instance_ids: list[str]
+    """List of instance IDs used for the experiment."""
     grouped_distributional_summaries: Optional[list[dict[str, Any]]] = None
     """Grouped distributional summaries of the batch experiment."""
-    option_sets: Optional[dict[str, dict[str, str]]] = None
-    """Option sets used for the experiment."""
 
 
 class BatchExperimentRun(BaseModel):
-    """A batch experiment run is a single execution of a batch experiment."""
+    """
+    A batch experiment run is a single execution of a batch experiment. It
+    contains information about the experiment, the input used, and the
+    configuration used for the run.
+
+    Attributes
+    ----------
+    option_set : str
+        Option set used for the experiment.
+    input_id : str
+        ID of the input used for the experiment.
+    instance_id : Optional[str]
+        ID of the instance used for the experiment.
+    version_id : Optional[str]
+        ID of the version used for the experiment.
+    input_set_id : Optional[str]
+        ID of the input set used for the experiment.
+    scenario_id : Optional[str]
+        If the batch experiment is a scenario test, this is the ID of that test.
+    repetition : Optional[int]
+        Repetition number of the experiment.
+    run_number : Optional[str]
+        Run number of the experiment.
+    """
 
     option_set: str
     """Option set used for the experiment."""
@@ -50,8 +82,16 @@ class BatchExperimentRun(BaseModel):
     """ID of the instance used for the experiment."""
     version_id: Optional[str] = None
     """ID of the version used for the experiment."""
-
-    def __post_init__(self):
+    input_set_id: Optional[str] = None
+    """ID of the input set used for the experiment."""
+    scenario_id: Optional[str] = None
+    """If the batch experiment is a scenario test, this is the ID of that test."""
+    repetition: Optional[int] = None
+    """Repetition number of the experiment."""
+    run_number: Optional[str] = None
+    """Run number of the experiment."""
+
+    def __post_init_post_parse__(self):
         """Logic to run after the class is initialized."""
 
         if self.instance_id is None and self.version_id is None:
@@ -61,9 +101,5 @@ class BatchExperimentRun(BaseModel):
 class BatchExperimentMetadata(BatchExperimentInformation):
     """Metadata of a batch experiment."""
 
-    status: str
-    """Status of the batch experiment."""
-    created_at: datetime
-    """Creation date of the batch experiment."""
-    number_of_runs: int
-    """Number of runs in the batch experiment."""
+    app_id: str
+    """ID of the application used for the batch experiment."""

nextmv/cloud/client.py

@@ -55,6 +55,8 @@ class Client:
     """Timeout to use for requests to the Nextmv Cloud API."""
     url: str = "https://api.cloud.nextmv.io"
     """URL of the Nextmv Cloud API."""
+    console_url: str = "https://cloud.nextmv.io"
+    """URL of the Nextmv Cloud console."""
 
     def __post_init__(self):
         """Logic to run after the class is initialized."""

nextmv/cloud/input_set.py

@@ -1,8 +1,32 @@
 """This module contains definitions for input sets."""
 
 from datetime import datetime
+from typing import Optional
 
 from nextmv.base_model import BaseModel
+from nextmv.cloud.run import Format
+
+
+class ManagedInput(BaseModel):
+    """An input created for experimenting with an application."""
+
+    id: str
+    """ID of the input."""
+
+    name: Optional[str] = None
+    """Name of the input."""
+    description: Optional[str] = None
+    """Description of the input."""
+    run_id: Optional[str] = None
+    """ID of the run that created the input."""
+    upload_id: Optional[str] = None
+    """ID of the upload that created the input."""
+    format: Optional[Format] = None
+    """Format of the input."""
+    created_at: Optional[datetime] = None
+    """Creation time of the input."""
+    updated_at: Optional[datetime] = None
+    """Last update time of the input."""
 
 
 class InputSet(BaseModel):
@@ -22,3 +46,5 @@ class InputSet(BaseModel):
     """Name of the input set."""
     updated_at: datetime
     """Last update time of the input set."""
+    inputs: list[ManagedInput]
+    """List of inputs in the input set."""

nextmv/cloud/manifest.py

@@ -9,6 +9,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
 
 FILE_NAME = "app.yaml"
 """Name of the app manifest file."""
@@ -89,7 +90,7 @@ class ManifestPythonModel(BaseModel):
     """
     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.Parameter` class. It is used to be able to
+    represents the `nextmv.Option` class. It is used to be able to
     reconstruct an Options object from data when loading a decision model.
     """
 
@@ -113,6 +114,94 @@ class ManifestPython(BaseModel):
     """
 
 
+class ManifestOption(BaseModel):
+    """An option for the decision model that is recorded in the manifest."""
+
+    name: str
+    """The name of the option"""
+    option_type: str = Field(
+        serialization_alias="type",
+        validation_alias=AliasChoices("type", "option_type"),
+    )
+    """The type of the option"""
+
+    default: Optional[Any] = None
+    """The default value of the option"""
+    description: Optional[str] = ""
+    """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"""
+
+    @classmethod
+    def from_option(cls, option: Option) -> "ManifestOption":
+        """
+        Create a `ManifestOption` from an `Option`.
+
+        Parameters
+        ----------
+        option: Option
+            The option to convert.
+
+        Returns
+        -------
+        ManifestOption
+            The converted option.
+        """
+        option_type = option.option_type
+        if option_type is str:
+            option_type = "string"
+        elif option_type is bool:
+            option_type = "boolean"
+        elif option_type is int:
+            option_type = "integer"
+        elif option_type is float:
+            option_type = "float"
+        else:
+            raise ValueError(f"unknown option type: {option_type}")
+
+        return cls(
+            name=option.name,
+            option_type=option_type,
+            default=option.default,
+            description=option.description,
+            required=option.required,
+            choices=option.choices,
+        )
+
+    def to_option(self) -> Option:
+        """
+        Convert the `ManifestOption` to an `Option`.
+
+        Returns
+        -------
+        Option
+            The converted option.
+        """
+
+        option_type_string = self.option_type
+        if option_type_string == "string":
+            option_type = str
+        elif option_type_string == "boolean":
+            option_type = bool
+        elif option_type_string == "integer":
+            option_type = int
+        elif option_type_string == "float":
+            option_type = float
+        else:
+            raise ValueError(f"unknown option type: {option_type_string}")
+
+        return Option(
+            name=self.name,
+            option_type=option_type,
+            default=self.default,
+            description=self.description,
+            required=self.required,
+            choices=self.choices,
+        )
+
+
 class Manifest(BaseModel):
     """
     An application that runs on the Nextmv Platform must contain a file named
@@ -161,6 +250,11 @@ class Manifest(BaseModel):
     Optional. Only for Python apps. Contains further Python-specific
     attributes.
     """
+    options: Optional[list[ManifestOption]] = None
+    """
+    Optional. A list of options for the decision model. An option is a
+    parameter that configures the decision model.
+    """
 
     @classmethod
     def from_yaml(cls, dirpath: str) -> "Manifest":
@@ -169,7 +263,7 @@ class Manifest(BaseModel):
 
         Parameters
         ----------
-        dirpath : str
+        dirpath: str
             Path to the directory containing the app.yaml file.
 
         Returns
@@ -190,7 +284,7 @@ class Manifest(BaseModel):
 
         Parameters
         ----------
-        dirpath : str
+        dirpath: str
             Path to the directory where the app.yaml file will be written.
 
         """
@@ -198,14 +292,35 @@ 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:
+        """
+        Convert the manifest options to a `nextmv.Options` object.
+
+        Returns
+        -------
+        Options
+            The converted options.
+        """
+
+        if self.options is None:
+            raise ValueError("No options found in the manifest")
+
+        options = [option.to_option() for option in self.options]
+
+        return Options(*options)
+
     @classmethod
     def from_model_configuration(cls, model_configuration: ModelConfiguration) -> "Manifest":
         """
-        Create a Python manifest from a Python model configuration.
+        Create a Python manifest from a Python model configuration. Note that
+        the `ModelConfiguration` is almost always used in conjunction with the
+        `nextmv.Model` class. If you are not implementing an instance of
+        `nextmv.Model`, maybe you should use the `from_options` method instead,
+        to initialize the manifest with the options of the model.
 
         Parameters
         ----------
-        model_configuration : ModelConfiguration
+        model_configuration: ModelConfiguration
             The model configuration.
 
         Returns
@@ -222,13 +337,47 @@ class Manifest(BaseModel):
         }
 
         if model_configuration.options is not None:
-            manifest_python_dict["model"]["options"] = model_configuration.options.parameters_dict()
+            manifest_python_dict["model"]["options"] = model_configuration.options.options_dict()
 
         manifest_python = ManifestPython.from_dict(manifest_python_dict)
-
-        return cls(
+        manifest = cls(
             files=["main.py", f"{model_configuration.name}/**"],
             runtime=ManifestRuntime.PYTHON,
             type=ManifestType.PYTHON,
             python=manifest_python,
         )
+
+        if model_configuration.options is not None:
+            manifest.options = [ManifestOption.from_option(opt) for opt in model_configuration.options.options]
+
+        return manifest
+
+    @classmethod
+    def from_options(cls, options: Options) -> "Manifest":
+        """
+        Create a basic Python manifest from `Options`. If you have more files
+        than just a `main.py`, make sure you modify the `.files` attribute of
+        the resulting manifest. This method assumes that requirements are
+        specified in a `requirements.txt` file. You may also specify a
+        different requirements file once you instantiate the manifest.
+
+        Parameters
+        ----------
+        options: Options
+            The options to include in the manifest.
+
+        Returns
+        -------
+        Manifest
+            The manifest with the given options.
+        """
+
+        manifest = cls(
+            files=["main.py"],
+            runtime=ManifestRuntime.PYTHON,
+            type=ManifestType.PYTHON,
+            python=ManifestPython(pip_requirements="requirements.txt"),
+            options=[ManifestOption.from_option(opt) for opt in options.options],
+        )
+
+        return manifest

nextmv/cloud/run.py

@@ -52,6 +52,7 @@ class RunInformation(BaseModel):
     """Name of the run."""
     user_email: str
     """Email of the user who submitted the run."""
+    console_url: str = Field(default="")
 
 
 class ErrorLog(BaseModel):
@@ -128,12 +129,12 @@ class RunTypeConfiguration(BaseModel):
     """ID of the reference for the run type."""
 
 
-class RunQueueing(BaseModel):
-    """Queueing configuration for a run."""
+class RunQueuing(BaseModel):
+    """RunQueuing configuration for a run."""
 
     priority: Optional[int] = None
     """
-    Priority of the run in the queue. 1 is the highest priority, 10 is the
+    Priority of the run in the queue. 1 is the highest priority, 9 is the
     lowest priority.
     """
     disabled: Optional[bool] = None
@@ -145,8 +146,8 @@ class RunQueueing(BaseModel):
     def __post_init_post_parse__(self):
         """Validations done after parsing the model."""
 
-        if self.priority is not None and (self.priority < 1 or self.priority > 10):
-            raise ValueError("Priority must be between 1 and 10.")
+        if self.priority is not None and (self.priority < 1 or self.priority > 9):
+            raise ValueError("Priority must be between 1 and 9.")
 
         if self.disabled is not None and self.disabled not in {True, False}:
             raise ValueError("Disabled must be a boolean value.")
@@ -163,8 +164,8 @@ class RunConfiguration(BaseModel):
     """Run type configuration for the run."""
     secrets_collection_id: Optional[str] = None
     """ID of the secrets collection to use for the run."""
-    queuing: Optional[RunQueueing] = None
-    """Queueing configuration for the run."""
+    queuing: Optional[RunQueuing] = None
+    """Queuing configuration for the run."""
 
 
 class ExternalRunResult(BaseModel):

nextmv/cloud/safe.py

@@ -0,0 +1,83 @@
+"""
+Utilities for generating “safe” IDs and huma-readable names
+"""
+
+import re
+import secrets
+import string
+
+ENTITY_ID_CHAR_COUNT_MAX: int = 40
+INDEX_TAG_CHAR_COUNT: int = 3  # room reserved for “-001”, “-xyz”, etc.
+RE_NON_ALNUM = re.compile(r"[^A-Za-z0-9]+")
+
+
+def kebab_case(value: str) -> str:
+    """Convert arbitrary text to `kebab-case` (lower-case, hyphen-separated)."""
+
+    cleaned = RE_NON_ALNUM.sub(" ", value).strip()
+    return "-".join(word.lower() for word in cleaned.split())
+
+
+def start_case(value: str) -> str:
+    """Convert `kebab-case` (or any hyphen/underscore string) to `Start Case`."""
+
+    cleaned = re.sub(r"[-_]+", " ", value)
+    return " ".join(word.capitalize() for word in cleaned.split())
+
+
+def nanoid(size: int = 8, alphabet: str = string.ascii_lowercase + string.digits) -> str:
+    """Simple nanoid clone using the std-lib `secrets` module."""
+
+    return "".join(secrets.choice(alphabet) for _ in range(size))
+
+
+def name_and_id(prefix: str, entity_id: str) -> tuple[str, str]:
+    """
+    Generate a safe ID and human-readable name from a prefix and user-supplied
+    identifier.
+
+    Parameters
+    ----------
+    prefix : str
+        Prefix to use for the ID.
+    entity_id : str
+        User-supplied identifier. This will be converted to `kebab-case` and
+        truncated to fit within the safe ID length.
+
+    Returns
+    -------
+    tuple[str, str]
+        A tuple containing the human-readable name and the safe ID.
+    """
+
+    if not prefix or not entity_id:
+        return "", ""
+
+    safe_user_defined_id = kebab_case(entity_id)
+    random_slug = nanoid(8)
+
+    # Space available for user text once prefix, random slug and separator "-"
+    # are accounted for
+    safe_id_max = (
+        ENTITY_ID_CHAR_COUNT_MAX
+        - INDEX_TAG_CHAR_COUNT
+        - len(prefix)
+        - (len(random_slug) + 1)  # +1 for the hyphen before the slug
+    )
+
+    safe_id_parts: list[str] = [prefix]
+
+    for word in safe_user_defined_id.split("-"):
+        # Trim individual word if it alone would overflow
+        safe_slug = word[: safe_id_max - 1] if len(word) > safe_id_max else word
+
+        # Will the combined ID (so far) overflow if we add this slug?
+        prospective_len = len("-".join(safe_id_parts + [safe_slug]))
+        if prospective_len >= safe_id_max:
+            break
+        safe_id_parts.append(safe_slug)
+
+    safe_id = "-".join(filter(None, safe_id_parts)) + f"-{random_slug}"
+    safe_name = start_case(safe_id)
+
+    return safe_name, safe_id