nextmv 0.33.0__py3-none-any.whl → 0.34.0__py3-none-any.whl

nextmv/local/local.py

@@ -36,7 +36,7 @@ LOGS_KEY = "logs"
 """
 Logs key constant used for identifying logs in the run output.
 """
-LOGS_FILE = "stderr.log"
+LOGS_FILE = "logs.log"
 """
 Constant used for identifying the file used for logging.
 """

nextmv/manifest.py

@@ -11,6 +11,8 @@ ManifestType
     Enum for application types based on programming language.
 ManifestRuntime
     Enum for runtime environments where apps run on Nextmv.
+ManifestPythonArch
+    Enum for target architecture for bundling Python apps.
 ManifestBuild
     Class for build-specific attributes in the manifest.
 ManifestPythonModel
@@ -38,6 +40,11 @@ ManifestConfiguration
 Manifest
     Main class representing an app manifest for Nextmv.
 
+Functions
+---------
+default_python_manifest
+    Creates a default Python manifest as a starting point for applications.
+
 Constants
 --------
 MANIFEST_FILE_NAME
@@ -331,7 +338,7 @@ class ManifestPython(BaseModel):
 
     Parameters
     ----------
-    pip_requirements : Optional[str], default=None
+    pip_requirements : Optional[Union[str, list[str]]], default=None
         Path to a requirements.txt file containing (additional) Python
         dependencies that will be bundled with the app. Alternatively, you can provide a
         list of strings, each representing a package to install, e.g.,
@@ -357,19 +364,25 @@ class ManifestPython(BaseModel):
         validation_alias=AliasChoices("pip-requirements", "pip_requirements"),
         default=None,
     )
-    """Path to a requirements.txt file.
+    """
+    Path to a requirements.txt file or list of packages.
 
     Contains (additional) Python dependencies that will be bundled with the
-    app.
+    app. Can be either a string path to a requirements.txt file or a list
+    of package specifications.
     """
     arch: Optional[ManifestPythonArch] = None
-    """The architecture this model is meant to run on. One of "arm64" or "amd64". Uses
-    "arm64" if not specified."""
+    """
+    The architecture this model is meant to run on. One of "arm64" or "amd64". Uses
+    "arm64" if not specified.
+    """
     version: Optional[Union[str, float]] = None
-    """The Python version this model is meant to run with. Uses "3.11" if not specified.
+    """
+    The Python version this model is meant to run with. Uses "3.11" if not specified.
     """
     model: Optional[ManifestPythonModel] = None
-    """Information about an encoded decision model.
+    """
+    Information about an encoded decision model.
 
     As handled via mlflow. This information is used to load the decision model
     from the app bundle.
@@ -378,6 +391,31 @@ class ManifestPython(BaseModel):
     @field_validator("version", mode="before")
     @classmethod
     def validate_version(cls, v: Optional[Union[str, float]]) -> Optional[str]:
+        """
+        Validate and convert the Python version field to a string.
+
+        This validator allows the version to be specified as either a float or string
+        in the manifest for convenience, but ensures it's stored internally as a string.
+
+        Parameters
+        ----------
+        v : Optional[Union[str, float]]
+            The version value to validate. Can be None, a string, or a float.
+
+        Returns
+        -------
+        Optional[str]
+            The version as a string, or None if the input was None.
+
+        Examples
+        --------
+        >>> ManifestPython.validate_version(3.11)
+        '3.11'
+        >>> ManifestPython.validate_version("3.11")
+        '3.11'
+        >>> ManifestPython.validate_version(None) is None
+        True
+        """
         # We allow the version to be a float in the manifest for convenience, but we want
         # to store it as a string internally.
         if v is None:
@@ -912,7 +950,23 @@ class ManifestContent(BaseModel):
     """Configuration for multi-file content format."""
 
     def model_post_init(self, __context) -> None:
-        """Post-initialization to validate fields."""
+        """
+        Post-initialization validation to ensure format field contains valid values.
+
+        This method is automatically called by Pydantic after the model is initialized
+        to validate that the format field contains one of the acceptable values.
+
+        Parameters
+        ----------
+        __context : Any
+            Pydantic context (unused in this implementation).
+
+        Raises
+        ------
+        ValueError
+            If the format field contains an invalid value that is not one of the
+            acceptable formats (JSON, MULTI_FILE, or CSV_ARCHIVE).
+        """
         acceptable_formats = [InputFormat.JSON, InputFormat.MULTI_FILE, InputFormat.CSV_ARCHIVE]
         if self.format not in acceptable_formats:
             raise ValueError(f"Invalid format: {self.format}. Must be one of {acceptable_formats}.")
@@ -1019,17 +1073,28 @@ class Manifest(BaseModel):
     ['main.py', 'model_logic/']
     """
 
-    files: list[str]
-    """The files to include (or exclude) in the app. This is mandatory."""
-
+    type: ManifestType = ManifestType.PYTHON
+    """
+    Type of application, based on the programming language. 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.
     """
-    type: ManifestType = ManifestType.PYTHON
+    python: Optional[ManifestPython] = None
     """
-    Type of application, based on the programming language. This is mandatory.
+    Python-specific attributes. Only for Python apps. Contains further
+    Python-specific attributes.
+    """
+    files: list[str] = Field(
+        default_factory=list,
+    )
+    """The files to include (or exclude) in the app. This is mandatory."""
+    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.
     """
     build: Optional[ManifestBuild] = None
     """
@@ -1057,16 +1122,6 @@ class Manifest(BaseModel):
     process. This command is executed just before the app gets bundled and
     pushed (after the build command).
     """
-    python: Optional[ManifestPython] = None
-    """
-    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.
-    """
     entrypoint: Optional[str] = None
     """
     Optional entrypoint for the decision model. When not specified, the
@@ -1078,6 +1133,26 @@ class Manifest(BaseModel):
     """
 
     def model_post_init(self, __context) -> None:
+        """
+        Post-initialization to set default entrypoint based on runtime if not specified.
+
+        This method is automatically called by Pydantic after the model is initialized.
+        If no entrypoint is provided, it sets a default entrypoint based on the runtime:
+        - Python runtimes (PYTHON, HEXALY, PYOMO, CUOPT): "./main.py"
+        - DEFAULT runtime: "./main"
+        - JAVA runtime: "./main.jar"
+
+        Parameters
+        ----------
+        __context : Any
+            Pydantic context (unused in this implementation).
+
+        Raises
+        ------
+        ValueError
+            If no entrypoint is provided and the runtime cannot be resolved to
+            establish a default entrypoint.
+        """
         if self.entrypoint is None:
             if self.runtime in (
                 ManifestRuntime.PYTHON,
@@ -1170,7 +1245,14 @@ class Manifest(BaseModel):
         """
 
         with open(os.path.join(dirpath, MANIFEST_FILE_NAME), "w") as file:
-            yaml.dump(self.to_dict(), file)
+            yaml.dump(
+                self.to_dict(),
+                file,
+                sort_keys=False,
+                default_flow_style=False,
+                indent=2,
+                width=120,
+            )
 
     def extract_options(self) -> Optional[Options]:
         """
@@ -1352,3 +1434,31 @@ class Manifest(BaseModel):
         )
 
         return manifest
+
+
+def default_python_manifest() -> Manifest:
+    """
+    Creates a default Python manifest as a starting point for applications
+    being executed on the Nextmv Platform.
+
+    You can import the `default_python_manifest` function directly from `nextmv`:
+
+    ```python
+    from nextmv import default_python_manifest
+    ```
+
+    Returns
+    -------
+    Manifest
+        A default Python manifest with common settings.
+    """
+
+    m = Manifest(
+        files=["main.py"],
+        runtime=ManifestRuntime.PYTHON,
+        type=ManifestType.PYTHON,
+        python=ManifestPython(pip_requirements="requirements.txt"),
+    )
+    m.entrypoint = None  # TODO: change this when we are ready for the entrypoint.
+
+    return m

nextmv/run.py

@@ -52,7 +52,7 @@ from pydantic import AliasChoices, Field, field_validator
 from nextmv._serialization import serialize_json
 from nextmv.base_model import BaseModel
 from nextmv.input import Input, InputFormat
-from nextmv.output import Output, OutputFormat
+from nextmv.output import Asset, Output, OutputFormat, Statistics
 from nextmv.status import Status, StatusV2
 
 
@@ -687,6 +687,56 @@ class Metadata(BaseModel):
     """Deprecated: use status_v2."""
 
 
+class SyncedRun(BaseModel):
+    """
+    Information about a run that has been synced to a remote application.
+
+    You can import the `SyncedRun` class directly from `nextmv`:
+
+    ```python
+    from nextmv import SyncedRun
+    ```
+
+    Parameters
+    ----------
+    run_id : str
+        ID of the synced remote run. When the `Application.sync` method is
+        used, this field marks the association between the local run (`id`) and
+        the remote run (`synced_run.id`).
+    synced_at : datetime
+        Timestamp when the run was synced with the remote run.
+    app_id : str
+        The ID of the remote application that the local run was synced to.
+    instance_id : Optional[str], optional
+        The instance of the remote application that the local run was synced
+        to. This field is optional and may be None. If it is not specified, it
+        indicates that the run was synced against the default instance of the
+        app. Defaults to None.
+    """
+
+    run_id: str
+    """
+    ID of the synced remote run. When the `Application.sync` method is used,
+    this field marks the association between the local run (`id`) and the
+    remote run (`synced_run.id`)
+    """
+    synced_at: datetime
+    """
+    Timestamp when the run was synced with the remote run.
+    """
+    app_id: str
+    """
+    The ID of the remote application that the local run was synced to.
+    """
+
+    instance_id: Optional[str] = None
+    """
+    The instance of the remote application that the local run was synced to.
+    This field is optional and may be None. If it is not specified, it
+    indicates that the run was synced against the default instance of the app.
+    """
+
+
 class RunInformation(BaseModel):
     """
     Information of a run.
@@ -727,19 +777,18 @@ class RunInformation(BaseModel):
     """
     URL to the run in the Nextmv console.
     """
-    synced_run_id: Optional[str] = None
-    """
-    ID of the synced remote run, if applicable. When the `Application.sync`
-    method is used, this field marks the association between the local run
-    (`id`) and the remote run (`synced_run_id`). This field is None if the run
-    was not created using `Application.sync` or if the run has not been synced
-    yet.
+    synced_runs: Optional[list[SyncedRun]] = None
     """
-    synced_at: Optional[datetime] = None
-    """
-    Timestamp when the run was synced with the remote run. This field is
-    None if the run was not created using `Application.sync` or if the run
-    has not been synced yet.
+    List of synced runs associated with this run, if applicable. When the
+    `Application.sync` method is used, this field contains the associations
+    between the local run (`id`) and the remote runs (`synced_run.id`). This
+    field is None if the run was not created using `Application.sync` or if the
+    run has not been synced yet. It is possible to sync a single local run to
+    multiple remote runs. A remote run is identified by its application ID and
+    instance (if applicable). A local run cannot be synced to a remote run if
+    it is already present, this is, if there exists a record in the list with
+    the same application ID and instance. If there is not a repeated remote
+    run, a new record is added to the list.
     """
 
     def to_run(self) -> Run:
@@ -817,6 +866,83 @@ class RunInformation(BaseModel):
             input_set_id=None,
         )
 
+    def add_synced_run(self, synced_run: SyncedRun) -> bool:
+        """
+        Add a synced run to the RunInformation.
+
+        This method adds a `SyncedRun` instance to the list of synced runs
+        associated with this `RunInformation`. If the list is None, it
+        initializes it first. If the run has already been synced, then it is
+        not added to the list. A run is already synced if there exists a record
+        in the list with the same application ID. This method returns True if
+        the synced run was added, and False otherwise.
+
+        Parameters
+        ----------
+        synced_run : SyncedRun
+            The SyncedRun instance to add.
+
+        Returns
+        -------
+        bool
+            True if the synced run was added, False if it was already present.
+        """
+
+        if self.synced_runs is None:
+            self.synced_runs = [synced_run]
+
+            return True
+
+        if synced_run.instance_id is None:
+            for existing_run in self.synced_runs:
+                if existing_run.app_id == synced_run.app_id:
+                    return False
+        else:
+            for existing_run in self.synced_runs:
+                if existing_run.app_id == synced_run.app_id and existing_run.instance_id == synced_run.instance_id:
+                    return False
+
+        self.synced_runs.append(synced_run)
+
+        return True
+
+    def is_synced(self, app_id: str, instance_id: Optional[str] = None) -> tuple[SyncedRun, bool]:
+        """
+        Check if the run has been synced to a specific application and instance.
+
+        This method checks if there exists a `SyncedRun` in the list of synced
+        runs that matches the given application ID and optional instance ID.
+
+        Parameters
+        ----------
+        app_id : str
+            The application ID to check.
+        instance_id : Optional[str], optional
+            The instance ID to check. If None, only the application ID is
+            considered. Defaults to None.
+
+        Returns
+        -------
+        tuple[SyncedRun, bool]
+            A tuple containing the SyncedRun instance if found, and a boolean
+            indicating whether the run has been synced to the specified
+            application and instance.
+        """
+
+        if self.synced_runs is None:
+            return None, False
+
+        if instance_id is None:
+            for existing_run in self.synced_runs:
+                if existing_run.app_id == app_id:
+                    return existing_run, True
+        else:
+            for existing_run in self.synced_runs:
+                if existing_run.app_id == app_id and existing_run.instance_id == instance_id:
+                    return existing_run, True
+
+        return None, False
+
 
 class ErrorLog(BaseModel):
     """
@@ -1154,6 +1280,16 @@ class ExternalRunResult(BaseModel):
     """Error message of the run."""
     execution_duration: Optional[int] = None
     """Duration of the run, in milliseconds."""
+    statistics_upload_id: Optional[str] = None
+    """
+    ID of the statistics upload. Use this field when working with `CSV_ARCHIVE`
+    or `MULTI_FILE` output formats.
+    """
+    assets_upload_id: Optional[str] = None
+    """
+    ID of the assets upload. Use this field when working with `CSV_ARCHIVE`
+    or `MULTI_FILE` output formats.
+    """
 
     def __post_init_post_parse__(self):
         """
@@ -1265,6 +1401,18 @@ class TrackedRun:
         when working with `CSV_ARCHIVE` or `MULTI_FILE`. If both `output` and
         `output_dir_path` are specified, the `output` is ignored, and the files
         are saved in the directory instead. Defaults to None.
+    statistics : Statistics or dict[str, Any], optional
+        Statistics of the run being tracked. Only use this field if you want to
+        track statistics for `CSV_ARCHIVE` or `MULTI_FILE` output formats. If you
+        are working with `JSON` or `TEXT` output formats, this field will be
+        ignored, as the statistics are extracted directly from the `output`.
+        This field is optional. Defaults to None.
+    assets : list[Asset or dict[str, Any]], optional
+        Assets associated with the run being tracked. Only use this field if you
+        want to track assets for `CSV_ARCHIVE` or `MULTI_FILE` output formats.
+        If you are working with `JSON` or `TEXT` output formats, this field will
+        be ignored, as the assets are extracted directly from the `output`.
+        This field is optional. Defaults to None.
 
     Examples
     --------
@@ -1365,6 +1513,20 @@ class TrackedRun:
     `output_dir_path` are specified, the `output` is ignored, and the files
     are saved in the directory instead.
     """
+    statistics: Optional[Union[Statistics, dict[str, Any]]] = None
+    """
+    Statistics of the run being tracked. Only use this field if you want to
+    track statistics for `CSV_ARCHIVE` or `MULTI_FILE` output formats. If you
+    are working with `JSON` or `TEXT` output formats, this field will be
+    ignored, as the statistics are extracted directly from the `output`.
+    """
+    assets: Optional[list[Union[Asset, dict[str, Any]]]] = None
+    """
+    Assets associated with the run being tracked. Only use this field if you
+    want to track assets for `CSV_ARCHIVE` or `MULTI_FILE` output formats.
+    If you are working with `JSON` or `TEXT` output formats, this field will
+    be ignored, as the assets are extracted directly from the `output`.
+    """
 
     def __post_init__(self):  # noqa: C901
         """

{nextmv-0.33.0.dist-info → nextmv-0.34.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nextmv
-Version: 0.33.0
+Version: 0.34.0
 Summary: The all-purpose Python SDK for Nextmv
 Project-URL: Homepage, https://www.nextmv.io
 Project-URL: Documentation, https://nextmv-py.docs.nextmv.io/en/latest/nextmv/

{nextmv-0.33.0.dist-info → nextmv-0.34.0.dist-info}/RECORD

@@ -1,23 +1,23 @@
-nextmv/__about__.py,sha256=VyKoqs7qvl1UtyON_wE484wOoQ1-D2LWfsRhOrha9gg,24
+nextmv/__about__.py,sha256=R6JmJlUTOJ25ql5gmHiwKZDMDym2RLkSYwWgTeG9wAQ,24
 nextmv/__entrypoint__.py,sha256=dA0iwwHtrq6Z9w9FxmxKLoBGLyhe7jWtUAU-Y3PEgHg,1094
-nextmv/__init__.py,sha256=uM80mRRs2Ht2dP60DvxR11HmunFJ7EL7XUJHtKQi2qI,3683
+nextmv/__init__.py,sha256=C2f8MteVvvOX1Wj-0GFjfUt-0RzCT0zpLpLI2yyZQw8,3796
 nextmv/_serialization.py,sha256=JlSl6BL0M2Esf7F89GsGIZ__Pp8RnFRNM0UxYhuuYU4,2853
 nextmv/base_model.py,sha256=qmJ4AsYr9Yv01HQX_BERrn3229gyoZrYyP9tcyqNfeU,2311
 nextmv/deprecated.py,sha256=kEVfyQ-nT0v2ePXTNldjQG9uH5IlfQVy3L4tztIxwmU,1638
 nextmv/input.py,sha256=m9sVfO9ZL3F5i1l8amEtlWlbkekyUP4C3y9DduHWGFs,40211
 nextmv/logger.py,sha256=kNIbu46MisrzYe4T0hNMpWfRTKKacDVvbtQcNys_c_E,2513
-nextmv/manifest.py,sha256=jCu5RUl6bip4kTDh4zaD4PTYNOIGHWKm34kfXD_rpzw,45898
+nextmv/manifest.py,sha256=vo4GJk2yF6-6cA1M5YrynlXKqupH2vQE7HByph6ne4k,49256
 nextmv/model.py,sha256=vI3pSV3iTwjRPflar7nAg-6h98XRUyi9II5O2J06-Kc,15018
 nextmv/options.py,sha256=yPJu5lYMbV6YioMwAXv7ctpZUggLXKlZc9CqIbUFvE4,37895
 nextmv/output.py,sha256=HdvWYG3gIzwoXquulaEVI4LLchXJDjkbag0BkBPM0vQ,55128
 nextmv/polling.py,sha256=nfefvWI1smm-lIzaXE-4DMlojp6KXIvVi88XLJYUmo8,9724
-nextmv/run.py,sha256=lAWWkLml1C7wkXSvN8orBjudoz72Qv5ZCHCWY9e7xaY,45813
+nextmv/run.py,sha256=8B9hh-jWJpoMSJiDmgmXaqvmzTicWCn75UTJu7Nf7Cs,52401
 nextmv/safe.py,sha256=VAK4fGEurbLNji4Pg5Okga5XQSbI4aI9JJf95_68Z20,3867
 nextmv/status.py,sha256=SCDLhh2om3yeO5FxO0x-_RShQsZNXEpjHNdCGdb3VUI,2787
 nextmv/cloud/__init__.py,sha256=2wI72lhWq81BYv1OpS0OOTT5-3sivpX0H4z5ANPoLMc,5051
 nextmv/cloud/acceptance_test.py,sha256=ZEzCMrfJF-nUFr1nEr4IDgcoyavPhnanjFuPBJ79tAk,27731
 nextmv/cloud/account.py,sha256=jIdGNyI3l3dVh2PuriAwAOrEuWRM150WgzxcBMVBNRw,6058
-nextmv/cloud/application.py,sha256=zbirm_bbihnzhKsO8gAO_dJRAJV4FtXsQsSaismgt-I,139298
+nextmv/cloud/application.py,sha256=oUpw6I1r4u9Cn0pnlylWlm23hPgZKsg_vnBXbqTtU-w,139693
 nextmv/cloud/batch_experiment.py,sha256=13ciRpgBabMMTyazfdfEAymD3rTPrTAAorECsANxxuA,10397
 nextmv/cloud/client.py,sha256=E0DiUb377jvEnpXlRnfT1PGCI0Jm0lTUoX5VqeU91lk,18165
 nextmv/cloud/ensemble.py,sha256=glrRgyRFcEH12fNUhEl1FOo6xOTDEaF478dxfX0wj2Y,8604
@@ -38,13 +38,13 @@ nextmv/default_app/src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3
 nextmv/default_app/src/main.py,sha256=WWeN_xl_mcPhICl3rSCvdEjRkFXGmAnej88FhS-fAmc,884
 nextmv/default_app/src/visuals.py,sha256=WYK_YBnLmYo3TpVev1CpoNCuW5R7hk9QIkeCmvMn1Fs,1014
 nextmv/local/__init__.py,sha256=6BsoqlK4dw6X11_uKzz9gBPfxKpdiol2FYO8R3X73SE,116
-nextmv/local/application.py,sha256=qq14ihKxymg5NHqhU56qTu6lVmMYWLGYUJC4MrhWB68,45815
-nextmv/local/executor.py,sha256=ohAUrIRohcH_qGglK1hSFR0W6bPBSuMAcMwVkW5G4vM,24338
+nextmv/local/application.py,sha256=yJDlbQB_mh29Y541Mt6a6zyT3XutdtzjqSd0mlOeteo,47002
+nextmv/local/executor.py,sha256=7rxVkpyZ4GyTH7hjJX7rdM0hCo7_fSqX4EiA8YHZpC8,36624
 nextmv/local/geojson_handler.py,sha256=7FavJdkUonop-yskjis0x3qFGB8A5wZyoBUblw-bVhw,12540
-nextmv/local/local.py,sha256=wUHuoAXqJIZpTJBh056hmQuiPEjlZvLTR2BC6Ino-WI,2619
+nextmv/local/local.py,sha256=cp56UpI8h19Ob6Jvb_Ni0ceXH5Vv3ET_iPTDe6ftq3Y,2617
 nextmv/local/plotly_handler.py,sha256=bLb50e3AkVr_W-F6S7lXfeRdN60mG2jk3UElNmhoMWU,1930
 nextmv/local/runner.py,sha256=hwkITHrQG_J9TzxufnaP1mjLWG-iSsNQD66UFZY4pp4,8602
-nextmv-0.33.0.dist-info/METADATA,sha256=JRt0lALKQ1i0E_J2AhgozeUtC7kv_YGHsqK_-VDePsw,16008
-nextmv-0.33.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-nextmv-0.33.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
-nextmv-0.33.0.dist-info/RECORD,,
+nextmv-0.34.0.dist-info/METADATA,sha256=xaYGEjnGpH8t_ULjbHULvcEVtvMXNQ6B5Wx41tone0o,16008
+nextmv-0.34.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+nextmv-0.34.0.dist-info/licenses/LICENSE,sha256=ZIbK-sSWA-OZprjNbmJAglYRtl5_K4l9UwAV3PGJAPc,11349
+nextmv-0.34.0.dist-info/RECORD,,