nextmv 0.18.0__py3-none-any.whl → 1.0.0.dev2__py3-none-any.whl

nextmv/cloud/ensemble.py

@@ -0,0 +1,247 @@
+"""
+Classes for working with Nextmv Cloud Ensemble Runs.
+
+This module provides classes for interacting with ensemble runs in Nextmv Cloud.
+It details the core data structures for ensemble definitions.
+
+Classes
+-------
+RunGroup
+    A structure to group execution of child runs for an ensemble run.
+RuleObjective
+    An enum that specifies the supported evaluation rule objectives.
+ToleranceType
+    An enum that specifies the supported tolerance types for evaluation rules.
+RuleTolerance
+    A structure for defining tolerance thresholds for an evaluation rule
+EvaluationRule
+    A structure to evaluate run results for an ensemble run.
+EnsembleDefinition
+    Representation of a Nextmv Cloud Ensemble Definition for an application.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+from nextmv.base_model import BaseModel
+
+
+class RunGroup(BaseModel):
+    """A structure to group child runs for an ensemble run.
+
+    You can import the `RunGroup` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RunGroup
+    ```
+
+    This class represents a grouping of child runs that share a configuration
+    for ensemble run executions.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the run group.
+    instance_id : str
+        ID of the app instance that this run group executes on.
+    options : dict, optional
+        Runtime options/parameters for the application.
+    repetitions : int, optional
+        The number of times the run is to be repeated on the instance and with
+        the options defined in the run group
+    """
+
+    id: str
+    """The unique identifier of the run group."""
+    instance_id: str
+    """ID of the app instance that this run group executes on."""
+    options: dict | None = None
+    """Runtime options/parameters for the application."""
+    repetitions: int | None = None
+    """The number of times the run is to be repeated on the instance and with
+    the options defined in the run group"""
+
+
+class RuleObjective(str, Enum):
+    """The value of this data determines how a value of a run is optimized to
+    determined which ensemble child run is the "best" for a given metric and
+    rule, as well as which other ones are within tolerance of that run for the
+    purposes of selecting a result for the ensemble run from among the child runs.
+
+    You can import the `RuleObjective` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleObjective
+    ```
+
+    This enum specifies the supported evaluation rule objectives.
+
+    Attributes
+    ----------
+    MAXIMIZE : str
+        Maximize the value of the evaluated metric.
+    MINIMIZE : str
+        Minimize the value of the evaluated metric.
+    """
+
+    MAXIMIZE = "maximize"
+    """Maximize the value of the evaluated metric."""
+    MINIMIZE = "minimize"
+    """Minimize the value of the evaluated metric."""
+
+
+class RuleToleranceType(str, Enum):
+    """The type of comparison used to determine if a run metric is within
+    tolerance of a the "best" run for that rule and metric
+
+    You can import the `RuleToleranceType` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleToleranceType
+    ```
+
+    This enum specifies the supported tolerance types.
+
+    Attributes
+    ----------
+    ABSOLUTE : str
+        Uses the absolute difference between the value of the "best" run and
+        the run being evaluated for tolerance
+    RELATIVE : str
+        Uses the the percentage of the "best" run by which the run being
+        evaluted for tolerance differs. A value of `1` is 100%.
+    """
+
+    ABSOLUTE = "absolute"
+    """Uses the absolute difference between the value of the "best" run and
+    the run being evaluated for tolerance"""
+    RELATIVE = "relative"
+    """Uses the the percentage of the "best" run by which the run being
+    evaluted for tolerance differs. A value of `1` is 100%."""
+
+
+class RuleTolerance(BaseModel):
+    """A structure used to determine if a run is within tolerance of of the best
+    run (as determined by the objective of the `EvaluationRule` it is defined on).
+
+    You can import the `RuleTolerance` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import RuleTolerance
+    ```
+
+    This class represents the tolerance on a particular evaluation rule by
+    which a child run may be selected as the result of an ensemble run.
+
+    value : float
+        The value within which runs can deviate from the "best" run
+        for that metric to be considered within tolerance of it.
+    type : ToleranceType
+        The method by which runs are determined to be within tolerance.
+    """
+
+    value: float
+    """The value within which runs can deviate from the "best" run
+    for that metric to be considered within tolerance of it."""
+    type: RuleToleranceType
+    """The method by which runs are determined to be within tolerance."""
+
+
+class EvaluationRule(BaseModel):
+    """A structure to evaluate run results for an ensemble run.
+
+    You can import the `EvaluationRule` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import EvaluationRule
+    ```
+
+    This class represents a rule by which the child runs for an ensemble run
+    will be evaluated for the purpose of selecting an optimal result for the
+    ensemble run.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the evaluation rule.
+    statistics_path : str
+        The path within the statistics of a run output (conforming to Nextmv
+        statistics convention and flattened to a string starting with `$` and
+        delimited by `.` e.g. `$.result.value`.)
+    objective : RuleObjective
+        The objective by which runs are optimized for this rule
+    tolerance : RuleTolerance
+        The tolerance by which runs can be accepted as a potential result
+        for an evaluation rule
+    index : int, optional
+        The index (non-negative integer) of the evalutation rule. Lower indicies
+        are evaluated first.
+    """
+
+    id: str
+    """The unique identifier of the evaluation rule."""
+    statistics_path: str
+    """The path within the statistics of a run output (conforming to Nextmv
+    statistics convention and flattened to a string starting with `$` and
+    delimited by `.` e.g. `$.result.value`.)"""
+    objective: RuleObjective
+    """The objective by which runs are optimized for this rule"""
+    tolerance: RuleTolerance
+    """The tolerance by which runs can be accepted as a potential result
+    for an evaluation rule"""
+    index: int
+    """The index (non-negative integer) of the evalutation rule. Lower indicies
+    are evaluated first."""
+
+
+class EnsembleDefinition(BaseModel):
+    """An ensemble definition for an application.
+
+    You can import the `EnsembleDefinition` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import EnsembleDefinition
+    ```
+
+    A Nextmv Cloud ensemble definition represents a structure by which an
+    application can coordinate and execute, and determine the optimal result of
+    an ensemble run.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the ensemble definition.
+    application_id : str
+        ID of the application that this ensemble definition belongs to.
+    name : str
+        Human-readable name of the ensemble definition.
+    description : str
+        Detailed description of the ensemble definition.
+    run_groups : list[RunGroup], optional
+        The run groups that structure the execution of an ensemble run
+    rules : list[EvaluationRule], optional
+        The rules by which ensemble child runs are evaluated
+        to find an optimal result.
+    created_at : datetime
+        Timestamp when the ensemble definition was created.
+    updated_at : datetime
+        Timestamp when the ensemble definition was last updated.
+    """
+
+    id: str
+    """The unique identifier of the ensemble definition."""
+    application_id: str
+    """ID of the application that this ensemble definition belongs to."""
+    name: str = ""
+    """Human-readable name of the ensemble definition."""
+    description: str = ""
+    """Detailed description of the ensemble definition."""
+    run_groups: list[RunGroup]
+    """The run groups that structure the execution of an ensemble run"""
+    rules: list[EvaluationRule]
+    """The rules by which ensemble child runs are evaluated
+    to find an optimal result."""
+    created_at: datetime
+    """Timestamp when the ensemble definition was created."""
+    updated_at: datetime
+    """Timestamp when the ensemble definition was last updated."""

nextmv/cloud/input_set.py

@@ -1,12 +1,128 @@
-"""This module contains definitions for input sets."""
+"""Definitions for input sets and related cloud objects.
+
+This module provides classes for managing inputs and input sets in the Nextmv Cloud.
+
+Classes
+-------
+ManagedInput
+    An input created for experimenting with an application.
+InputSet
+    A collection of inputs from associated runs.
+"""
 
 from datetime import datetime
 
 from nextmv.base_model import BaseModel
+from nextmv.run import Format
+
+
+class ManagedInput(BaseModel):
+    """An input created for experimenting with an application.
+
+    You can import the `ManagedInput` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ManagedInput
+    ```
+
+    This class represents an input that was uploaded to the Nextmv Cloud
+    for experimentation purposes. It contains metadata about the input,
+    such as its ID, name, description, and creation time.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier of the input.
+    name : str, optional
+        User-defined name of the input.
+    description : str, optional
+        User-defined description of the input.
+    run_id : str, optional
+        Identifier of the run that created this input.
+    upload_id : str, optional
+        Identifier of the upload that created this input.
+    format : Format, optional
+        Format of the input (e.g., JSON, CSV).
+    created_at : datetime, optional
+        Timestamp when the input was created.
+    updated_at : datetime, optional
+        Timestamp when the input was last updated.
+
+    Examples
+    --------
+    >>> input = ManagedInput(id="inp_123456789")
+    >>> print(input.id)
+    inp_123456789
+    """
+
+    id: str
+    """ID of the input."""
+
+    name: str | None = None
+    """Name of the input."""
+    description: str | None = None
+    """Description of the input."""
+    run_id: str | None = None
+    """ID of the run that created the input."""
+    upload_id: str | None = None
+    """ID of the upload that created the input."""
+    format: Format | None = None
+    """Format of the input."""
+    created_at: datetime | None = None
+    """Creation time of the input."""
+    updated_at: datetime | None = None
+    """Last update time of the input."""
 
 
 class InputSet(BaseModel):
-    """An input set is the collection of inputs from the associated runs."""
+    """A collection of inputs from associated runs.
+
+    You can import the `InputSet` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import InputSet
+    ```
+
+    An input set aggregates multiple inputs used for experimentation with an application
+    in the Nextmv Cloud. It allows organizing and managing related inputs
+    for comparison and analysis.
+
+    Parameters
+    ----------
+    app_id : str
+        Identifier of the application that the input set belongs to.
+    created_at : datetime
+        Timestamp when the input set was created.
+    description : str
+        User-defined description of the input set.
+    id : str
+        Unique identifier of the input set.
+    input_ids : list[str]
+        List of identifiers of the inputs in the input set.
+    name : str
+        User-defined name of the input set.
+    updated_at : datetime
+        Timestamp when the input set was last updated.
+    inputs : list[ManagedInput]
+        List of ManagedInput objects contained in this input set.
+
+    Examples
+    --------
+    >>> input_set = InputSet(
+    ...     app_id="app_123456789",
+    ...     id="is_987654321",
+    ...     name="My Input Set",
+    ...     description="A collection of routing inputs",
+    ...     input_ids=["inp_111", "inp_222"],
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now(),
+    ...     inputs=[]
+    ... )
+    >>> print(input_set.name)
+    My Input Set
+    >>> print(len(input_set.input_ids))
+    2
+    """
 
     app_id: str
     """ID of the application that the input set belongs to."""
@@ -22,3 +138,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/instance.py

@@ -1,22 +1,147 @@
-"""This module contains definitions for instances."""
+"""Classes for working with Nextmv Cloud Instances.
+
+This module provides classes for interacting with instances in Nextmv Cloud.
+It defines the core data structures for both instance configuration and the
+instance itself.
+
+Classes
+-------
+InstanceConfiguration
+    Configuration settings for a Nextmv Cloud instance.
+Instance
+    Representation of a Nextmv Cloud instance tied to an application version.
+"""
 
 from datetime import datetime
-from typing import Optional
 
 from nextmv.base_model import BaseModel
+from nextmv.run import Format, RunQueuing
+
+
+class InstanceConfiguration(BaseModel):
+    """Configuration for a Nextmv Cloud instance.
+
+    You can import the `InstanceConfiguration` class directly from `cloud`:
 
+    ```python
+    from nextmv.cloud import InstanceConfiguration
+    ```
 
-class Configuration(BaseModel):
-    """Configuration for an instance."""
+    This class represents the configuration settings that can be applied to a
+    Nextmv Cloud instance, including execution class, options, and secrets.
 
-    execution_class: Optional[str] = None
+    Parameters
+    ----------
+    execution_class : str, optional
+        The execution class for the instance, which determines compute resources.
+    options : dict, optional
+        Runtime options/parameters for the application.
+    secrets_collection_id : str, optional
+        ID of the secrets collection to use with this instance.
+    queuing : RunQueuing, optional
+        Queuing configuration for the instance.
+    integration_id : str, optional
+        ID of the integration to use for the instance.
+
+    Examples
+    --------
+    >>> config = InstanceConfiguration(
+    ...     execution_class="small",
+    ...     options={"max_runtime": 30},
+    ...     secrets_collection_id="sc_1234567890"
+    ... )
+    """
+
+    execution_class: str | None = None
     """Execution class for the instance."""
-    options: Optional[dict] = None
+    format: Format | None = None
+    """Input format for the instance, if applicable. When configuring an
+    instance, only the `format.format_input` attribute is used."""
+    options: dict | None = None
     """Options of the app that the instance uses."""
+    secrets_collection_id: str | None = None
+    """ID of the secrets collection that the instance uses."""
+    queuing: RunQueuing | None = None
+    """Queuing configuration for the instance."""
+    integration_id: str | None = None
+    """ID of the integration to use for the instance."""
+
+    def model_post_init(self, __context) -> None:
+        """
+        Validations done after parsing the model.
+
+        Raises
+        ------
+        ValueError
+            If execution_class is an empty string.
+        """
+
+        if self.integration_id is None or self.integration_id == "":
+            return
+
+        integration_val = "integration"
+        if self.execution_class is not None and self.execution_class != "" and self.execution_class != integration_val:
+            raise ValueError(f"When integration_id is set, execution_class must be `{integration_val}` or None.")
+
+        self.execution_class = integration_val
+
+        # Processes the format to ensure only format_input is set.
+        if self.format is not None and self.format.format_input is not None:
+            final_format = Format(format_input=self.format.format_input)
+        else:
+            final_format = None
+        self.format = final_format
 
 
 class Instance(BaseModel):
-    """A instance of an application tied to a version and further configuration."""
+    """An instance of an application tied to a version with configuration.
+
+    You can import the `Instance` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Instance
+    ```
+
+    A Nextmv Cloud instance represents a deployable configuration of an application
+    version. Instances have their own unique identity and can be used to run jobs
+    with specific configurations.
+
+    Parameters
+    ----------
+    id : str
+        The unique identifier of the instance.
+    application_id : str
+        ID of the application that this instance belongs to.
+    version_id : str
+        ID of the application version this instance uses.
+    name : str
+        Human-readable name of the instance.
+    description : str
+        Detailed description of the instance.
+    configuration : InstanceConfiguration
+        Configuration settings for this instance.
+    locked : bool
+        Whether the instance is locked for modifications.
+    created_at : datetime
+        Timestamp when the instance was created.
+    updated_at : datetime
+        Timestamp when the instance was last updated.
+
+    Examples
+    --------
+    >>> from nextmv.cloud import Instance, InstanceConfiguration
+    >>> instance = Instance(
+    ...     id="inst_1234567890",
+    ...     application_id="app_1234567890",
+    ...     version_id="ver_1234567890",
+    ...     name="Production Routing Instance",
+    ...     description="Instance for daily production routing jobs",
+    ...     configuration=InstanceConfiguration(execution_class="small"),
+    ...     locked=False,
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    """
 
     id: str
     """ID of the instance."""
@@ -28,7 +153,7 @@ class Instance(BaseModel):
     """Name of the instance."""
     description: str
     """Description of the instance."""
-    configuration: Configuration
+    configuration: InstanceConfiguration
     """Configuration for the instance."""
     locked: bool
     """Whether the instance is locked."""