nextmv 0.29.5.dev1__py3-none-any.whl → 0.31.0__py3-none-any.whl

nextmv/cloud/application.py

@@ -24,13 +24,9 @@ poll
 
 import json
 import os
-import random
 import shutil
 import tarfile
 import tempfile
-import time
-import uuid
-from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Optional, Union
@@ -40,19 +36,30 @@ import requests
 from nextmv._serialization import deflated_serialize_json
 from nextmv.base_model import BaseModel
 from nextmv.cloud import package
-from nextmv.cloud.acceptance_test import AcceptanceTest, ExperimentStatus, Metric
+from nextmv.cloud.acceptance_test import AcceptanceTest, Metric
 from nextmv.cloud.batch_experiment import (
     BatchExperiment,
     BatchExperimentInformation,
     BatchExperimentMetadata,
     BatchExperimentRun,
+    ExperimentStatus,
     to_runs,
 )
 from nextmv.cloud.client import Client, get_size
 from nextmv.cloud.input_set import InputSet, ManagedInput
 from nextmv.cloud.instance import Instance, InstanceConfiguration
-from nextmv.cloud.manifest import Manifest
-from nextmv.cloud.run import (
+from nextmv.cloud.scenario import Scenario, ScenarioInputType, _option_sets, _scenarios_by_id
+from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
+from nextmv.cloud.url import DownloadURL, UploadURL
+from nextmv.cloud.version import Version
+from nextmv.input import Input, InputFormat
+from nextmv.logger import log
+from nextmv.manifest import Manifest
+from nextmv.model import Model, ModelConfiguration
+from nextmv.options import Options
+from nextmv.output import Output, OutputFormat
+from nextmv.polling import DEFAULT_POLLING_OPTIONS, PollingOptions, poll
+from nextmv.run import (
     ExternalRunResult,
     Format,
     FormatInput,
@@ -63,16 +70,8 @@ from nextmv.cloud.run import (
     RunResult,
     TrackedRun,
 )
-from nextmv.cloud.safe import _name_and_id, _safe_id
-from nextmv.cloud.scenario import Scenario, ScenarioInputType, _option_sets, _scenarios_by_id
-from nextmv.cloud.secrets import Secret, SecretsCollection, SecretsCollectionSummary
-from nextmv.cloud.status import StatusV2
-from nextmv.cloud.version import Version
-from nextmv.input import Input, InputFormat
-from nextmv.logger import log
-from nextmv.model import Model, ModelConfiguration
-from nextmv.options import Options
-from nextmv.output import Output, OutputFormat
+from nextmv.safe import safe_id, safe_name_and_id
+from nextmv.status import StatusV2
 
 # Maximum size of the run input/output in bytes. This constant defines the
 # maximum allowed size for run inputs and outputs. When the size exceeds this
@@ -81,180 +80,6 @@ from nextmv.output import Output, OutputFormat
 _MAX_RUN_SIZE: int = 5 * 1024 * 1024
 
 
-class DownloadURL(BaseModel):
-    """
-    Result of getting a download URL.
-
-    You can import the `DownloadURL` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import DownloadURL
-    ```
-
-    This class represents a download URL that can be used to fetch content
-    from Nextmv Cloud, typically used for downloading large run results.
-
-    Attributes
-    ----------
-    url : str
-        URL to use for downloading the file.
-
-    Examples
-    --------
-    >>> download_url = DownloadURL(url="https://example.com/download")
-    >>> response = requests.get(download_url.url)
-    """
-
-    url: str
-    """URL to use for downloading the file."""
-
-
-@dataclass
-class PollingOptions:
-    """
-    Options to use when polling for a run result.
-
-    You can import the `PollingOptions` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import PollingOptions
-    ```
-
-    The Cloud API will be polled for the result. The polling stops if:
-
-    * The maximum number of polls (tries) are exhausted. This is specified by
-      the `max_tries` parameter.
-    * The maximum duration of the polling strategy is reached. This is
-      specified by the `max_duration` parameter.
-
-    Before conducting the first poll, the `initial_delay` is used to sleep.
-    After each poll, a sleep duration is calculated using the following
-    strategy, based on exponential backoff with jitter:
-
-    ```
-    sleep_duration = min(`max_delay`, `delay` + `backoff` * 2 ** i + Uniform(0, `jitter`))
-    ```
-
-    Where:
-    * i is the retry (poll) number.
-    * Uniform is the uniform distribution.
-
-    Note that the sleep duration is capped by the `max_delay` parameter.
-
-    Parameters
-    ----------
-    backoff : float, default=0.9
-        Exponential backoff factor, in seconds, to use between polls.
-    delay : float, default=0.1
-        Base delay to use between polls, in seconds.
-    initial_delay : float, default=1.0
-        Initial delay to use before starting the polling strategy, in seconds.
-    max_delay : float, default=20.0
-        Maximum delay to use between polls, in seconds.
-    max_duration : float, default=300.0
-        Maximum duration of the polling strategy, in seconds.
-    max_tries : int, default=100
-        Maximum number of tries to use.
-    jitter : float, default=1.0
-        Jitter to use for the polling strategy. A uniform distribution is sampled
-        between 0 and this number. The resulting random number is added to the
-        delay for each poll, adding a random noise. Set this to 0 to avoid using
-        random jitter.
-    verbose : bool, default=False
-        Whether to log the polling strategy. This is useful for debugging.
-    stop : callable, default=None
-        Function to call to check if the polling should stop. This is useful for
-        stopping the polling based on external conditions. The function should
-        return True to stop the polling and False to continue. The function does
-        not receive any arguments. The function is called before each poll.
-
-    Examples
-    --------
-    >>> from nextmv.cloud import PollingOptions
-    >>> # Create polling options with custom settings
-    >>> polling_options = PollingOptions(
-    ...     max_tries=50,
-    ...     max_duration=600,
-    ...     verbose=True
-    ... )
-    """
-
-    backoff: float = 0.9
-    """
-    Exponential backoff factor, in seconds, to use between polls.
-    """
-    delay: float = 0.1
-    """Base delay to use between polls, in seconds."""
-    initial_delay: float = 1
-    """
-    Initial delay to use before starting the polling strategy, in seconds.
-    """
-    max_delay: float = 20
-    """Maximum delay to use between polls, in seconds."""
-    max_duration: float = -1
-    """
-    Maximum duration of the polling strategy, in seconds. A negative value means no limit.
-    """
-    max_tries: int = -1
-    """Maximum number of tries to use. A negative value means no limit."""
-    jitter: float = 1
-    """
-    Jitter to use for the polling strategy. A uniform distribution is sampled
-    between 0 and this number. The resulting random number is added to the
-    delay for each poll, adding a random noise. Set this to 0 to avoid using
-    random jitter.
-    """
-    verbose: bool = False
-    """Whether to log the polling strategy. This is useful for debugging."""
-    stop: Optional[Callable[[], bool]] = None
-    """
-    Function to call to check if the polling should stop. This is useful for
-    stopping the polling based on external conditions. The function should
-    return True to stop the polling and False to continue. The function does
-    not receive any arguments. The function is called before each poll.
-    """
-
-
-# Default polling options to use when polling for a run result. This constant
-# provides the default values for `PollingOptions` used across the module.
-# Using these defaults is recommended for most use cases unless specific timing
-# needs are required.
-_DEFAULT_POLLING_OPTIONS: PollingOptions = PollingOptions()
-
-
-class UploadURL(BaseModel):
-    """
-    Result of getting an upload URL.
-
-    You can import the `UploadURL` class directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import UploadURL
-    ```
-
-    This class represents an upload URL that can be used to send data to
-    Nextmv Cloud, typically used for uploading large inputs for runs.
-
-    Attributes
-    ----------
-    upload_id : str
-        ID of the upload, used to reference the uploaded content.
-    upload_url : str
-        URL to use for uploading the file.
-
-    Examples
-    --------
-    >>> upload_url = UploadURL(upload_id="123", upload_url="https://example.com/upload")
-    >>> with open("large_input.json", "rb") as f:
-    ...     requests.put(upload_url.upload_url, data=f)
-    """
-
-    upload_id: str
-    """ID of the upload."""
-    upload_url: str
-    """URL to use for uploading the file."""
-
-
 @dataclass
 class Application:
     """
@@ -304,15 +129,6 @@ class Application:
     experiments_endpoint: str = "{base}/experiments"
     """Base endpoint for the experiments in the application."""
 
-    # Local experience parameters.
-    src: Optional[str] = None
-    """
-    Source of the application, if initialized locally. This is the path
-    to the application's source code.
-    """
-    description: Optional[str] = None
-    """Description of the application."""
-
     def __post_init__(self):
         """Initialize the endpoint and experiments_endpoint attributes.
 
@@ -322,92 +138,6 @@ class Application:
         self.endpoint = self.endpoint.format(id=self.id)
         self.experiments_endpoint = self.experiments_endpoint.format(base=self.endpoint)
 
-    @classmethod
-    def initialize(
-        cls,
-        name: str,
-        id: Optional[str] = None,
-        description: Optional[str] = None,
-        destination: Optional[str] = None,
-        client: Optional[Client] = None,
-    ) -> "Application":
-        """
-        Initialize a Nextmv application, locally.
-
-        This method will create a new application in the local file system. The
-        application is a folder with the name given by `name`, under the
-        location given by `destination`. If the `destination` parameter is not
-        specified, the current working directory is used as default. This
-        method will scaffold the application with the necessary files and
-        directories to have an opinionated structure for your decision model.
-        Once the application is initialized, you are encouraged to complete it
-        with the decision model itself, so that the application can be run,
-        locally or remotely.
-
-        This method differs from the `Application.new` method in that it
-        creates the application locally rather than in the Cloud.
-
-        Although not required, you are encouraged to specify the `client`
-        parameter, so that the application can be pushed and synced remotely,
-        with the Nextmv Cloud. If you don't specify the `client`, and intend to
-        interact with the Nextmv Cloud, you will encounter an error. Make sure
-        you set the `client` parameter on the `Application` instance after
-        initialization, if you don't provide it here.
-
-        Use the `destination` parameter to specify where you want the app to be
-        initialized, using the current working directory by default.
-
-        Parameters
-        ----------
-        name : str
-            Name of the application.
-        id : str, optional
-            ID of the application. Will be generated if not provided.
-        description : str, optional
-            Description of the application.
-        destination : str, optional
-            Destination directory where the application will be initialized. If
-            not provided, the current working directory will be used.
-        client : Client, optional
-            Client to use for interacting with the Nextmv Cloud API.
-
-        Returns
-        -------
-        Application
-            The initialized application instance.
-        """
-
-        destination_dir = os.getcwd() if destination is None else destination
-        app_id = id if id is not None else str(uuid.uuid4())
-
-        # Create the new directory with the given name.
-        src = os.path.join(destination_dir, name)
-        os.makedirs(src, exist_ok=True)
-
-        # Get the path to the initial app structure template.
-        current_file_dir = os.path.dirname(os.path.abspath(__file__))
-        initial_app_structure_path = os.path.join(current_file_dir, "..", "default_app")
-        initial_app_structure_path = os.path.normpath(initial_app_structure_path)
-
-        # Copy everything from initial_app_structure to the new directory.
-        if os.path.exists(initial_app_structure_path):
-            for item in os.listdir(initial_app_structure_path):
-                source_path = os.path.join(initial_app_structure_path, item)
-                dest_path = os.path.join(src, item)
-
-                if os.path.isdir(source_path):
-                    shutil.copytree(source_path, dest_path, dirs_exist_ok=True)
-                    continue
-
-                shutil.copy2(source_path, dest_path)
-
-        return cls(
-            id=app_id,
-            client=client,
-            src=src,
-            description=description,
-        )
-
     @classmethod
     def new(
         cls,
@@ -506,6 +236,57 @@ class Application:
 
         return AcceptanceTest.from_dict(response.json())
 
+    def acceptance_test_with_polling(
+        self,
+        acceptance_test_id: str,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
+    ) -> AcceptanceTest:
+        """
+        Retrieve details of an acceptance test using polling.
+
+        Retrieves the result of an acceptance test. This method polls for the
+        result until the test finishes executing or the polling strategy is
+        exhausted.
+
+        Parameters
+        ----------
+        acceptance_test_id : str
+            ID of the acceptance test to retrieve.
+
+        Returns
+        -------
+        AcceptanceTest
+            The requested acceptance test details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> test = app.acceptance_test_with_polling("test-123")
+        >>> print(test.name)
+        'My Test'
+        """
+
+        def polling_func() -> tuple[Any, bool]:
+            acceptance_test_result = self.acceptance_test(acceptance_test_id=acceptance_test_id)
+            if acceptance_test_result.status in {
+                ExperimentStatus.COMPLETED,
+                ExperimentStatus.FAILED,
+                ExperimentStatus.DRAFT,
+                ExperimentStatus.CANCELED,
+                ExperimentStatus.DELETE_FAILED,
+            }:
+                return acceptance_test_result, True
+
+            return None, False
+
+        acceptance_test = poll(polling_options=polling_options, polling_func=polling_func)
+
+        return self.acceptance_test(acceptance_test_id=acceptance_test.id)
+
     def batch_experiment(self, batch_id: str) -> BatchExperiment:
         """
         Get a batch experiment.
@@ -539,6 +320,90 @@ class Application:
 
         return BatchExperiment.from_dict(response.json())
 
+    def batch_experiment_metadata(self, batch_id: str) -> BatchExperimentMetadata:
+        """
+        Get metadata for a batch experiment.
+
+        Parameters
+        ----------
+        batch_id : str
+            ID of the batch experiment.
+
+        Returns
+        -------
+        BatchExperimentMetadata
+            The requested batch experiment metadata.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> metadata = app.batch_experiment_metadata("batch-123")
+        >>> print(metadata.name)
+        'My Batch Experiment'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/batch/{batch_id}/metadata",
+        )
+
+        return BatchExperimentMetadata.from_dict(response.json())
+
+    def batch_experiment_with_polling(
+        self,
+        batch_id: str,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
+    ) -> BatchExperiment:
+        """
+        Get a batch experiment with polling.
+
+        Retrieves the result of an experiment. This method polls for the result
+        until the experiment finishes executing or the polling strategy is
+        exhausted.
+
+        Parameters
+        ----------
+        batch_id : str
+            ID of the batch experiment.
+
+        Returns
+        -------
+        BatchExperiment
+            The requested batch experiment details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> batch_exp = app.batch_experiment_with_polling("batch-123")
+        >>> print(batch_exp.name)
+        'My Batch Experiment'
+        """
+
+        def polling_func() -> tuple[Any, bool]:
+            batch_metadata = self.batch_experiment_metadata(batch_id=batch_id)
+            if batch_metadata.status in {
+                ExperimentStatus.COMPLETED,
+                ExperimentStatus.FAILED,
+                ExperimentStatus.DRAFT,
+                ExperimentStatus.CANCELED,
+                ExperimentStatus.DELETE_FAILED,
+            }:
+                return batch_metadata, True
+
+            return None, False
+
+        batch_information = poll(polling_options=polling_options, polling_func=polling_func)
+
+        return self.batch_experiment(batch_id=batch_information.id)
+
     def cancel_run(self, run_id: str) -> None:
         """
         Cancel a run.
@@ -1130,7 +995,7 @@ class Application:
         else:
             # Get all input IDs from the input set.
             input_set = self.input_set(input_set_id=input_set_id)
-            if len(input_set.input_ids) == 0:
+            if not input_set.input_ids:
                 raise ValueError(f"input set {input_set_id} does not contain any inputs")
             runs = []
             for input_id in input_set.input_ids:
@@ -1191,7 +1056,7 @@ class Application:
         name: str,
         input_set_id: Optional[str] = None,
         description: Optional[str] = None,
-        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
     ) -> AcceptanceTest:
         """
         Create a new acceptance test and poll for the result.
@@ -1248,7 +1113,8 @@ class Application:
         >>> print(test.status)
         'completed'
         """
-        _ = self.new_acceptance_test(
+
+        acceptance_test = self.new_acceptance_test(
             candidate_instance_id=candidate_instance_id,
             baseline_instance_id=baseline_instance_id,
             id=id,
@@ -1258,20 +1124,10 @@ class Application:
             description=description,
         )
 
-        def polling_func() -> tuple[AcceptanceTest, bool]:
-            test_information = self.acceptance_test(acceptance_test_id=id)
-            if test_information.status in [
-                ExperimentStatus.completed,
-                ExperimentStatus.failed,
-                ExperimentStatus.canceled,
-            ]:
-                return test_information, True
-
-            return None, False
-
-        test_information = poll(polling_options=polling_options, polling_func=polling_func)
-
-        return test_information
+        return self.acceptance_test_with_polling(
+            acceptance_test_id=acceptance_test.id,
+            polling_options=polling_options,
+        )
 
     def new_batch_experiment(
         self,
@@ -1354,6 +1210,76 @@ class Application:
 
         return response.json()["id"]
 
+    def new_batch_experiment_with_result(
+        self,
+        name: str,
+        input_set_id: Optional[str] = None,
+        instance_ids: Optional[list[str]] = None,
+        description: Optional[str] = None,
+        id: Optional[str] = None,
+        option_sets: Optional[dict[str, dict[str, str]]] = None,
+        runs: Optional[list[Union[BatchExperimentRun, dict[str, Any]]]] = None,
+        type: Optional[str] = "batch",
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
+    ) -> BatchExperiment:
+        """
+        Convenience method to create a new batch experiment and poll for the
+        result.
+
+        This method combines the `new_batch_experiment` and
+        `batch_experiment_with_polling` methods, applying polling logic to
+        check when the experiment succeeded.
+
+        Parameters
+        ----------
+        name: str
+            Name of the batch experiment.
+        input_set_id: str
+            ID of the input set to use for the batch experiment.
+        instance_ids: list[str]
+            List of instance IDs to use for the batch experiment. This argument
+            is deprecated, use `runs` instead.
+        description: Optional[str]
+            Optional description of the batch experiment.
+        id: Optional[str]
+            ID of the batch experiment. Will be generated if not provided.
+        option_sets: Optional[dict[str, dict[str, str]]]
+            Option sets to use for the batch experiment. This is a dictionary
+            where the keys are option set IDs and the values are dictionaries
+            with the actual options.
+        runs: Optional[list[BatchExperimentRun]]
+            List of runs to use for the batch experiment.
+        type: Optional[str]
+            Type of the batch experiment. This is used to determine the
+            experiment type. The default value is "batch". If you want to
+            create a scenario test, set this to "scenario".
+        polling_options : PollingOptions, default=_DEFAULT_POLLING_OPTIONS
+            Options to use when polling for the batch experiment result.
+
+        Returns
+        -------
+        BatchExperiment
+            The completed batch experiment with results.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        batch_id = self.new_batch_experiment(
+            name=name,
+            input_set_id=input_set_id,
+            instance_ids=instance_ids,
+            description=description,
+            id=id,
+            option_sets=option_sets,
+            runs=runs,
+            type=type,
+        )
+
+        return self.batch_experiment_with_polling(batch_id=batch_id, polling_options=polling_options)
+
     def new_input_set(
         self,
         id: str,
@@ -1722,7 +1648,7 @@ class Application:
             not `JSON`. If the final `options` are not of type `dict[str,str]`.
         """
 
-        self.__validate_dir_path_and_configuration(input_dir_path, configuration)
+        self.__validate_input_dir_path_and_configuration(input_dir_path, configuration)
 
         tar_file = ""
         if input_dir_path is not None and input_dir_path != "":
@@ -1734,13 +1660,7 @@ class Application:
 
             tar_file = self.__package_inputs(input_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):
-            input_data = input.data
+        input_data = self.__extract_input_data(input)
 
         input_size = 0
         if input_data is not None:
@@ -1753,20 +1673,10 @@ class Application:
             upload_id = upload_url.upload_id
             upload_id_used = True
 
-        options_dict = {}
-        if isinstance(input, Input) and input.options is not None:
-            options_dict = input.options.to_dict_cloud()
-
-        if options is not None:
-            if isinstance(options, Options):
-                options_dict = options.to_dict_cloud()
-            elif isinstance(options, dict):
-                for k, v in options.items():
-                    if isinstance(v, str):
-                        options_dict[k] = v
-                    else:
-                        options_dict[k] = deflated_serialize_json(v, json_configurations=json_configurations)
+        options_dict = self.__extract_options_dict(options, json_configurations)
 
+        # Builds the payload progressively based on the different arguments
+        # that must be provided.
         payload = {}
         if upload_id_used:
             payload["upload_id"] = upload_id
@@ -1779,19 +1689,11 @@ class Application:
             payload["description"] = description
         if len(options_dict) > 0:
             for k, v in options_dict.items():
-                if not isinstance(v, str):
-                    raise ValueError(f"options must be dict[str,str], option {k} has type {type(v)} instead.")
-            payload["options"] = options_dict
-
-        if configuration is not None:
-            configuration_dict = (
-                configuration.to_dict() if isinstance(configuration, RunConfiguration) else configuration
-            )
-        else:
-            configuration = RunConfiguration()
-            configuration.resolve(input=input, dir_path=input_dir_path)
-            configuration_dict = configuration.to_dict()
+                if not isinstance(v, str):
+                    raise ValueError(f"options must be dict[str,str], option {k} has type {type(v)} instead.")
+            payload["options"] = options_dict
 
+        configuration_dict = self.__extract_run_config(input, configuration, input_dir_path)
         payload["configuration"] = configuration_dict
 
         if batch_experiment_id is not None:
@@ -1823,7 +1725,7 @@ class Application:
         description: Optional[str] = None,
         upload_id: Optional[str] = None,
         run_options: Optional[Union[Options, dict[str, str]]] = None,
-        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
         configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
         batch_experiment_id: Optional[str] = None,
         external_result: Optional[Union[ExternalRunResult, dict[str, Any]]] = None,
@@ -2085,6 +1987,69 @@ class Application:
             runs=runs,
         )
 
+    def new_scenario_test_with_result(
+        self,
+        id: str,
+        name: str,
+        scenarios: list[Scenario],
+        description: Optional[str] = None,
+        repetitions: Optional[int] = 0,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
+    ) -> BatchExperiment:
+        """
+        Convenience method to create a new scenario test and poll for the
+        result.
+
+        This method combines the `new_scenario_test` and
+        `scenario_test_with_polling` methods, applying polling logic to
+        check when the test succeeded.
+
+        The scenario tests uses the batch experiments API under the hood.
+
+        Parameters
+        ----------
+        id: str
+            ID of the scenario test.
+        name: str
+            Name of the scenario test.
+        scenarios: list[Scenario]
+            List of scenarios to use for the scenario test. At least one
+            scenario should be provided.
+        description: Optional[str]
+            Optional description of the scenario test.
+        repetitions: Optional[int]
+            Number of repetitions to use for the scenario test. 0
+            repetitions means that the tests will be executed once. 1
+            repetition means that the test will be repeated once, i.e.: it
+            will be executed twice. 2 repetitions equals 3 executions, so on,
+            and so forth.
+
+        Returns
+        -------
+        BatchExperiment
+            The completed scenario test as a BatchExperiment.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        ValueError
+            If no scenarios are provided.
+        """
+
+        test_id = self.new_scenario_test(
+            id=id,
+            name=name,
+            scenarios=scenarios,
+            description=description,
+            repetitions=repetitions,
+        )
+
+        return self.scenario_test_with_polling(
+            scenario_test_id=test_id,
+            polling_options=polling_options,
+        )
+
     def new_secrets_collection(
         self,
         secrets: list[Secret],
@@ -2236,7 +2201,7 @@ class Application:
             return self.version(version_id=id)
 
         if id is None:
-            id = _safe_id(prefix="version")
+            id = safe_id(prefix="version")
 
         payload = {
             "id": id,
@@ -2567,7 +2532,7 @@ class Application:
     def run_result_with_polling(
         self,
         run_id: str,
-        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
         output_dir_path: Optional[str] = ".",
     ) -> RunResult:
         """
@@ -2638,9 +2603,9 @@ class Application:
         """
         Get a scenario test.
 
-        Retrieves a scenario test by ID. Scenario tests are based on batch experiments,
-        so this function returns the corresponding batch experiment associated with
-        the scenario test.
+        Retrieves a scenario test by ID. Scenario tests are based on batch
+        experiments, so this function returns the corresponding batch
+        experiment associated with the scenario test.
 
         Parameters
         ----------
@@ -2668,7 +2633,88 @@ class Application:
 
         return self.batch_experiment(batch_id=scenario_test_id)
 
-    def track_run(self, tracked_run: TrackedRun, instance_id: Optional[str] = None) -> str:
+    def scenario_test_metadata(self, scenario_test_id: str) -> BatchExperimentMetadata:
+        """
+        Get the metadata for a scenario test, given its ID.
+
+        Scenario tests are based on batch experiments, so this function returns
+        the corresponding batch experiment metadata associated with the
+        scenario test.
+
+        Parameters
+        ----------
+        scenario_test_id : str
+            ID of the scenario test to retrieve.
+
+        Returns
+        -------
+        BatchExperimentMetadata
+            The scenario test metadata as a batch experiment.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> metadata = app.scenario_test_metadata("scenario-123")
+        >>> print(metadata.name)
+        'My Scenario Test'
+        >>> print(metadata.type)
+        'scenario'
+        """
+
+        return self.batch_experiment_metadata(batch_id=scenario_test_id)
+
+    def scenario_test_with_polling(
+        self,
+        scenario_test_id: str,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
+    ) -> BatchExperiment:
+        """
+        Get a scenario test with polling.
+
+        Retrieves the result of a scenario test. This method polls for the
+        result until the test finishes executing or the polling strategy is
+        exhausted.
+
+        The scenario tests uses the batch experiments API under the hood.
+
+        Parameters
+        ----------
+        scenario_test_id : str
+            ID of the scenario test to retrieve.
+        polling_options : PollingOptions, default=_DEFAULT_POLLING_OPTIONS
+            Options to use when polling for the scenario test result.
+
+        Returns
+        -------
+        BatchExperiment
+            The scenario test details as a batch experiment.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> test = app.scenario_test_with_polling("scenario-123")
+        >>> print(test.name)
+        'My Scenario Test'
+        >>> print(test.type)
+        'scenario'
+        """
+
+        return self.batch_experiment_with_polling(batch_id=scenario_test_id, polling_options=polling_options)
+
+    def track_run(  # noqa: C901
+        self,
+        tracked_run: TrackedRun,
+        instance_id: Optional[str] = None,
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
+    ) -> str:
         """
         Track an external run.
 
@@ -2677,6 +2723,14 @@ class Application:
         information about a run in Nextmv is useful for things like
         experimenting and testing.
 
+        Please read the documentation on the `TrackedRun` class carefully, as
+        there are important considerations to take into account when using this
+        method. For example, if you intend to upload JSON input/output, use the
+        `input`/`output` attributes of the `TrackedRun` class. On the other
+        hand, if you intend to track files-based input/output, use the
+        `input_dir_path`/`output_dir_path` attributes of the `TrackedRun`
+        class.
+
         Parameters
         ----------
         tracked_run : TrackedRun
@@ -2684,6 +2738,11 @@ class Application:
         instance_id : Optional[str], default=None
             Optional instance ID if you want to associate your tracked run with
             an instance.
+        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
+            configuration.
 
         Returns
         -------
@@ -2706,22 +2765,55 @@ class Application:
         >>> run_id = app.track_run(tracked_run)
         """
 
+        # Get the URL to upload the input to.
         url_input = self.upload_url()
 
+        # Handle the case where the input is being uploaded as files. We need
+        # to tar them.
+        input_tar_file = ""
+        input_dir_path = tracked_run.input_dir_path
+        if input_dir_path is not None and input_dir_path != "":
+            if not os.path.exists(input_dir_path):
+                raise ValueError(f"Directory {input_dir_path} does not exist.")
+
+            if not os.path.isdir(input_dir_path):
+                raise ValueError(f"Path {input_dir_path} is not a directory.")
+
+            input_tar_file = self.__package_inputs(input_dir_path)
+
+        # Handle the case where the input is uploaded as Input or a dict.
         upload_input = tracked_run.input
-        if isinstance(tracked_run.input, Input):
+        if upload_input is not None and isinstance(tracked_run.input, Input):
             upload_input = tracked_run.input.data
 
-        self.upload_large_input(input=upload_input, upload_url=url_input)
+        # Actually uploads de input.
+        self.upload_large_input(input=upload_input, upload_url=url_input, tar_file=input_tar_file)
 
+        # Get the URL to upload the output to.
         url_output = self.upload_url()
 
+        # Handle the case where the output is being uploaded as files. We need
+        # to tar them.
+        output_tar_file = ""
+        output_dir_path = tracked_run.output_dir_path
+        if output_dir_path is not None and output_dir_path != "":
+            if not os.path.exists(output_dir_path):
+                raise ValueError(f"Directory {output_dir_path} does not exist.")
+
+            if not os.path.isdir(output_dir_path):
+                raise ValueError(f"Path {output_dir_path} is not a directory.")
+
+            output_tar_file = self.__package_inputs(output_dir_path)
+
+        # Handle the case where the output is uploaded as Output or a dict.
         upload_output = tracked_run.output
-        if isinstance(tracked_run.output, Output):
+        if upload_output is not None and isinstance(tracked_run.output, Output):
             upload_output = tracked_run.output.to_dict()
 
-        self.upload_large_input(input=upload_output, upload_url=url_output)
+        # Actually uploads the output.
+        self.upload_large_input(input=upload_output, upload_url=url_output, tar_file=output_tar_file)
 
+        # Create the external run result and appends logs if required.
         external_result = ExternalRunResult(
             output_upload_id=url_output.upload_id,
             status=tracked_run.status.value,
@@ -2740,14 +2832,18 @@ class Application:
             upload_id=url_input.upload_id,
             external_result=external_result,
             instance_id=instance_id,
+            name=tracked_run.name,
+            description=tracked_run.description,
+            configuration=configuration,
         )
 
     def track_run_with_result(
         self,
         tracked_run: TrackedRun,
-        polling_options: PollingOptions = _DEFAULT_POLLING_OPTIONS,
+        polling_options: PollingOptions = DEFAULT_POLLING_OPTIONS,
         instance_id: Optional[str] = None,
         output_dir_path: Optional[str] = ".",
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
     ) -> RunResult:
         """
         Track an external run and poll for the result. This is a convenience
@@ -2768,6 +2864,11 @@ class Application:
             Path to a directory where non-JSON output files will be saved. This is
             required if the output is non-JSON. If the directory does not exist, it
             will be created. Uses the current directory by default.
+        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
+            configuration.
 
         Returns
         -------
@@ -2787,7 +2888,11 @@ class Application:
             If the run does not succeed after the polling strategy is
             exhausted based on number of tries.
         """
-        run_id = self.track_run(tracked_run=tracked_run, instance_id=instance_id)
+        run_id = self.track_run(
+            tracked_run=tracked_run,
+            instance_id=instance_id,
+            configuration=configuration,
+        )
 
         return self.run_result_with_polling(
             run_id=run_id,
@@ -3393,6 +3498,47 @@ class Application:
 
         return result
 
+    @staticmethod
+    def __convert_manifest_to_payload(manifest: Manifest) -> dict[str, Any]:
+        """Converts a manifest to a payload dictionary for the API."""
+
+        activation_request = {
+            "requirements": {
+                "executable_type": manifest.type,
+                "runtime": manifest.runtime,
+            },
+        }
+
+        if manifest.configuration is not None and manifest.configuration.content is not None:
+            content = manifest.configuration.content
+            io_config = {
+                "format": content.format,
+            }
+            if content.multi_file is not None:
+                multi_config = io_config["multi_file"] = {}
+                if content.multi_file.input is not None:
+                    multi_config["input_path"] = content.multi_file.input.path
+                if content.multi_file.output is not None:
+                    output_config = multi_config["output_configuration"] = {}
+                    if content.multi_file.output.statistics:
+                        output_config["statistics_path"] = content.multi_file.output.statistics
+                    if content.multi_file.output.assets:
+                        output_config["assets_path"] = content.multi_file.output.assets
+                    if content.multi_file.output.solutions:
+                        output_config["solutions_path"] = content.multi_file.output.solutions
+            activation_request["requirements"]["io_configuration"] = io_config
+
+        if manifest.configuration is not None and manifest.configuration.options is not None:
+            options = manifest.configuration.options.to_dict()
+            if "format" in options and isinstance(options["format"], list):
+                # the endpoint expects a dictionary with a template key having a list of strings
+                # the app.yaml however defines format as a list of strings, so we need to convert it here
+                options["format"] = {
+                    "template": options["format"],
+                }
+            activation_request["requirements"]["options"] = options
+        return activation_request
+
     def __update_app_binary(
         self,
         tar_file: str,
@@ -3419,27 +3565,10 @@ class Application:
                 headers={"Content-Type": "application/octet-stream"},
             )
 
-        activation_request = {
-            "requirements": {
-                "executable_type": manifest.type,
-                "runtime": manifest.runtime,
-            },
-        }
-
-        if manifest.configuration is not None and manifest.configuration.options is not None:
-            options = manifest.configuration.options.to_dict()
-            if "format" in options and isinstance(options["format"], list):
-                # the endpoint expects a dictionary with a template key having a list of strings
-                # the app.yaml however defines format as a list of strings, so we need to convert it here
-                options["format"] = {
-                    "template": options["format"],
-                }
-            activation_request["requirements"]["options"] = options
-
         response = self.client.request(
             method="PUT",
             endpoint=endpoint,
-            payload=activation_request,
+            payload=Application.__convert_manifest_to_payload(manifest=manifest),
         )
 
         if verbose:
@@ -3469,7 +3598,7 @@ class Application:
         # If working with a list of managed inputs, we need to create an
         # input set.
         if scenario.scenario_input.scenario_input_type == ScenarioInputType.INPUT:
-            name, id = _name_and_id(prefix="inpset", entity_id=scenario_id)
+            name, id = safe_name_and_id(prefix="inpset", entity_id=scenario_id)
             input_set = self.new_input_set(
                 id=id,
                 name=name,
@@ -3489,7 +3618,7 @@ class Application:
             for data in scenario.scenario_input.scenario_input_data:
                 upload_url = self.upload_url()
                 self.upload_large_input(input=data, upload_url=upload_url)
-                name, id = _name_and_id(prefix="man-input", entity_id=scenario_id)
+                name, id = safe_name_and_id(prefix="man-input", entity_id=scenario_id)
                 managed_input = self.new_managed_input(
                     id=id,
                     name=name,
@@ -3498,7 +3627,7 @@ class Application:
                 )
                 managed_inputs.append(managed_input)
 
-            name, id = _name_and_id(prefix="inpset", entity_id=scenario_id)
+            name, id = safe_name_and_id(prefix="inpset", entity_id=scenario_id)
             input_set = self.new_input_set(
                 id=id,
                 name=name,
@@ -3510,15 +3639,16 @@ class Application:
 
         raise ValueError(f"Unknown scenario input type: {scenario.scenario_input.scenario_input_type}")
 
-    def __validate_dir_path_and_configuration(
+    def __validate_input_dir_path_and_configuration(
         self,
-        dir_path: Optional[str],
-        configuration: Optional[RunConfiguration],
+        input_dir_path: Optional[str],
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]],
     ) -> None:
         """
         Auxiliary function to validate the directory path and configuration.
         """
-        if dir_path is None or dir_path == "":
+
+        if input_dir_path is None or input_dir_path == "":
             return
 
         if configuration is None:
@@ -3526,23 +3656,57 @@ class Application:
                 "If dir_path is provided, a RunConfiguration must also be provided.",
             )
 
-        if configuration.format is None:
+        config_format = self.__extract_config_format(configuration)
+
+        if config_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 = self.__extract_input_type(config_format)
 
-        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."
+                "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 __extract_config_format(self, configuration: Union[RunConfiguration, dict[str, Any]]) -> Any:
+        """Extract format from configuration, handling both RunConfiguration objects and dicts."""
+        if isinstance(configuration, RunConfiguration):
+            return configuration.format
+
+        if isinstance(configuration, dict):
+            config_format = configuration.get("format")
+            if config_format is not None and isinstance(config_format, dict):
+                return Format.from_dict(config_format) if hasattr(Format, "from_dict") else config_format
+
+            return config_format
+
+        raise ValueError("Configuration must be a RunConfiguration object or a dict.")
+
+    def __extract_input_type(self, config_format: Any) -> Any:
+        """Extract input type from config format."""
+        if isinstance(config_format, dict):
+            format_input = config_format.get("format_input") or config_format.get("input")
+            if format_input is None:
+                raise ValueError(
+                    "If dir_path is provided, RunConfiguration.format.format_input must also be provided.",
+                )
+
+            if isinstance(format_input, dict):
+                return format_input.get("input_type") or format_input.get("type")
+
+            return getattr(format_input, "input_type", None)
+
+        # Handle Format object
+        if config_format.format_input is None:
+            raise ValueError(
+                "If dir_path is provided, RunConfiguration.format.format_input must also be provided.",
+            )
+
+        return config_format.format_input.input_type
+
     def __package_inputs(self, dir_path: str) -> str:
         """
         This is an auxiliary function for packaging the inputs found in the
@@ -3604,153 +3768,72 @@ class Application:
 
         return size_exceeds or non_json_payload
 
+    def __extract_input_data(
+        self,
+        input: Union[Input, dict[str, Any], BaseModel, str] = None,
+    ) -> Optional[Union[dict[str, Any], str]]:
+        """
+        Auxiliary function to extract the input data from the input, based on
+        its type.
+        """
 
-def poll(  # noqa: C901
-    polling_options: PollingOptions,
-    polling_func: Callable[[], tuple[Any, bool]],
-    __sleep_func: Callable[[float], None] = time.sleep,
-) -> Any:
-    """
-    Poll a function until it succeeds or the polling strategy is exhausted.
-
-    You can import the `poll` function directly from `cloud`:
-
-    ```python
-    from nextmv.cloud import poll
-    ```
-
-    This function implements a flexible polling strategy with exponential backoff
-    and jitter. It calls the provided polling function repeatedly until it indicates
-    success, the maximum number of tries is reached, or the maximum duration is exceeded.
-
-    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.
-
-    Parameters
-    ----------
-    polling_options : PollingOptions
-        Options for configuring the polling behavior, including retry counts,
-        delays, timeouts, and verbosity settings.
-    polling_func : callable
-        Function to call to check if the polling was successful. Must return a tuple
-        where the first element is the result value and the second is a boolean
-        indicating success (True) or need to retry (False).
-
-    Returns
-    -------
-    Any
-        Result value from the polling function when successful.
-
-    Raises
-    ------
-    TimeoutError
-        If the polling exceeds the maximum duration specified in polling_options.
-    RuntimeError
-        If the maximum number of tries is exhausted without success.
-
-    Examples
-    --------
-    >>> from nextmv.cloud import PollingOptions, poll
-    >>> import time
-    >>>
-    >>> # Define a polling function that succeeds after 3 tries
-    >>> counter = 0
-    >>> def check_completion() -> tuple[str, bool]:
-    ...     global counter
-    ...     counter += 1
-    ...     if counter >= 3:
-    ...         return "Success", True
-    ...     return None, False
-    ...
-    >>> # Configure polling options
-    >>> options = PollingOptions(
-    ...     max_tries=5,
-    ...     delay=0.1,
-    ...     backoff=0.2,
-    ...     verbose=True
-    ... )
-    >>>
-    >>> # Poll until the function succeeds
-    >>> result = poll(options, check_completion)
-    >>> print(result)
-    'Success'
-    """
-
-    # Start by sleeping for the duration specified as initial delay.
-    if polling_options.verbose:
-        log(f"polling | sleeping for initial delay: {polling_options.initial_delay}")
-
-    __sleep_func(polling_options.initial_delay)
+        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):
+            input_data = input.data
 
-    start_time = time.time()
-    stopped = False
+        return input_data
 
-    # Begin the polling process.
-    max_reached = False
-    ix = 0
-    while True:
-        # Check if we reached the maximum number of tries. Break if so.
-        if ix >= polling_options.max_tries and polling_options.max_tries >= 0:
-            break
-        ix += 1
+    def __extract_options_dict(
+        self,
+        options: Optional[Union[Options, dict[str, str]]] = None,
+        json_configurations: Optional[dict[str, Any]] = None,
+    ) -> dict[str, str]:
+        """
+        Auxiliary function to extract the options that will be sent to the
+        application for execution.
+        """
 
-        # Check is we should stop polling according to the stop callback.
-        if polling_options.stop is not None and polling_options.stop():
-            stopped = True
+        options_dict = {}
+        if options is not None:
+            if isinstance(options, Options):
+                options_dict = options.to_dict_cloud()
 
-            break
+            elif isinstance(options, dict):
+                for k, v in options.items():
+                    if isinstance(v, str):
+                        options_dict[k] = v
+                        continue
 
-        # We check if we can stop polling.
-        result, ok = polling_func()
-        if polling_options.verbose:
-            log(f"polling | try # {ix + 1}, ok: {ok}")
+                    options_dict[k] = deflated_serialize_json(v, json_configurations=json_configurations)
 
-        if ok:
-            return result
+        return options_dict
 
-        # An exit condition happens if we exceed the allowed duration.
-        passed = time.time() - start_time
-        if polling_options.verbose:
-            log(f"polling | elapsed time: {passed}")
+    def __extract_run_config(
+        self,
+        input: Union[Input, dict[str, Any], BaseModel, str] = None,
+        configuration: Optional[Union[RunConfiguration, dict[str, Any]]] = None,
+        dir_path: Optional[str] = None,
+    ) -> dict[str, Any]:
+        """
+        Auxiliary function to extract the run configuration that will be sent
+        to the application for execution.
+        """
 
-        if passed >= polling_options.max_duration and polling_options.max_duration >= 0:
-            raise TimeoutError(
-                f"polling did not succeed after {passed} seconds, exceeds max duration: {polling_options.max_duration}",
+        if configuration is not None:
+            configuration_dict = (
+                configuration.to_dict() if isinstance(configuration, RunConfiguration) else configuration
             )
+            return configuration_dict
 
-        # Calculate the delay.
-        if max_reached:
-            # If we already reached the maximum, we don't want to further calculate the
-            # delay to avoid overflows.
-            delay = polling_options.max_delay
-            delay += random.uniform(0, polling_options.jitter)  # Add jitter.
-        else:
-            delay = polling_options.delay  # Base
-            delay += polling_options.backoff * (2**ix)  # Add exponential backoff.
-            delay += random.uniform(0, polling_options.jitter)  # Add jitter.
-
-        # We cannot exceed the max delay.
-        if delay >= polling_options.max_delay:
-            max_reached = True
-            delay = polling_options.max_delay
-
-        # Sleep for the calculated delay.
-        sleep_duration = delay
-        if polling_options.verbose:
-            log(f"polling | sleeping for duration: {sleep_duration}")
-
-        __sleep_func(sleep_duration)
-
-    if stopped:
-        log("polling | stop condition met, stopping polling")
-
-        return None
+        configuration = RunConfiguration()
+        configuration.resolve(input=input, dir_path=dir_path)
+        configuration_dict = configuration.to_dict()
 
-    raise RuntimeError(
-        f"polling did not succeed after {polling_options.max_tries} tries",
-    )
+        return configuration_dict
 
 
 def _is_not_exist_error(e: requests.HTTPError) -> bool: