Towards application scaffolding

Author: sebastian-quintero

nextmv/nextmv/cloud/application.py

@@ -29,6 +29,7 @@
 import tarfile
 import tempfile
 import time
+import uuid
 from collections.abc import Callable
 from dataclasses import dataclass
 from datetime import datetime
@@ -311,6 +312,156 @@ def __post_init__(self):
         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.
+        app_dir = os.path.join(destination_dir, name)
+        os.makedirs(app_dir, 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(app_dir, 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,
+        )
+
+    @classmethod
+    def new(
+        cls,
+        client: Client,
+        name: str,
+        id: Optional[str] = None,
+        description: Optional[str] = None,
+        is_workflow: Optional[bool] = None,
+        exist_ok: bool = False,
+    ) -> "Application":
+        """
+        Create a new application directly in Nextmv Cloud.
+
+        The application is created as an empty shell, and executable code must
+        be pushed to the app before running it remotely.
+
+        Parameters
+        ----------
+        client : Client
+            Client to use for interacting with the Nextmv Cloud API.
+        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.
+        is_workflow : bool, optional
+            Whether the application is a Decision Workflow.
+        exist_ok : bool, default=False
+            If True and an application with the same ID already exists,
+            return the existing application instead of creating a new one.
+
+        Returns
+        -------
+        Application
+            The newly created (or existing) application.
+
+        Examples
+        --------
+        >>> from nextmv.cloud import Client
+        >>> client = Client(api_key="your-api-key")
+        >>> app = Application.new(client=client, name="My New App", id="my-app")
+        """
+
+        if exist_ok and cls.exists(client=client, id=id):
+            return Application(client=client, id=id)
+
+        payload = {
+            "name": name,
+        }
+
+        if description is not None:
+            payload["description"] = description
+        if id is not None:
+            payload["id"] = id
+        if is_workflow is not None:
+            payload["is_pipeline"] = is_workflow
+
+        response = client.request(
+            method="POST",
+            endpoint="v1/applications",
+            payload=payload,
+        )
+
+        return cls(client=client, id=response.json()["id"])
+
     def acceptance_test(self, acceptance_test_id: str) -> AcceptanceTest:
         """
         Retrieve details of an acceptance test.
@@ -902,69 +1053,6 @@ def managed_input(self, managed_input_id: str) -> ManagedInput:
 
         return ManagedInput.from_dict(response.json())
 
-    @classmethod
-    def new(
-        cls,
-        client: Client,
-        name: str,
-        id: Optional[str] = None,
-        description: Optional[str] = None,
-        is_workflow: Optional[bool] = None,
-        exist_ok: bool = False,
-    ) -> "Application":
-        """
-        Create a new application.
-
-        Parameters
-        ----------
-        client : Client
-            Client to use for interacting with the Nextmv Cloud API.
-        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.
-        is_workflow : bool, optional
-            Whether the application is a Decision Workflow.
-        exist_ok : bool, default=False
-            If True and an application with the same ID already exists,
-            return the existing application instead of creating a new one.
-
-        Returns
-        -------
-        Application
-            The newly created (or existing) application.
-
-        Examples
-        --------
-        >>> from nextmv.cloud import Client
-        >>> client = Client(api_key="your-api-key")
-        >>> app = Application.new(client=client, name="My New App", id="my-app")
-        """
-
-        if exist_ok and cls.exists(client=client, id=id):
-            return Application(client=client, id=id)
-
-        payload = {
-            "name": name,
-        }
-
-        if description is not None:
-            payload["description"] = description
-        if id is not None:
-            payload["id"] = id
-        if is_workflow is not None:
-            payload["is_pipeline"] = is_workflow
-
-        response = client.request(
-            method="POST",
-            endpoint="v1/applications",
-            payload=payload,
-        )
-
-        return cls(client=client, id=response.json()["id"])
-
     def new_acceptance_test(
         self,
         candidate_instance_id: str,

nextmv/nextmv/cloud/manifest.py

@@ -322,6 +322,7 @@ class ManifestPython(BaseModel):
     from the app bundle.
     """
 
+
 class ManifestOptionUI(BaseModel):
     """
     UI attributes for an option in the manifest.
@@ -360,6 +361,7 @@ class ManifestOptionUI(BaseModel):
     hidden_from: Optional[list[str]] = None
     """A list of team roles for which this option will be hidden in the UI."""
 
+
 class ManifestOption(BaseModel):
     """
     An option for the decision model that is recorded in the manifest.
@@ -429,7 +431,6 @@ class ManifestOption(BaseModel):
     ui: Optional[ManifestOptionUI] = None
     """Optional UI attributes for the option."""
 
-
     @classmethod
     def from_option(cls, option: Option) -> "ManifestOption":
         """
@@ -483,7 +484,9 @@ def from_option(cls, option: Option) -> "ManifestOption":
             ui=ManifestOptionUI(
                 control_type=option.control_type,
                 hidden_from=option.hidden_from,
-            ) if option.control_type or option.hidden_from else None,
+            )
+            if option.control_type or option.hidden_from
+            else None,
         )
 
     def to_option(self) -> Option:
@@ -534,6 +537,7 @@ def to_option(self) -> Option:
             hidden_from=self.ui.hidden_from if self.ui else None,
         )
 
+
 class ManifestValidation(BaseModel):
     """
     Validation rules for options in the manifest.
@@ -569,6 +573,7 @@ class ManifestValidation(BaseModel):
     created if any of the rules of the options are violated.
     """
 
+
 class ManifestOptions(BaseModel):
     """
     Options for the decision model.
@@ -649,9 +654,10 @@ def from_options(cls, options: Options, validation: OptionsEnforcement = None) -
         return cls(
             strict=validation.strict if validation else False,
             validation=ManifestValidation(enforce="all" if validation and validation.validation_enforce else "none"),
-            items=items
+            items=items,
         )
 
+
 class ManifestConfiguration(BaseModel):
     """
     Configuration for the decision model.
@@ -749,14 +755,17 @@ class Manifest(BaseModel):
     """The files to include (or exclude) in the app. This is mandatory."""
 
     runtime: ManifestRuntime = ManifestRuntime.PYTHON
-    """The runtime to use for the app.
-
-    It provides the environment in which the app runs. This is mandatory.
+    """
+    The runtime to use for the app. It provides the environment in which the
+    app runs. This is mandatory.
     """
     type: ManifestType = ManifestType.PYTHON
-    """Type of application, based on the programming language. This is mandatory."""
+    """
+    Type of application, based on the programming language. This is mandatory.
+    """
     build: Optional[ManifestBuild] = None
-    """Build-specific attributes.
+    """
+    Build-specific attributes.
 
     The `build.command` to run to build the app. This command will be executed
     without a shell, i.e., directly. The command must exit with a status of 0
@@ -770,7 +779,8 @@ class Manifest(BaseModel):
         validation_alias=AliasChoices("pre-push", "pre_push"),
         default=None,
     )
-    """A command to run before the app is pushed to the Nextmv Cloud.
+    """
+    A command to run before the app is pushed to the Nextmv Cloud.
 
     This command can be used to compile a binary, run tests or similar tasks.
     One difference with what is specified under build, is that the command will
@@ -780,15 +790,14 @@ class Manifest(BaseModel):
     pushed (after the build command).
     """
     python: Optional[ManifestPython] = None
-    """Python-specific attributes.
-
-    Only for Python apps. Contains further Python-specific attributes.
+    """
+    Python-specific attributes. Only for Python apps. Contains further
+    Python-specific attributes.
     """
     configuration: Optional[ManifestConfiguration] = None
-    """Configuration for the decision model.
-
-    A list of options for the decision model. An option is a parameter that
-    configures the decision model.
+    """
+    Configuration for the decision model. A list of options for the decision
+    model. An option is a parameter that configures the decision model.
     """
 
     @classmethod
@@ -1041,11 +1050,8 @@ def from_options(cls, options: Options, validation: OptionsEnforcement = None) -
             type=ManifestType.PYTHON,
             python=ManifestPython(pip_requirements="requirements.txt"),
             configuration=ManifestConfiguration(
-                options= ManifestOptions.from_options(
-                    options=options,
-                    validation=validation
-                ),
-            )
+                options=ManifestOptions.from_options(options=options, validation=validation),
+            ),
         )
 
         return manifest

nextmv/nextmv/default_app/README.md

@@ -0,0 +1,17 @@
+# Nextmv Application
+
+This is the basic structure of a Nextmv application.
+
+```text
+├── app.yaml
+├── README.md
+├── requirements.txt
+└── src
+```
+
+* `app.yaml`: App manifest, containing the configuration to run the app
+  remotely on Nextmv Cloud.
+* `README.md`: Description of the app.
+* `requirements.txt`: Python dependencies for the app.
+* `src/`: Source code for the app. The `main.py` file is the entry point for
+  the app.

nextmv/nextmv/default_app/app.yaml

@@ -0,0 +1,11 @@
+# This manifest holds the information the app needs to run on the Nextmv Cloud.
+type: python
+runtime: ghcr.io/nextmv-io/runtime/python:3.11
+python:
+  # All listed packages will get bundled with the app.
+  pip-requirements: requirements.txt
+
+# List all files/directories that should be included in the app. Globbing
+# (e.g.: configs/*.json) is supported.
+files:
+  - src/

nextmv/nextmv/default_app/requirements.txt

@@ -0,0 +1,2 @@
+nextmv>=0.29.3
+plotly>=6.2.0