dominus-sdk-python 2.16.0__tar.gz → 2.17.0__tar.gz

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.16.0
+Version: 2.17.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/dominus/__init__.py

@@ -180,7 +180,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "2.16.0"
+__version__ = "2.17.0"
 __all__ = [
     # Main SDK instance
     "dominus",

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/dominus/namespaces/workflow.py

@@ -86,6 +86,74 @@ class WorkflowNamespace:
             return {"workflow_id": str(workflow_id).strip()}
         raise ValueError("workflow_id or workflow_ref is required")
 
+    @staticmethod
+    def _instance_base_endpoint(workflow_id: str) -> str:
+        from urllib.parse import quote
+
+        return f"/api/workflow/workflows/{quote(workflow_id, safe='')}/instances"
+
+    @staticmethod
+    def _build_instance_nudge_policy(
+        nudge_policy: Optional[Dict[str, Any]] = None,
+    ) -> Optional[Dict[str, Any]]:
+        if not nudge_policy:
+            return None
+
+        policy = dict(nudge_policy)
+        result: Dict[str, Any] = {}
+        if "mode" in policy and policy["mode"] is not None:
+            result["mode"] = policy["mode"]
+        if "max_rerun_count" in policy and policy["max_rerun_count"] is not None:
+            result["max_rerun_count"] = policy["max_rerun_count"]
+        elif "maxRerunCount" in policy and policy["maxRerunCount"] is not None:
+            result["max_rerun_count"] = policy["maxRerunCount"]
+        if "rerun_window_seconds" in policy and policy["rerun_window_seconds"] is not None:
+            result["rerun_window_seconds"] = policy["rerun_window_seconds"]
+        elif "rerunWindowSeconds" in policy and policy["rerunWindowSeconds"] is not None:
+            result["rerun_window_seconds"] = policy["rerunWindowSeconds"]
+
+        for key, value in policy.items():
+            if value is None:
+                continue
+            if key in {"mode", "max_rerun_count", "maxRerunCount", "rerun_window_seconds", "rerunWindowSeconds"}:
+                continue
+            result[key] = value
+
+        return result or None
+
+    def _build_ensure_instance_body(
+        self,
+        *,
+        group: str,
+        owner: str,
+        instance_id: Optional[str] = None,
+        environment: Optional[str] = None,
+        nudge_policy: Optional[Dict[str, Any]] = None,
+        bindings: Optional[Dict[str, Any]] = None,
+        mode: Optional[str] = None,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {
+            "params": {
+                "group": group,
+                "owner": owner,
+            }
+        }
+        if instance_id:
+            body["instance_id"] = instance_id
+        if environment:
+            body["params"]["env"] = environment
+        policy = self._build_instance_nudge_policy(nudge_policy)
+        if policy:
+            body["params"]["nudge_policy"] = policy
+        if bindings:
+            body["bindings"] = bindings
+        if mode:
+            body["mode"] = mode
+        if context:
+            body["context"] = context
+        return body
+
     async def _api(
         self,
         endpoint: str,
@@ -620,6 +688,281 @@ class WorkflowNamespace:
             body=body,
         )
 
+    async def ensure(
+        self,
+        workflow_id: str,
+        *,
+        instance_id: Optional[str] = None,
+        group: str,
+        owner: str,
+        environment: Optional[str] = None,
+        nudge_policy: Optional[Dict[str, Any]] = None,
+        bindings: Optional[Dict[str, Any]] = None,
+        mode: str = "blocking",
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Ensure a workflow instance exists and optionally launch execution."""
+        return await self.ensure_instance(
+            workflow_id,
+            instance_id=instance_id,
+            group=group,
+            owner=owner,
+            environment=environment,
+            nudge_policy=nudge_policy,
+            bindings=bindings,
+            mode=mode,
+            context=context,
+        )
+
+    async def ensure_instance(
+        self,
+        workflow_id: str,
+        *,
+        instance_id: Optional[str] = None,
+        group: str,
+        owner: str,
+        environment: Optional[str] = None,
+        nudge_policy: Optional[Dict[str, Any]] = None,
+        bindings: Optional[Dict[str, Any]] = None,
+        mode: str = "blocking",
+        context: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Ensure a workflow instance exists and optionally launch execution."""
+        if mode == "streaming":
+            raise ValueError("Use stream_ensure_instance() for streaming instance execution")
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/ensure",
+            body=self._build_ensure_instance_body(
+                instance_id=instance_id,
+                group=group,
+                owner=owner,
+                environment=environment,
+                nudge_policy=nudge_policy,
+                bindings=bindings,
+                mode=mode,
+                context=context,
+            ),
+        )
+
+    async def stream_ensure_instance(
+        self,
+        workflow_id: str,
+        *,
+        instance_id: Optional[str] = None,
+        group: str,
+        owner: str,
+        environment: Optional[str] = None,
+        nudge_policy: Optional[Dict[str, Any]] = None,
+        bindings: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+        on_chunk: Optional[Any] = None,
+    ):
+        """Ensure a workflow instance and stream execution events."""
+        async for chunk in self._client._stream_request(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/ensure",
+            body=self._build_ensure_instance_body(
+                instance_id=instance_id,
+                group=group,
+                owner=owner,
+                environment=environment,
+                nudge_policy=nudge_policy,
+                bindings=bindings,
+                mode="streaming",
+                context=context,
+            ),
+            on_chunk=on_chunk,
+            use_gateway=True,
+        ):
+            yield chunk
+
+    async def get_instance_status(self, workflow_id: str, instance_id: str) -> Dict[str, Any]:
+        """Get workflow instance status."""
+        from urllib.parse import quote
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/status",
+            method="GET",
+        )
+
+    async def list_instances(
+        self,
+        *,
+        workflow_id: Optional[str] = None,
+        group: Optional[str] = None,
+        owner: Optional[str] = None,
+        environment: Optional[str] = None,
+        status: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> List[Dict[str, Any]]:
+        """List workflow instances."""
+        params = [f"limit={limit}", f"offset={offset}"]
+        if workflow_id:
+            params.append(f"workflow_id={workflow_id}")
+        if group:
+            params.append(f"group={group}")
+        if owner:
+            params.append(f"owner={owner}")
+        if environment:
+            params.append(f"environment={environment}")
+        if status:
+            params.append(f"status={status}")
+
+        result = await self._api(
+            endpoint=f"/api/workflow/instances?{'&'.join(params)}",
+            method="GET",
+        )
+        return result.get("instances", result) if isinstance(result, dict) else result
+
+    async def get_instance_artifacts(self, workflow_id: str, instance_id: str) -> Dict[str, Any]:
+        """Get workflow instance artifact addresses."""
+        from urllib.parse import quote
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/artifacts",
+            method="GET",
+        )
+
+    async def get_instance_outputs(self, workflow_id: str, instance_id: str) -> Dict[str, Any]:
+        """Get workflow instance accepted outputs."""
+        from urllib.parse import quote
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/outputs",
+            method="GET",
+        )
+
+    async def get_instance_history(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> Dict[str, Any]:
+        """Get workflow instance execution history."""
+        from urllib.parse import quote
+
+        return await self._api(
+            endpoint=(
+                f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/history"
+                f"?limit={limit}&offset={offset}"
+            ),
+            method="GET",
+        )
+
+    async def nudge(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        reason: str,
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+    ) -> Dict[str, Any]:
+        """Nudge a workflow instance into a new execution."""
+        return await self.nudge_instance(
+            workflow_id,
+            instance_id,
+            reason=reason,
+            trigger_artifact=trigger_artifact,
+            mode=mode,
+        )
+
+    async def nudge_instance(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        reason: str,
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+    ) -> Dict[str, Any]:
+        """Nudge a workflow instance into a new execution."""
+        from urllib.parse import quote
+
+        if mode == "streaming":
+            raise ValueError("Use stream_nudge_instance() for streaming instance execution")
+
+        body: Dict[str, Any] = {"reason": reason, "mode": mode}
+        if trigger_artifact:
+            body["trigger_artifact"] = trigger_artifact
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/nudge",
+            body=body,
+        )
+
+    async def stream_nudge_instance(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        reason: str,
+        trigger_artifact: Optional[str] = None,
+        on_chunk: Optional[Any] = None,
+    ):
+        """Nudge a workflow instance and stream execution events."""
+        from urllib.parse import quote
+
+        body: Dict[str, Any] = {"reason": reason, "mode": "streaming"}
+        if trigger_artifact:
+            body["trigger_artifact"] = trigger_artifact
+
+        async for chunk in self._client._stream_request(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/nudge",
+            body=body,
+            on_chunk=on_chunk,
+            use_gateway=True,
+        ):
+            yield chunk
+
+    async def retry(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        reason: str = "retry",
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+    ) -> Dict[str, Any]:
+        """Retry a workflow instance. Alias for nudge with a default retry reason."""
+        return await self.retry_instance(
+            workflow_id,
+            instance_id,
+            reason=reason,
+            trigger_artifact=trigger_artifact,
+            mode=mode,
+        )
+
+    async def retry_instance(
+        self,
+        workflow_id: str,
+        instance_id: str,
+        *,
+        reason: str = "retry",
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+    ) -> Dict[str, Any]:
+        """Retry a workflow instance. Alias for nudge with a default retry reason."""
+        return await self.nudge_instance(
+            workflow_id,
+            instance_id,
+            reason=reason,
+            trigger_artifact=trigger_artifact,
+            mode=mode,
+        )
+
+    async def cancel_instance(self, workflow_id: str, instance_id: str) -> Dict[str, Any]:
+        """Cancel a running workflow instance."""
+        from urllib.parse import quote
+
+        return await self._api(
+            endpoint=f"{self._instance_base_endpoint(workflow_id)}/{quote(instance_id, safe='')}/cancel",
+            body={},
+        )
+
     async def get_run(self, run_id: str) -> Dict[str, Any]:
         """Get a saved-workflow run."""
         return await self._api(

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.16.0
+Version: 2.17.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "2.16.0"
+version = "2.17.0"
 description = "Python SDK for the Dominus Orchestrator Platform"
 readme = "README.md"
 license = {text = "Proprietary"}

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.17.0}/tests/test_workflow_lifecycle.py

@@ -314,3 +314,228 @@ async def test_execute_pipeline_forwards_resume_execution_id():
 
     call = client.calls[0]
     assert call["body"]["config"]["resume_execution_id"] == "resume-1"
+
+
+@pytest.mark.asyncio
+async def test_saved_workflow_instance_ensure_contract_matches_workflow_manager():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+
+    await namespace.ensure_instance(
+        "wf-instance",
+        instance_id="inst-1",
+        group="reports",
+        owner="company:acme",
+        environment="production",
+        nudge_policy={
+            "mode": "coalesce",
+            "maxRerunCount": 3,
+            "rerunWindowSeconds": 120,
+            "cooldown_seconds": 15,
+        },
+        bindings={"subject": "PCM47474562"},
+        mode="async",
+        context={"company": "acme"},
+    )
+
+    call = client.calls[0]
+    assert call["endpoint"] == "/api/workflow/workflows/wf-instance/instances/ensure"
+    assert call["body"] == {
+        "instance_id": "inst-1",
+        "params": {
+            "group": "reports",
+            "owner": "company:acme",
+            "env": "production",
+            "nudge_policy": {
+                "mode": "coalesce",
+                "max_rerun_count": 3,
+                "rerun_window_seconds": 120,
+                "cooldown_seconds": 15,
+            },
+        },
+        "bindings": {"subject": "PCM47474562"},
+        "mode": "async",
+        "context": {"company": "acme"},
+    }
+
+
+@pytest.mark.asyncio
+async def test_saved_workflow_instance_ensure_alias_and_stream_guard():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+
+    await namespace.ensure(
+        "wf-instance",
+        group="reports",
+        owner="company:acme",
+        mode="ensure_only",
+    )
+
+    call = client.calls[0]
+    assert call["endpoint"] == "/api/workflow/workflows/wf-instance/instances/ensure"
+    assert call["body"] == {
+        "params": {
+            "group": "reports",
+            "owner": "company:acme",
+        },
+        "mode": "ensure_only",
+    }
+
+    with pytest.raises(ValueError, match="Use stream_ensure_instance\\(\\) for streaming instance execution"):
+        await namespace.ensure_instance(
+            "wf-instance",
+            group="reports",
+            owner="company:acme",
+            mode="streaming",
+        )
+
+
+@pytest.mark.asyncio
+async def test_stream_ensure_instance_uses_streaming_mode():
+    client = FakeClient(stream_chunks=[{"_event": "instance_ensured"}, {"_event": "workflow_complete"}])
+    namespace = WorkflowNamespace(client)
+
+    streamed = [
+        chunk
+        async for chunk in namespace.stream_ensure_instance(
+            "wf-instance",
+            group="reports",
+            owner="company:acme",
+            bindings={"subject": "PCM47474562"},
+        )
+    ]
+
+    assert client.stream_calls == [
+        {
+            "endpoint": "/api/workflow/workflows/wf-instance/instances/ensure",
+            "body": {
+                "params": {
+                    "group": "reports",
+                    "owner": "company:acme",
+                },
+                "bindings": {"subject": "PCM47474562"},
+                "mode": "streaming",
+            },
+            "timeout": 300.0,
+            "use_gateway": True,
+        }
+    ]
+    assert streamed == [{"_event": "instance_ensured"}, {"_event": "workflow_complete"}]
+
+
+@pytest.mark.asyncio
+async def test_workflow_instance_read_routes_match_contract():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+
+    await namespace.get_instance_status("wf-instance", "inst/1")
+    await namespace.list_instances(
+        workflow_id="wf-instance",
+        group="reports",
+        owner="company:acme",
+        environment="production",
+        status="idle",
+        limit=25,
+        offset=5,
+    )
+    await namespace.get_instance_artifacts("wf-instance", "inst-1")
+    await namespace.get_instance_outputs("wf-instance", "inst-1")
+    await namespace.get_instance_history("wf-instance", "inst-1", limit=10, offset=2)
+
+    assert client.calls[0]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst%2F1/status"
+    assert client.calls[0]["method"] == "GET"
+    assert client.calls[1]["endpoint"] == (
+        "/api/workflow/instances"
+        "?limit=25&offset=5&workflow_id=wf-instance&group=reports&owner=company:acme"
+        "&environment=production&status=idle"
+    )
+    assert client.calls[1]["method"] == "GET"
+    assert client.calls[2]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-1/artifacts"
+    assert client.calls[2]["method"] == "GET"
+    assert client.calls[3]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-1/outputs"
+    assert client.calls[3]["method"] == "GET"
+    assert client.calls[4]["endpoint"] == (
+        "/api/workflow/workflows/wf-instance/instances/inst-1/history?limit=10&offset=2"
+    )
+    assert client.calls[4]["method"] == "GET"
+
+
+@pytest.mark.asyncio
+async def test_workflow_instance_nudge_retry_and_cancel_contract():
+    client = FakeClient(stream_chunks=[{"_event": "instance_nudged"}])
+    namespace = WorkflowNamespace(client)
+
+    await namespace.nudge_instance(
+        "wf-instance",
+        "inst-1",
+        reason="artifact-updated",
+        trigger_artifact="report_snapshot",
+        mode="blocking",
+    )
+    await namespace.nudge(
+        "wf-instance",
+        "inst-2",
+        reason="manual-retry",
+    )
+    await namespace.retry_instance(
+        "wf-instance",
+        "inst-3",
+        trigger_artifact="report_snapshot",
+        mode="async",
+    )
+    await namespace.cancel_instance("wf-instance", "inst-4")
+
+    streamed = [
+        chunk
+        async for chunk in namespace.stream_nudge_instance(
+            "wf-instance",
+            "inst-5",
+            reason="artifact-updated",
+            trigger_artifact="report_snapshot",
+        )
+    ]
+
+    assert client.calls[0]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-1/nudge"
+    assert client.calls[0]["body"] == {
+        "reason": "artifact-updated",
+        "trigger_artifact": "report_snapshot",
+        "mode": "blocking",
+    }
+
+    assert client.calls[1]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-2/nudge"
+    assert client.calls[1]["body"] == {
+        "reason": "manual-retry",
+        "mode": "async",
+    }
+
+    assert client.calls[2]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-3/nudge"
+    assert client.calls[2]["body"] == {
+        "reason": "retry",
+        "trigger_artifact": "report_snapshot",
+        "mode": "async",
+    }
+
+    assert client.calls[3]["endpoint"] == "/api/workflow/workflows/wf-instance/instances/inst-4/cancel"
+    assert client.calls[3]["body"] == {}
+
+    assert client.stream_calls == [
+        {
+            "endpoint": "/api/workflow/workflows/wf-instance/instances/inst-5/nudge",
+            "body": {
+                "reason": "artifact-updated",
+                "trigger_artifact": "report_snapshot",
+                "mode": "streaming",
+            },
+            "timeout": 300.0,
+            "use_gateway": True,
+        }
+    ]
+    assert streamed == [{"_event": "instance_nudged"}]
+
+    with pytest.raises(ValueError, match="Use stream_nudge_instance\\(\\) for streaming instance execution"):
+        await namespace.nudge_instance(
+            "wf-instance",
+            "inst-1",
+            reason="artifact-updated",
+            mode="streaming",
+        )