nextmv 0.39.0.dev1__py3-none-any.whl → 1.0.0__py3-none-any.whl

nextmv/cloud/application/_ensemble.py

@@ -0,0 +1,251 @@
+"""
+Application mixin for managing app ensembles.
+"""
+
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.ensemble import EnsembleDefinition, EvaluationRule, RunGroup
+from nextmv.deprecated import deprecated
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationEnsembleMixin:
+    """
+    Mixin class for managing app ensembles within an application.
+    """
+
+    def delete_ensemble_definition(self: "Application", ensemble_definition_id: str) -> None:
+        """
+        Delete an ensemble definition.
+
+        Parameters
+        ----------
+        ensemble_definition_id : str
+            ID of the ensemble definition to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_ensemble_definition("development-ensemble-definition")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.ensembles_endpoint}/{ensemble_definition_id}",
+        )
+
+    def ensemble_definition(self: "Application", ensemble_definition_id: str) -> EnsembleDefinition:
+        """
+        Get an ensemble definition.
+
+        Parameters
+        ----------
+        ensemble_definition_id : str
+            ID of the ensemble definition to retrieve.
+
+        Returns
+        -------
+        EnsembleDefintion
+            The requested ensemble definition details.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> ensemble_definition = app.ensemble_definition("instance-123")
+        >>> print(ensemble_definition.name)
+        'Production Ensemble Definition'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.ensembles_endpoint}/{ensemble_definition_id}",
+        )
+
+        return EnsembleDefinition.from_dict(response.json())
+
+    def list_ensemble_definitions(self: "Application") -> list[EnsembleDefinition]:
+        """
+        List all ensemble_definitions.
+
+        Returns
+        -------
+        list[EnsembleDefinition]
+            List of all ensemble definitions associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> ensemble_definitions = app.list_ensemble_definitions()
+        >>> for ensemble_definition in ensemble_definitions:
+        ...     print(ensemble_definition.name)
+        'Development Ensemble Definition'
+        'Production Ensemble Definition'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.ensembles_endpoint}",
+        )
+
+        return [EnsembleDefinition.from_dict(ensemble_definition) for ensemble_definition in response.json()["items"]]
+
+    def new_ensemble_defintion(
+        self: "Application",
+        id: str,
+        run_groups: list[RunGroup],
+        rules: list[EvaluationRule],
+        name: str | None = None,
+        description: str | None = None,
+    ) -> EnsembleDefinition:
+        """
+        !!! warning
+            `new_ensemble_defintion` is deprecated, use `new_ensemble_definition` instead.
+
+        Create a new ensemble definition.
+
+        Parameters
+        ----------
+        id: str
+            ID of the ensemble defintion.
+        run_groups: list[RunGroup]
+            Information to facilitate the execution of child runs.
+        rules: list[EvaluationRule]
+            Information to facilitate the selection of
+            a result for the ensemble run from child runs.
+        name: Optional[str]
+            Name of the ensemble definition.
+        description: Optional[str]
+            Description of the ensemble definition.
+        """
+
+        deprecated(
+            name="new_ensemble_defintion",
+            reason="`Application.new_ensemble_defintion` is deprecated, use `new_ensemble_definition` instead",
+        )
+
+        return self.new_ensemble_definition(
+            run_groups=run_groups,
+            rules=rules,
+            id=id,
+            name=name,
+            description=description,
+        )
+
+    def new_ensemble_definition(
+        self: "Application",
+        run_groups: list[RunGroup],
+        rules: list[EvaluationRule],
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> EnsembleDefinition:
+        """
+        Create a new ensemble definition.
+
+        Parameters
+        ----------
+        run_groups: list[RunGroup]
+            Information to facilitate the execution of child runs.
+        rules: list[EvaluationRule]
+            Information to facilitate the selection of
+            a result for the ensemble run from child runs.
+        id: str | None, default=None
+            ID of the ensemble definition. If not provided, a unique ID will be
+            generated with the prefix 'ensemble-'.
+        name: Optional[str]
+            Name of the ensemble definition. If not provided, the ID will be used.
+        description: Optional[str]
+            Description of the ensemble definition. If not provided, the name will be used.
+        """
+
+        if len(run_groups) == 0:
+            raise ValueError("at least one run group must be defined to create an ensemble definition")
+
+        if len(rules) == 0:
+            raise ValueError("at least one evaluation rule must be defined to create an ensemble definition")
+
+        if id is None or id == "":
+            id = safe_id(prefix="ensemble")
+        if name is None or name == "":
+            name = id
+        if description is None or description == "":
+            description = name
+
+        payload = {
+            "id": id,
+            "run_groups": [run_group.to_dict() for run_group in run_groups],
+            "rules": [rule.to_dict() for rule in rules],
+            "name": name,
+            "description": description,
+        }
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.ensembles_endpoint}",
+            payload=payload,
+        )
+
+        return EnsembleDefinition.from_dict(response.json())
+
+    def update_ensemble_definition(
+        self: "Application",
+        id: str,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> EnsembleDefinition:
+        """
+        Update an ensemble definition.
+
+        Parameters
+        ----------
+        id : str
+            ID of the ensemble definition to update.
+        name : Optional[str], default=None
+            Optional name of the ensemble definition.
+        description : Optional[str], default=None
+            Optional description of the ensemble definition.
+
+        Returns
+        -------
+        EnsembleDefinition
+            The updated ensemble definition.
+
+        Raises
+        ------
+        ValueError
+            If neither name nor description is updated
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        payload = {}
+
+        if name is None and description is None:
+            raise ValueError("Must define at least one value among name and description to modify")
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+
+        response = self.client.request(
+            method="PATCH",
+            endpoint=f"{self.ensembles_endpoint}/{id}",
+            payload=payload,
+        )
+
+        return EnsembleDefinition.from_dict(response.json())

nextmv/cloud/application/_input_set.py

@@ -0,0 +1,263 @@
+"""
+Application mixin for managing app input sets.
+"""
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from nextmv.cloud.input_set import InputSet, ManagedInput
+from nextmv.safe import safe_id
+
+if TYPE_CHECKING:
+    from . import Application
+
+
+class ApplicationInputSetMixin:
+    """
+    Mixin class for managing app input sets within an application.
+    """
+
+    def delete_input_set(self: "Application", input_set_id: str) -> None:
+        """
+        Delete an input set.
+
+        Deletes an input set along with all the associated information.
+
+        Parameters
+        ----------
+        input_set_id : str
+            ID of the input set to delete.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> app.delete_input_set("input-set-123")
+        """
+
+        _ = self.client.request(
+            method="DELETE",
+            endpoint=f"{self.experiments_endpoint}/inputsets/{input_set_id}",
+        )
+
+    def input_set(self: "Application", input_set_id: str) -> InputSet:
+        """
+        Get an input set.
+
+        Parameters
+        ----------
+        input_set_id : str
+            ID of the input set to retrieve.
+
+        Returns
+        -------
+        InputSet
+            The requested input set.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> input_set = app.input_set("input-set-123")
+        >>> print(input_set.name)
+        'My Input Set'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/inputsets/{input_set_id}",
+        )
+
+        return InputSet.from_dict(response.json())
+
+    def list_input_sets(self: "Application") -> list[InputSet]:
+        """
+        List all input sets.
+
+        Returns
+        -------
+        list[InputSet]
+            List of all input sets associated with this application.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+
+        Examples
+        --------
+        >>> input_sets = app.list_input_sets()
+        >>> for input_set in input_sets:
+        ...     print(input_set.name)
+        'Input Set 1'
+        'Input Set 2'
+        """
+
+        response = self.client.request(
+            method="GET",
+            endpoint=f"{self.experiments_endpoint}/inputsets",
+        )
+
+        return [InputSet.from_dict(input_set) for input_set in response.json()]
+
+    def new_input_set(
+        self: "Application",
+        id: str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        end_time: datetime | None = None,
+        instance_id: str | None = None,
+        maximum_runs: int | None = None,
+        run_ids: list[str] | None = None,
+        start_time: datetime | None = None,
+        inputs: list[ManagedInput] | None = None,
+    ) -> InputSet:
+        """
+        Create a new input set. You can create an input set from three
+        different methodologies:
+
+        1. Using `instance_id`, `start_time`, `end_time` and `maximum_runs`.
+           Instance runs will be obtained from the application matching the
+           criteria of dates and maximum number of runs.
+        2. Using `run_ids`. The input set will be created using the list of
+           runs specified by the user.
+        3. Using `inputs`. The input set will be created using the list of
+           inputs specified by the user. This is useful for creating an input
+           set from a list of inputs that are already available in the
+           application.
+
+        Parameters
+        ----------
+        id: str | None = None
+            ID of the input set, will be generated if not provided.
+        name: str | None = None
+            Name of the input set. If not provided, the ID will be used as
+            the name.
+        description: Optional[str]
+            Optional description of the input set.
+        end_time: Optional[datetime]
+            End time of the input set. This is used to filter the runs
+            associated with the input set.
+        instance_id: Optional[str]
+            ID of the instance to use for the input set. This is used to
+            filter the runs associated with the input set. If not provided,
+            the application's `default_instance_id` is used.
+        maximum_runs: Optional[int]
+            Maximum number of runs to use for the input set. This is used to
+            filter the runs associated with the input set. If not provided,
+            all runs are used.
+        run_ids: Optional[list[str]]
+            List of run IDs to use for the input set.
+        start_time: Optional[datetime]
+            Start time of the input set. This is used to filter the runs
+            associated with the input set.
+        inputs: Optional[list[ManagedInput]]
+            List of inputs to use for the input set. This is used to create
+            the input set from a list of inputs that are already available in
+            the application.
+
+        Returns
+        -------
+        InputSet
+            The new input set.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        # Generate ID if not provided
+        if id is None or id == "":
+            id = safe_id("input-set")
+
+        # Use ID as name if name not provided
+        if name is None or name == "":
+            name = id
+
+        payload = {
+            "id": id,
+            "name": name,
+        }
+        if description is not None:
+            payload["description"] = description
+        if end_time is not None:
+            payload["end_time"] = end_time.isoformat()
+        if instance_id is not None:
+            payload["instance_id"] = instance_id
+        if maximum_runs is not None:
+            payload["maximum_runs"] = maximum_runs
+        if run_ids is not None:
+            payload["run_ids"] = run_ids
+        if start_time is not None:
+            payload["start_time"] = start_time.isoformat()
+        if inputs is not None:
+            payload["inputs"] = [input.to_dict() for input in inputs]
+
+        response = self.client.request(
+            method="POST",
+            endpoint=f"{self.experiments_endpoint}/inputsets",
+            payload=payload,
+        )
+
+        return InputSet.from_dict(response.json())
+
+    def update_input_set(
+        self: "Application",
+        id: str,
+        name: str | None = None,
+        description: str | None = None,
+        inputs: list[ManagedInput] | None = None,
+    ) -> InputSet:
+        """
+        Update an input set.
+
+        Parameters
+        ----------
+        id : str
+            ID of the input set to update.
+        name : Optional[str], default=None
+            Optional name of the input set.
+        description : Optional[str], default=None
+            Optional description of the input set.
+        inputs: Optional[list[ManagedInput]]
+            List of inputs to use for the input set. This is used to create
+            the input set from a list of inputs that are already available in
+            the application.
+
+        Returns
+        -------
+        Instance
+            The updated instance.
+
+        Raises
+        ------
+        requests.HTTPError
+            If the response status code is not 2xx.
+        """
+
+        # Get the input set as it currently exsits.
+        input_set = self.input_set(id)
+        input_set_dict = input_set.to_dict()
+        payload = input_set_dict.copy()
+
+        if name is not None:
+            payload["name"] = name
+        if description is not None:
+            payload["description"] = description
+        if inputs is not None:
+            payload["inputs"] = [input.to_dict() for input in inputs]
+
+        response = self.client.request(
+            method="PUT",
+            endpoint=f"{self.experiments_endpoint}/inputsets/{id}",
+            payload=payload,
+        )
+
+        return InputSet.from_dict(response.json())