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

nextmv/cloud/shadow.py

@@ -0,0 +1,190 @@
+"""
+Classes for working with Nextmv Cloud shadow tests.
+
+This module provides classes for interacting with shadow tests in Nextmv Cloud.
+It details the core data structures for these types of experiments.
+
+Classes
+-------
+TestComparison
+    A structure to define comparison parameters for tests.
+StartEvents
+    A structure to define start events for tests.
+TerminationEvents
+    A structure to define termination events for tests.
+ShadowTestMetadata
+    Metadata for a Nextmv Cloud shadow test.
+ShadowTest
+    A Nextmv Cloud shadow test definition.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import AliasChoices, Field
+
+from nextmv.base_model import BaseModel
+from nextmv.cloud.batch_experiment import ExperimentStatus
+from nextmv.run import Run
+
+
+class TestComparison(BaseModel):
+    """
+    A structure to define comparison parameters for tests.
+
+    You can import the `TestComparison` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TestComparison
+    ```
+
+    Parameters
+    ----------
+    baseline_instance_id : str
+        ID of the baseline instance for comparison.
+    candidate_instance_ids : list[str]
+        List of candidate instance IDs to compare against the baseline.
+    """
+
+    baseline_instance_id: str
+    """ID of the baseline instance for comparison."""
+    candidate_instance_ids: list[str]
+    """List of candidate instance IDs to compare against the baseline."""
+
+
+class StartEvents(BaseModel):
+    """
+    A structure to define start events for tests.
+
+    You can import the `StartEvents` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import StartEvents
+    ```
+
+    Parameters
+    ----------
+    time : datetime, optional
+        Scheduled time for the test to start.
+    """
+
+    time: datetime | None = None
+    """Scheduled time for the test to start."""
+
+
+class TerminationEvents(BaseModel):
+    """
+    A structure to define termination events for tests.
+
+    You can import the `TerminationEvents` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import TerminationEvents
+    ```
+
+    Parameters
+    ----------
+    time : datetime, optional
+        Scheduled time for the test to terminate.
+    """
+
+    maximum_runs: int
+    """
+    Maximum number of runs for the test. Min should be 1, max should be 300.
+    """
+    time: datetime | None = None
+    """
+    Scheduled time for the test to terminate. A zero value means no
+    limit.
+    """
+
+    def model_post_init(self, __context):
+        if self.maximum_runs < 1:
+            raise ValueError("maximum_runs must be at least 1")
+
+
+class ShadowTestMetadata(BaseModel):
+    """
+    Metadata for a Nextmv Cloud shadow test.
+
+    You can import the `ShadowTestMetadata` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ShadowTestMetadata
+    ```
+
+    Parameters
+    ----------
+    shadow_test_id : str, optional
+        The unique identifier of the shadow test.
+    name : str, optional
+        Name of the shadow test.
+    description : str, optional
+        Description of the shadow test.
+    app_id : str, optional
+        ID of the application to which the shadow test belongs.
+    created_at : datetime, optional
+        Creation date of the shadow test.
+    updated_at : datetime, optional
+        Last update date of the shadow test.
+    status : ExperimentStatus, optional
+        The current status of the shadow test.
+    """
+
+    shadow_test_id: str | None = Field(
+        serialization_alias="id",
+        validation_alias=AliasChoices("id", "shadow_test_id"),
+        default=None,
+    )
+    """The unique identifier of the shadow test."""
+    name: str | None = None
+    """Name of the shadow test."""
+    description: str | None = None
+    """Description of the shadow test."""
+    app_id: str | None = None
+    """ID of the application to which the shadow test belongs."""
+    created_at: datetime | None = None
+    """Creation date of the shadow test."""
+    updated_at: datetime | None = None
+    """Last update date of the shadow test."""
+    status: ExperimentStatus | None = None
+    """The current status of the shadow test."""
+
+
+class ShadowTest(ShadowTestMetadata):
+    """
+    A Nextmv Cloud shadow test definition.
+
+    A shadow test is a type of experiment where runs are executed in parallel
+    to compare different instances.
+
+    You can import the `ShadowTest` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import ShadowTest
+    ```
+
+    Parameters
+    ----------
+    completed_at : datetime, optional
+        Completion date of the shadow test, if applicable.
+    comparisons : list[TestComparison], optional
+        List of test comparisons defined in the shadow test.
+    start_events : StartEvents, optional
+        Start events for the shadow test.
+    termination_events : TerminationEvents, optional
+        Termination events for the shadow test.
+    """
+
+    completed_at: datetime | None = None
+    """Completion date of the shadow test, if applicable."""
+    comparisons: list[TestComparison] | None = None
+    """List of test comparisons defined in the shadow test."""
+    start_events: StartEvents | None = None
+    """Start events for the shadow test."""
+    termination_events: TerminationEvents | None = None
+    """Termination events for the shadow test."""
+    grouped_distributional_summaries: list[dict[str, Any]] | None = None
+    """Grouped distributional summaries of the shadow test."""
+    runs: list[Run] | None = None
+    """List of runs in the shadow test."""

nextmv/cloud/url.py

@@ -0,0 +1,73 @@
+"""
+Module for declarations related to upload and download URLs in Nextmv Cloud.
+
+Classes
+-------
+DownloadURL
+    Represents a download URL for fetching content from Nextmv Cloud.
+UploadURL
+    Represents an upload URL for sending content to Nextmv Cloud.
+"""
+
+from nextmv.base_model import BaseModel
+
+
+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."""
+
+
+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."""

nextmv/cloud/version.py

@@ -1,4 +1,20 @@
-"""This module contains definitions for versions."""
+"""Manages application versions within the Nextmv Cloud API.
+
+This module provides data models for representing application versions,
+their executables, and associated requirements. These models are used
+for interacting with version-related endpoints of the Nextmv Cloud API,
+allowing users to define, retrieve, and manage different versions of their
+decision applications.
+
+Classes
+-------
+VersionExecutableRequirements
+    Defines the requirements for a version's executable, such as type and runtime.
+VersionExecutable
+    Represents the executable artifact for a specific application version.
+Version
+    Represents a version of an application, linking to its executable and metadata.
+"""
 
 from datetime import datetime
 
@@ -6,7 +22,34 @@ from nextmv.base_model import BaseModel
 
 
 class VersionExecutableRequirements(BaseModel):
-    """Requirements for a version executable."""
+    """
+    Requirements for a version executable.
+
+    You can import the `VersionExecutableRequirements` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutableRequirements
+    ```
+
+    These requirements specify the environment and type of executable needed
+    to run a particular version of an application.
+
+    Parameters
+    ----------
+    executable_type : str
+        The type of the executable (e.g., "binary", "docker").
+    runtime : str
+        The runtime environment for the executable (e.g., "go", "python").
+
+    Examples
+    --------
+    >>> requirements = VersionExecutableRequirements(
+    ...     executable_type="binary",
+    ...     runtime="go1.x"
+    ... )
+    >>> print(requirements.executable_type)
+    binary
+    """
 
     executable_type: str
     """Type of the executable."""
@@ -15,7 +58,42 @@ class VersionExecutableRequirements(BaseModel):
 
 
 class VersionExecutable(BaseModel):
-    """Executable for a version."""
+    """
+    Executable for a version.
+
+    You can import the `VersionExecutable` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import VersionExecutable
+    ```
+
+    This class holds information about the actual executable file or image
+    associated with an application version, including who uploaded it and when.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version executable.
+    user_email : str
+        Email of the user who uploaded the executable.
+    uploaded_at : datetime
+        Timestamp indicating when the executable was uploaded.
+    requirements : VersionExecutableRequirements
+        The specific requirements for this executable.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="docker", runtime="custom")
+    >>> executable = VersionExecutable(
+    ...     id="exec-123",
+    ...     user_email="user@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> print(executable.id)
+    exec-123
+    """
 
     id: str
     """ID of the version."""
@@ -28,7 +106,57 @@ class VersionExecutable(BaseModel):
 
 
 class Version(BaseModel):
-    """A version of an application representing a code artifact or a compiled binary."""
+    """
+    A version of an application representing a code artifact or a compiled binary.
+
+    You can import the `Version` class directly from `cloud`:
+
+    ```python
+    from nextmv.cloud import Version
+    ```
+
+    This class encapsulates all details of a specific version of an application,
+    including its metadata, associated executable, and timestamps.
+
+    Parameters
+    ----------
+    id : str
+        Unique identifier for the version.
+    application_id : str
+        Identifier of the application to which this version belongs.
+    name : str
+        User-defined name for the version (e.g., "v1.0.0", "feature-branch-build").
+    description : str
+        A more detailed description of the version and its changes.
+    executable : VersionExecutable
+        The executable artifact associated with this version.
+    created_at : datetime
+        Timestamp indicating when the version was created.
+    updated_at : datetime
+        Timestamp indicating when the version was last updated.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> reqs = VersionExecutableRequirements(executable_type="binary", runtime="java11")
+    >>> exe = VersionExecutable(
+    ...     id="exec-abc",
+    ...     user_email="dev@example.com",
+    ...     uploaded_at=datetime.now(),
+    ...     requirements=reqs
+    ... )
+    >>> version_info = Version(
+    ...     id="ver-xyz",
+    ...     application_id="app-123",
+    ...     name="Initial Release",
+    ...     description="First stable release of the model.",
+    ...     executable=exe,
+    ...     created_at=datetime.now(),
+    ...     updated_at=datetime.now()
+    ... )
+    >>> print(version_info.name)
+    Initial Release
+    """
 
     id: str
     """ID of the version."""

nextmv/default_app/.gitignore

@@ -0,0 +1 @@
+.nextmv

nextmv/default_app/README.md

@@ -0,0 +1,32 @@
+# Nextmv application
+
+This is the basic structure of a Nextmv application.
+
+```text
+├── app.yaml
+├── main.py
+├── README.md
+├── requirements.txt
+└── src
+```
+
+* `app.yaml`: App manifest, containing the configuration to run the app
+  remotely on Nextmv Cloud.
+* `main.py`: Entry point for the app.
+* `README.md`: Description of the app.
+* `requirements.txt`: Python dependencies for the app.
+* `src/`: Source code for the app.
+
+A sample input file is also provided as `input.json`.
+
+1. Install packages.
+
+    ```bash
+    pip install -r requirements.txt
+    ```
+
+2. Run the app.
+
+    ```bash
+    cat input.json | python main.py
+    ```

nextmv/default_app/app.yaml

@@ -0,0 +1,12 @@
+# 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/
+  - main.py

nextmv/default_app/input.json

@@ -0,0 +1,5 @@
+{
+  "name": "Patches",
+  "radius": 6378,
+  "distance": 147.6
+}

nextmv/default_app/main.py

@@ -0,0 +1,37 @@
+from src.visuals import create_visuals
+
+import nextmv
+
+# Read the input from stdin.
+input = nextmv.load()
+name = input.data["name"]
+
+options = nextmv.Options(
+    nextmv.Option("details", bool, True, "Print details to logs. Default true.", False),
+)
+
+##### Insert model here
+
+# Print logs that render in the run view in Nextmv Console.
+message = f"Hello, {name}"
+nextmv.log(message)
+
+if options.details:
+    detail = f"You are {input.data['distance']} million km from the sun"
+    nextmv.log(detail)
+
+assets = create_visuals(name, input.data["radius"], input.data["distance"])
+
+# Write output and statistics.
+output = nextmv.Output(
+    options=options,
+    solution={"message": message},
+    statistics=nextmv.Statistics(
+        result=nextmv.ResultStatistics(
+            value=1.23,
+            custom={"message": message},
+        ),
+    ),
+    assets=assets,
+)
+nextmv.write(output)

nextmv/default_app/requirements.txt

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

nextmv/default_app/src/visuals.py

@@ -0,0 +1,36 @@
+import json
+
+import plotly.graph_objects as go
+
+import nextmv
+
+
+def create_visuals(name: str, radius: float, distance: float) -> list[nextmv.Asset]:
+    """Create a Plotly bar chart with radius and distance for a planet."""
+
+    fig = go.Figure()
+    fig.add_trace(
+        go.Bar(x=[name], y=[radius], name="Radius (km)", marker_color="red", opacity=0.5),
+    )
+    fig.add_trace(
+        go.Bar(x=[name], y=[distance], name="Distance (Millions km)", marker_color="blue", opacity=0.5),
+    )
+    fig.update_layout(
+        title="Radius and Distance by Planet", xaxis_title="Planet", yaxis_title="Values", barmode="group"
+    )
+    fig = fig.to_json()
+
+    assets = [
+        nextmv.Asset(
+            name="Plotly example",
+            content_type="json",
+            visual=nextmv.Visual(
+                visual_schema=nextmv.VisualSchema.PLOTLY,
+                visual_type="custom-tab",
+                label="Charts",
+            ),
+            content=[json.loads(fig)],
+        )
+    ]
+
+    return assets

nextmv/deprecated.py

@@ -0,0 +1,47 @@
+"""Utilities for handling deprecated functionality within the Nextmv Python SDK.
+
+This module provides tools to mark functions, methods, or features as deprecated,
+emitting appropriate warnings to users. These warnings inform users that the
+functionality will be removed in a future release and suggest alternative approaches.
+
+The main purpose of this module is to help with the smooth transition when
+API changes are necessary, giving users time to update their code before
+functionality is removed completely.
+"""
+
+import warnings
+
+
+def deprecated(name: str, reason: str) -> None:
+    """Mark functionality as deprecated with a warning message.
+
+    This function emits a DeprecationWarning when called, indicating that
+    the functionality will be removed in a future release.
+
+    Parameters
+    ----------
+    name : str
+        The name of the function, method, or feature being deprecated.
+    reason : str
+        The reason why the functionality is being deprecated, possibly
+        with suggestions for alternative approaches.
+
+    Notes
+    -----
+    This function temporarily changes the warning filter to ensure the
+    deprecation warning is shown, then resets it afterward.
+
+    Examples
+    --------
+    >>> def some_function():
+    ...     deprecated("feature_x", "Use feature_y instead")
+    ...     # function implementation
+    """
+
+    warnings.simplefilter("always", DeprecationWarning)
+    warnings.warn(
+        f"{name}: {reason}. This functionality will be removed in a future release",
+        category=DeprecationWarning,
+        stacklevel=2,
+    )
+    warnings.simplefilter("default", DeprecationWarning)