mainsequence 4.4.30__tar.gz → 4.4.32__tar.gz

{mainsequence-4.4.30 → mainsequence-4.4.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.30
+Version: 4.4.32
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.4.30 → mainsequence-4.4.32}/agent_scaffold/skills/platform_operations/orchestration_and_releases/SKILL.md

@@ -31,6 +31,8 @@ This skill is for:
 - freeze jobs to a project image
 - inspect job runs and logs
 - reason about project resources and resource releases
+- decide whether a `ResourceRelease` should opt into `automatic_deployment`
+- inspect automatic deployment run state for release rotations
 - create or review Streamlit dashboard deployment through project resources and `streamlit_dashboard` releases
 - review Artifact-based workflows in operational pipelines
 
@@ -96,6 +98,7 @@ Before changing orchestration or release behavior, collect or infer:
   - direct CLI/client job creation
   - repository-managed batch scheduling
   - Streamlit dashboard release creation
+- whether a `ResourceRelease` should be manually pinned or opted into repository-sync automatic deployment
 - whether Artifact inputs or outputs are part of the run
 - whether the job should be reproducible against a pinned image
 - for Streamlit dashboard deployment, the `README.md` resource next to `app.py`
@@ -113,6 +116,7 @@ For every non-trivial orchestration task, decide:
 5. Does the workflow depend on Artifacts?
 6. Is the task actually a release/resource problem instead of only a job problem?
 7. For Streamlit dashboard deployment, do the selected app resource, README resource, and project image all refer to the intended pushed commit?
+8. For a `ResourceRelease`, should repository sync be allowed to rotate the release automatically through `automatic_deployment`?
 
 ## Build Rules
 
@@ -218,6 +222,71 @@ That workflow exists to validate the contract in `apiTargetMode: "mock-json"` be
 
 Only publish the real FastAPI API after the AppComponent contract is stable.
 
+### 6.3 Automatic ResourceRelease deployment
+
+`automatic_deployment` is the automated deployment opt-in flag on a `ResourceRelease`. It means repository synchronization can rotate an existing release to the latest synced project commit for the same resource path.
+
+When `automatic_deployment=True`, repository-sync events may create a `ResourceReleaseAutomaticDeploymentRun` with source `repository_event`. That run:
+
+- reads the project's current synced commit
+- resolves the current project resource at the release's existing resource path
+- resolves the current adjacent `README.md` when the release kind requires one, such as Streamlit dashboards
+- creates or resolves the project image for that commit
+- redeploys the existing release to the current resource, README, and project image
+- records status, current step, revision context, image/resource context, result, and errors on the deployment run
+
+This is not a local development shortcut. It does not deploy unpushed local files. The repository must be pushed, the project repository must be synced, and project resource discovery must find the resource at the same path for the current commit.
+
+Enable `automatic_deployment` only when:
+
+- the release should track the project's synced repository version
+- the resource path is stable across commits
+- the current synced branch/version is an acceptable deployment source for that release
+- dashboard README requirements are satisfied for the current commit
+- the team accepts CI/CD-style rotation for this release
+
+Keep `automatic_deployment` disabled when:
+
+- the release must stay pinned to a manually selected image or resource version
+- each release rotation needs human approval
+- the resource path or entrypoint is still moving
+- API or widget contracts are not stable enough for automatic rotation
+- the current branch/project sync target is not the intended deployment source
+
+Create opted-in releases with the CLI flags that exist:
+
+- `mainsequence project project_resource create_dashboard --automatic-deployment`
+- `mainsequence project project_resource create_fastapi --automatic-deployment`
+- use `--no-automatic-deployment` when the decision is explicitly to keep the release pinned/manual
+
+The SDK surface also accepts:
+
+- `ProjectResource.create_dashboard(..., automatic_deployment=True)`
+- `ProjectResource.create_fastapi(..., automatic_deployment=True)`
+- `ResourceRelease.create(..., automatic_deployment=True)`
+- `ResourceRelease.deploy_current_version()` for an SDK-triggered manual deployment run
+
+Do not claim there is a CLI command for `deploy_current_version` unless the local CLI actually exposes one. In this SDK, the manual detail action is available through the client model.
+
+Automatic deployment runs can have these statuses:
+
+- `pending`
+- `running`
+- `waiting_project_image`
+- `waiting_runtime_ready`
+- `no_action`
+- `deployed`
+- `skipped`
+- `blocked`
+- `failed`
+
+Important blocked/skipped cases include:
+
+- `automatic_deployment_disabled`: repository-event rotation skipped because the release is not opted in
+- `project_current_version_missing`: the project has no current synced version
+- `resource_missing_for_current_commit`: no resource exists at the release path for the latest synced commit
+- `readme_missing_for_current_commit`: a dashboard-style release needs an adjacent README for the current commit
+
 ## Review Rules
 
 When reviewing an orchestration task, look for:
@@ -230,6 +299,9 @@ When reviewing an orchestration task, look for:
 - unsafe use of `--strict`
 - workflows depending on laptop-specific file paths instead of Artifacts
 - image or release work being used as a substitute for predeployment AppComponent/API contract validation
+- `automatic_deployment` enabled without an explicit decision about repository-sync CI/CD rotation
+- assumptions that automatic deployment will deploy local unpushed changes
+- automatic release rotation where the resource path or dashboard README is not stable
 - Streamlit dashboard deployment work drifting into app design or UI implementation ownership
 - tasks that are really resource/release problems rather than simple job problems
 
@@ -248,6 +320,9 @@ Do not claim success until you have checked:
 - runs and logs were inspected when execution success matters
 - resources and releases were verified when deployment success matters
 - Streamlit dashboard releases use the intended app resource, README resource, image, and `streamlit_dashboard` release kind
+- `automatic_deployment` is intentionally enabled or disabled on each release
+- automatic deployment runs were inspected when repository-sync rotation matters
+- automatic deployment results match the intended commit, resource, README, image, and terminal status
 - Command Center-facing API publishing is not being used just to test AppComponent UX that should have been validated first in `mock-json` mode
 
 If the workflow uses `scheduled_jobs.yaml`, also check:
@@ -270,6 +345,8 @@ If the workflow uses Artifacts, also check:
 - strict batch sync could delete jobs and the desired state is not explicit
 - the workflow depends on local file paths that should be platform Artifacts
 - the real need is AppComponent/API contract validation before deployment rather than release execution itself
+- automatic deployment is requested but the deployment source branch/current synced project version is unclear
+- automatic deployment is requested but the resource path or required README is not stable
 - the task is actually about RBAC policy rather than orchestration
 - the task is actually about producer semantics rather than platform execution
 

{mainsequence-4.4.30 → mainsequence-4.4.32}/mainsequence/cli/api.py

@@ -2635,6 +2635,7 @@ def create_project_resource_release(
     gpu_request: str | int | None = None,
     gpu_type: str | None = None,
     spot: bool | None = None,
+    automatic_deployment: bool | None = None,
     timeout: int | None = None,
 ) -> dict[str, Any]:
     """
@@ -2699,6 +2700,7 @@ def create_project_resource_release(
             "gpu_request": gpu_request,
             "gpu_type": gpu_type,
             "spot": spot,
+            "automatic_deployment": automatic_deployment,
             "timeout": timeout,
         }
 

{mainsequence-4.4.30 → mainsequence-4.4.32}/mainsequence/cli/cli.py

@@ -3376,27 +3376,35 @@ def _format_shareable_permission_change(payload: dict[str, object]) -> list[tupl
         ("Explicit Can Edit", str(payload.get("explicit_can_edit"))),
         (
             "Explicit View User IDs",
-            ", ".join(str(item) for item in explicit_view_ids)
-            if isinstance(explicit_view_ids, list)
-            else "-",
+            (
+                ", ".join(str(item) for item in explicit_view_ids)
+                if isinstance(explicit_view_ids, list)
+                else "-"
+            ),
         ),
         (
             "Explicit Edit User IDs",
-            ", ".join(str(item) for item in explicit_edit_ids)
-            if isinstance(explicit_edit_ids, list)
-            else "-",
+            (
+                ", ".join(str(item) for item in explicit_edit_ids)
+                if isinstance(explicit_edit_ids, list)
+                else "-"
+            ),
         ),
         (
             "Explicit View Team IDs",
-            ", ".join(str(item) for item in explicit_view_team_ids)
-            if isinstance(explicit_view_team_ids, list)
-            else "-",
+            (
+                ", ".join(str(item) for item in explicit_view_team_ids)
+                if isinstance(explicit_view_team_ids, list)
+                else "-"
+            ),
         ),
         (
             "Explicit Edit Team IDs",
-            ", ".join(str(item) for item in explicit_edit_team_ids)
-            if isinstance(explicit_edit_team_ids, list)
-            else "-",
+            (
+                ", ".join(str(item) for item in explicit_edit_team_ids)
+                if isinstance(explicit_edit_team_ids, list)
+                else "-"
+            ),
         ),
     ]
 
@@ -3610,9 +3618,11 @@ def _agent_list_impl(
                 str(agent_payload.get("uid") or "-"),
                 str(agent_payload.get("name") or "-"),
                 str(agent_payload.get("status") or "-"),
-                ", ".join(str(item) for item in labels)
-                if isinstance(labels, list) and labels
-                else "-",
+                (
+                    ", ".join(str(item) for item in labels)
+                    if isinstance(labels, list) and labels
+                    else "-"
+                ),
                 str(agent_payload.get("llm_provider") or "-"),
                 str(agent_payload.get("llm_model") or "-"),
                 str(agent_payload.get("engine_name") or "-"),
@@ -3929,9 +3939,9 @@ def _agent_session_a2a_send_impl(
     attachments = [
         {
             "path": str(path),
-            "media_type": attachment_media_types[index]
-            if attachment_media_types
-            else "application/pdf",
+            "media_type": (
+                attachment_media_types[index] if attachment_media_types else "application/pdf"
+            ),
         }
         for index, path in enumerate(attachment_paths)
     ]
@@ -4040,8 +4050,7 @@ def _agent_session_list_impl(
     )
     if agent_uid and any(key in filters for key in ("agent_uid", "agent_uid__in")):
         error(
-            "Do not pass `--filter agent_uid=...` with `--agent-uid`. "
-            "Use only one agent scope."
+            "Do not pass `--filter agent_uid=...` with `--agent-uid`. " "Use only one agent scope."
         )
         raise typer.Exit(1)
 
@@ -8391,9 +8400,9 @@ def data_node_storage_search_cmd(
         {
             "query": q,
             "mode": normalized_mode,
-            "description": description_payload
-            if normalized_mode in {"both", "description"}
-            else None,
+            "description": (
+                description_payload if normalized_mode in {"both", "description"} else None
+            ),
             "column": column_payload if normalized_mode in {"both", "column"} else None,
             "total_matches": total_matches,
         }
@@ -9916,6 +9925,7 @@ def _project_resource_release_create_impl(
     gpu_request: str | None,
     gpu_type: str | None,
     spot: bool | None,
+    automatic_deployment: bool | None,
     timeout: int | None,
 ) -> None:
     _require_login()
@@ -10039,6 +10049,7 @@ def _project_resource_release_create_impl(
             gpu_request=gpu_request,
             gpu_type=gpu_type,
             spot=spot,
+            automatic_deployment=automatic_deployment,
             timeout=timeout,
         )
     except ApiError as e:
@@ -10064,6 +10075,14 @@ def _project_resource_release_create_impl(
             ("GPU Request", str(created.get("gpu_request") or gpu_request or "-")),
             ("GPU Type", str(created.get("gpu_type") or gpu_type or "-")),
             ("Spot", str(created.get("spot") if created.get("spot") is not None else spot).lower()),
+            (
+                "Automatic Deployment",
+                str(
+                    created.get("automatic_deployment")
+                    if created.get("automatic_deployment") is not None
+                    else bool(automatic_deployment)
+                ).lower(),
+            ),
         ],
     )
 
@@ -10094,6 +10113,11 @@ def project_project_resource_create_dashboard_cmd(
     spot: bool | None = typer.Option(
         None, "--spot/--no-spot", help="Whether to prefer spot capacity."
     ),
+    automatic_deployment: bool | None = typer.Option(
+        None,
+        "--automatic-deployment/--no-automatic-deployment",
+        help="Opt the release into repository-sync CI/CD rotation.",
+    ),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
@@ -10114,6 +10138,7 @@ def project_project_resource_create_dashboard_cmd(
         gpu_request=gpu_request,
         gpu_type=gpu_type,
         spot=spot,
+        automatic_deployment=automatic_deployment,
         timeout=timeout,
     )
 
@@ -10144,6 +10169,11 @@ def project_project_resource_create_fastapi_cmd(
     spot: bool | None = typer.Option(
         None, "--spot/--no-spot", help="Whether to prefer spot capacity."
     ),
+    automatic_deployment: bool | None = typer.Option(
+        None,
+        "--automatic-deployment/--no-automatic-deployment",
+        help="Opt the release into repository-sync CI/CD rotation.",
+    ),
     timeout: int | None = typer.Option(None, "--timeout", help="Request timeout in seconds"),
 ):
     """
@@ -10164,6 +10194,7 @@ def project_project_resource_create_fastapi_cmd(
         gpu_request=gpu_request,
         gpu_type=gpu_type,
         spot=spot,
+        automatic_deployment=automatic_deployment,
         timeout=timeout,
     )
 

{mainsequence-4.4.30 → mainsequence-4.4.32}/mainsequence/client/base.py

@@ -101,6 +101,7 @@ class BaseObjectOrm:
         "GithubOrganization": "pods/github-organization",
         "ProjectResource": "pods/project-resource",
         "ResourceRelease": "pods/resource-release",
+        "ResourceReleaseAutomaticDeploymentRun": "pods/resource-release-automatic-deployment-runs",
         "Bucket": "pods/bucket",
     }
     ROOT_URL = API_ENDPOINT

{mainsequence-4.4.30 → mainsequence-4.4.32}/mainsequence/client/models_helpers.py

@@ -7,7 +7,7 @@ from collections.abc import Collection
 from decimal import Decimal
 from enum import Enum
 from pathlib import PurePosixPath
-from typing import Any, ClassVar, Literal, Union
+from typing import Any, ClassVar, Literal
 from uuid import UUID
 
 import yaml
@@ -78,7 +78,7 @@ class IntervalSchedule(BaseModel):
     )
 
 
-Schedule = Union[CrontabSchedule, IntervalSchedule]
+Schedule = CrontabSchedule | IntervalSchedule
 
 
 class PeriodicTask(BasePydanticModel):
@@ -989,11 +989,14 @@ class ProjectResource(BaseObjectOrm, BasePydanticModel):
         description="Display name of the resource discovered in the project's repository.",
         examples=["analytics_dashboard.py"],
     )
-    resource_type: Literal["dashboard", "fastapi", "markdown"] | None = Field(
+    resource_type: Literal["dashboard", "fastapi", "markdown", "agent"] | None = Field(
         None,
         title="Resource Type",
-        description="Type of the project resource. Allowed values are `dashboard`,  `fastapi`, and `markdown`.",
-        examples=["dashboard", "fastapi", "markdown"],
+        description=(
+            "Type of the project resource. Allowed values are `dashboard`, `fastapi`, "
+            "`markdown`, and `agent`."
+        ),
+        examples=["dashboard", "fastapi", "markdown", "agent"],
     )
     code: str | None = Field(
         None,
@@ -1047,9 +1050,19 @@ class ProjectResource(BaseObjectOrm, BasePydanticModel):
         **kwargs,
     ) -> ResourceRelease:
         resource_uid = self._public_detail_reference()
+        if "related_image_id" in kwargs and "related_image_uid" not in kwargs:
+            kwargs["related_image_uid"] = kwargs.pop("related_image_id")
+
+        readme_resource_id = kwargs.pop("readme_resource_id", None)
+        if readme_resource_id is not None:
+            raise ValueError(
+                "readme_resource_id is not supported by ResourceRelease.create(); "
+                "README resources are resolved by the backend."
+            )
+
         kwargs["resource_uid"] = resource_uid
         kwargs["release_kind"] = release_kind.value
-        return ResourceRelease.create(timeout=timeout, files=files, *args, **kwargs)
+        return ResourceRelease.create(*args, timeout=timeout, files=files, **kwargs)
 
     def create_dashboard(self, timeout=None, files=None, *args, **kwargs) -> ResourceRelease:
         return self._create_release(
@@ -1069,13 +1082,36 @@ class ProjectResource(BaseObjectOrm, BasePydanticModel):
             **kwargs,
         )
 
+    def create_agent(self, timeout=None, files=None, *args, **kwargs) -> ResourceRelease:
+        return self._create_release(
+            ResourceReleaseKind.AGENT,
+            timeout,
+            files,
+            *args,
+            **kwargs,
+        )
+
 
 class ResourceReleaseKind(str, Enum):
     STREAMLIT_DASHBOARD = "streamlit_dashboard"
+    AGENT = "agent"
     FAST_API = "fastapi"
 
 
 class ResourceRelease(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
+    FILTERSET_FIELDS: ClassVar[dict[str, list[str]]] = {
+        "uid": ["exact", "in"],
+        "resource__uid": ["exact", "in"],
+        "related_job__uid": ["exact", "in"],
+        "release_kind": ["exact", "in"],
+    }
+    FILTER_VALUE_NORMALIZERS: ClassVar[dict[str, str]] = {
+        "uid": "uid",
+        "resource__uid": "uid",
+        "related_job__uid": "uid",
+        "release_kind": "str",
+    }
+
     uid: str | None = Field(
         None,
         title="Resource Release UID",
@@ -1141,6 +1177,15 @@ class ResourceRelease(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
         description="Whether the release should prefer spot or preemptible capacity.",
         examples=[False, True],
     )
+    automatic_deployment: bool = Field(
+        default=False,
+        title="Automatic Deployment",
+        description=(
+            "Whether repository synchronization should rotate this release to the "
+            "current project commit."
+        ),
+        examples=[False, True],
+    )
 
     @classmethod
     def create(
@@ -1154,6 +1199,7 @@ class ResourceRelease(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
         gpu_request: str | int | None = None,
         gpu_type: str | None = None,
         spot: bool | None = None,
+        automatic_deployment: bool | None = None,
         timeout: int | None = None,
         files=None,
     ) -> ResourceRelease:
@@ -1198,6 +1244,8 @@ class ResourceRelease(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
             payload["gpu_type"] = normalized_compute["gpu_type"]
         if spot is not None:
             payload["spot"] = bool(spot)
+        if automatic_deployment is not None:
+            payload["automatic_deployment"] = bool(automatic_deployment)
 
         request_payload = {"json": cls.serialize_for_json(payload)}
         if files:
@@ -1216,3 +1264,126 @@ class ResourceRelease(ShareableObjectMixin, BaseObjectOrm, BasePydanticModel):
             raise_for_response(r, payload=request_payload)
 
         return cls(**r.json())
+
+    def deploy_current_version(
+        self,
+        *,
+        timeout: int | float | tuple[float, float] | None = None,
+    ) -> ResourceReleaseAutomaticDeploymentRun:
+        data = self._request_detail_action(
+            r_type="POST",
+            action_name="deploy-current-version",
+            payload={},
+            timeout=timeout,
+            expected_statuses=(200, 202),
+        )
+        return ResourceReleaseAutomaticDeploymentRun(**data)
+
+
+class ResourceReleaseAutomaticDeploymentRun(BaseObjectOrm, BasePydanticModel):
+    FILTERSET_FIELDS: ClassVar[dict[str, list[str]]] = {
+        "resource_release__uid": ["exact", "in"],
+        "status": ["exact", "in"],
+        "release_kind": ["exact", "in"],
+        "automatic_deployment_source": ["exact", "in"],
+    }
+    FILTER_VALUE_NORMALIZERS: ClassVar[dict[str, str]] = {
+        "resource_release__uid": "uid",
+        "status": "str",
+        "release_kind": "str",
+        "automatic_deployment_source": "str",
+    }
+
+    STATUS_PENDING: ClassVar[str] = "pending"
+    STATUS_RUNNING: ClassVar[str] = "running"
+    STATUS_WAITING_PROJECT_IMAGE: ClassVar[str] = "waiting_project_image"
+    STATUS_WAITING_RUNTIME_READY: ClassVar[str] = "waiting_runtime_ready"
+    STATUS_NO_ACTION: ClassVar[str] = "no_action"
+    STATUS_DEPLOYED: ClassVar[str] = "deployed"
+    STATUS_SKIPPED: ClassVar[str] = "skipped"
+    STATUS_BLOCKED: ClassVar[str] = "blocked"
+    STATUS_FAILED: ClassVar[str] = "failed"
+
+    SOURCE_MANUAL: ClassVar[str] = "manual"
+    SOURCE_REPOSITORY_EVENT: ClassVar[str] = "repository_event"
+
+    uid: str | None = Field(
+        None,
+        title="Resource Release Automatic Deployment Run UID",
+        description="Public UID of the automatic deployment run.",
+    )
+    resource_release_uid: str | None = Field(
+        None,
+        title="Resource Release UID",
+        description="Public UID snapshot of the resource release targeted by this run.",
+    )
+    resource_release_name: str = Field(
+        default="",
+        title="Resource Release Name",
+        description="Display-name snapshot of the targeted resource release.",
+    )
+    release_kind: ResourceReleaseKind | str | None = Field(
+        None,
+        title="Release Kind",
+        description="Resource release kind targeted by this run.",
+    )
+    status: str | None = Field(
+        None,
+        title="Status",
+        description="Deployment run status.",
+    )
+    current_step: str = Field(
+        default="",
+        title="Current Step",
+        description="Current orchestration step key.",
+    )
+    automatic_deployment_source: str | None = Field(
+        None,
+        title="Automatic Deployment Source",
+        description="Run trigger source, for example manual or repository_event.",
+    )
+    revision_context: dict[str, Any] = Field(
+        default_factory=dict,
+        title="Revision Context",
+        description="Stable project/revision/resource context for the run.",
+    )
+    trigger_context: dict[str, Any] = Field(
+        default_factory=dict,
+        title="Trigger Context",
+        description="Repository event or manual trigger correlation metadata.",
+    )
+    image_artifact_context: dict[str, Any] = Field(
+        default_factory=dict,
+        title="Image Artifact Context",
+        description="Project image and resource snapshots captured by the run.",
+    )
+    cleanup_context: dict[str, Any] = Field(
+        default_factory=dict,
+        title="Cleanup Context",
+        description="Cleanup outcomes captured by the run.",
+    )
+    started_at: datetime.datetime | None = Field(
+        None,
+        title="Started At",
+        description="Timestamp when execution started.",
+    )
+    finished_at: datetime.datetime | None = Field(
+        None,
+        title="Finished At",
+        description="Timestamp when execution finished.",
+    )
+    result: dict[str, Any] = Field(
+        default_factory=dict,
+        title="Result",
+        description="Terminal or intermediate deployment result payload.",
+    )
+    error_code: str = Field(
+        default="",
+        title="Error Code",
+        description="Machine-readable error code when the run failed or was blocked.",
+    )
+    error_detail: str = Field(
+        default="",
+        title="Error Detail",
+        description="Human-readable error detail when the run failed or was blocked.",
+    )

{mainsequence-4.4.30 → mainsequence-4.4.32}/mainsequence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.30
+Version: 4.4.32
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.4.30 → mainsequence-4.4.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "4.4.30"
+version = "4.4.32"
 description = "Main Sequence SDK "
 readme = "README.md"
 requires-python = ">=3.11"