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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.16.0
+Version: 2.18.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary
@@ -49,7 +49,7 @@ Async Python SDK for CareBridge Dominus platform services. Routes calls through
 - Server-side, asyncio-first Python SDK (3.9+)
 - Namespace API with root-level shortcuts for common operations
 - Targets production Cloudflare Workers (gateway, JWT, logs) and Cloud Run (orchestrator)
-- Version: 2.16.0
+- Version: 2.18.0
 
 ## Quick Start
 
@@ -89,7 +89,15 @@ async for chunk in dominus.ai.stream_agent(
 ):
     print(chunk.get("content", ""), end="", flush=True)
 
-# Saved workflow lifecycle through workflow-manager
+# Preferred Authority-backed one-call lifecycle
+execution = await dominus.workflow.ensure(
+    "wf://carebridge/report-cycle",
+    subject="PCM47474562",
+    company="summit-radiology",
+    inputs={"report_snapshot": "ar://carebridge/summit-radiology/production/snapshot/report-1"},
+)
+
+# Saved workflow lifecycle through workflow-manager when you need explicit artifacts
 run = await dominus.workflow.create_run(
     workflow_id="wf_saved_123",
     context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.18.0}/README.md

@@ -7,7 +7,7 @@ Async Python SDK for CareBridge Dominus platform services. Routes calls through
 - Server-side, asyncio-first Python SDK (3.9+)
 - Namespace API with root-level shortcuts for common operations
 - Targets production Cloudflare Workers (gateway, JWT, logs) and Cloud Run (orchestrator)
-- Version: 2.16.0
+- Version: 2.18.0
 
 ## Quick Start
 
@@ -47,7 +47,15 @@ async for chunk in dominus.ai.stream_agent(
 ):
     print(chunk.get("content", ""), end="", flush=True)
 
-# Saved workflow lifecycle through workflow-manager
+# Preferred Authority-backed one-call lifecycle
+execution = await dominus.workflow.ensure(
+    "wf://carebridge/report-cycle",
+    subject="PCM47474562",
+    company="summit-radiology",
+    inputs={"report_snapshot": "ar://carebridge/summit-radiology/production/snapshot/report-1"},
+)
+
+# Saved workflow lifecycle through workflow-manager when you need explicit artifacts
 run = await dominus.workflow.create_run(
     workflow_id="wf_saved_123",
     context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},

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

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

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

@@ -34,6 +34,9 @@ Usage:
     await dominus.workflow.validate_run(run["run_id"])
     result = await dominus.workflow.start_run(run["run_id"], mode="async")
 """
+import base64
+import json
+import uuid
 from typing import Any, Dict, List, Optional, TYPE_CHECKING
 from urllib.parse import urlencode
 
@@ -86,6 +89,158 @@ 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
+
+    @staticmethod
+    def _decode_authority_run_id(run_id: str) -> Optional[Dict[str, str]]:
+        normalized = str(run_id or "").strip()
+        if not normalized:
+            return None
+        try:
+            padding = "=" * ((4 - len(normalized) % 4) % 4)
+            decoded = base64.urlsafe_b64decode((normalized + padding).encode("utf-8")).decode("utf-8")
+            payload = json.loads(decoded)
+        except Exception:
+            return None
+
+        required = ("project_id", "environment", "workflow_id", "instance_id")
+        if all(isinstance(payload.get(field), str) and str(payload.get(field)).strip() for field in required):
+            return {field: str(payload[field]).strip() for field in required}
+        return None
+
+    def _is_authority_run_id(self, run_id: str) -> bool:
+        return self._decode_authority_run_id(run_id) is not None
+
+    @staticmethod
+    def _authority_mutation_body(
+        body: Dict[str, Any],
+        *,
+        idempotency_key: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        result = dict(body)
+        if initiator_type:
+            result["initiator_type"] = initiator_type
+        if initiator_id:
+            result["initiator_id"] = initiator_id
+        result["idempotency_key"] = idempotency_key or uuid.uuid4().hex
+        return result
+
+    def _build_authority_ensure_body(
+        self,
+        workflow_id: str,
+        *,
+        workflow_ref: Optional[str] = None,
+        subject: Optional[str] = None,
+        company: Optional[str] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        context: Optional[Dict[str, Any]] = None,
+        bindings: Optional[Dict[str, Any]] = None,
+        instance_id: Optional[str] = None,
+        mode: str = "async",
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        body: Dict[str, Any] = {"mode": mode}
+        if workflow_ref:
+            body["workflow_ref"] = workflow_ref
+        elif self._is_workflow_ref(workflow_id):
+            body["workflow_ref"] = workflow_id
+        else:
+            body["workflow_id"] = workflow_id
+        if subject is not None:
+            body["subject"] = subject
+        if company is not None:
+            body["company"] = company
+        if inputs:
+            body["inputs"] = inputs
+        if context:
+            body["context"] = context
+        if bindings:
+            body["bindings"] = bindings
+        if instance_id:
+            body["instance_id"] = instance_id
+        if target_project_id:
+            body["target_project_id"] = target_project_id
+        if target_environment:
+            body["target_environment"] = target_environment
+        return self._authority_mutation_body(
+            body,
+            idempotency_key=idempotency_key,
+            initiator_type=initiator_type,
+            initiator_id=initiator_id,
+        )
+
     async def _api(
         self,
         endpoint: str,
@@ -172,6 +327,16 @@ class WorkflowNamespace:
         Returns:
             Dict with workflow metadata and optionally content
         """
+        if not include_content and self._is_authority_run_id(workflow_id):
+            return await self.get_run_state(workflow_id)
+        endpoint = self._workflow_lookup_endpoint(workflow_id, include_content=include_content)
+        return await self._api(endpoint=endpoint, method="GET")
+
+    async def get_workflow(
+        self,
+        workflow_id: str,
+        include_content: bool = False,
+    ) -> Dict[str, Any]:
         endpoint = self._workflow_lookup_endpoint(workflow_id, include_content=include_content)
         return await self._api(endpoint=endpoint, method="GET")
 
@@ -620,6 +785,410 @@ class WorkflowNamespace:
             body=body,
         )
 
+    async def ensure(
+        self,
+        workflow_id: str,
+        *,
+        instance_id: Optional[str] = None,
+        group: Optional[str] = None,
+        owner: Optional[str] = None,
+        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,
+        workflow_ref: Optional[str] = None,
+        subject: Optional[str] = None,
+        company: Optional[str] = None,
+        inputs: Optional[Dict[str, Any]] = None,
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Ensure a workflow instance exists and optionally launch execution."""
+        if (
+            subject is not None
+            or company is not None
+            or inputs is not None
+            or workflow_ref is not None
+            or target_project_id is not None
+            or target_environment is not None
+            or initiator_type is not None
+            or initiator_id is not None
+            or idempotency_key is not None
+            or group is None
+            or owner is None
+        ):
+            return await self._api(
+                endpoint="/api/authority/runs/ensure",
+                body=self._build_authority_ensure_body(
+                    workflow_id,
+                    workflow_ref=workflow_ref,
+                    subject=subject,
+                    company=company,
+                    inputs=inputs,
+                    context=context,
+                    bindings=bindings,
+                    instance_id=instance_id,
+                    mode=mode,
+                    target_project_id=target_project_id,
+                    target_environment=target_environment,
+                    initiator_type=initiator_type,
+                    initiator_id=initiator_id,
+                    idempotency_key=idempotency_key,
+                ),
+            )
+        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 list_runs(
+        self,
+        *,
+        workflow_id: Optional[str] = None,
+        subject: Optional[str] = None,
+        company: Optional[str] = None,
+        status: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        params = [f"limit={limit}", f"offset={offset}"]
+        if workflow_id:
+            params.append(f"workflow_id={workflow_id}")
+        if subject:
+            params.append(f"owner={subject}")
+        if company:
+            params.append(f"group={company}")
+        if status:
+            params.append(f"status={status}")
+        if target_project_id:
+            params.append(f"target_project_id={target_project_id}")
+        if target_environment:
+            params.append(f"target_environment={target_environment}")
+
+        result = await self._api(
+            endpoint=f"/api/authority/runs?{'&'.join(params)}",
+            method="GET",
+        )
+        return result.get("runs", result) if isinstance(result, dict) else result
+
+    async def get_run_state(self, run_id: str) -> Dict[str, Any]:
+        return await self._api(
+            endpoint=f"/api/authority/runs/{run_id}",
+            method="GET",
+        )
+
+    async def get_run_timeline(self, run_id: str) -> Dict[str, Any]:
+        return await self._api(
+            endpoint=f"/api/authority/runs/{run_id}/timeline",
+            method="GET",
+        )
+
+    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: Optional[str] = None,
+        *,
+        reason: str,
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Nudge a workflow instance into a new execution."""
+        if instance_id is None and self._is_authority_run_id(workflow_id):
+            body: Dict[str, Any] = {"reason": reason, "mode": mode}
+            if trigger_artifact:
+                body["trigger_artifact"] = trigger_artifact
+            if target_project_id:
+                body["target_project_id"] = target_project_id
+            if target_environment:
+                body["target_environment"] = target_environment
+            return await self._api(
+                endpoint=f"/api/authority/runs/{workflow_id}/nudge",
+                body=self._authority_mutation_body(
+                    body,
+                    idempotency_key=idempotency_key,
+                    initiator_type=initiator_type,
+                    initiator_id=initiator_id,
+                ),
+            )
+        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: Optional[str] = None,
+        *,
+        reason: str = "retry",
+        trigger_artifact: Optional[str] = None,
+        mode: str = "async",
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Retry a workflow instance. Alias for nudge with a default retry reason."""
+        if instance_id is None and self._is_authority_run_id(workflow_id):
+            body: Dict[str, Any] = {"reason": reason, "mode": mode}
+            if trigger_artifact:
+                body["trigger_artifact"] = trigger_artifact
+            if target_project_id:
+                body["target_project_id"] = target_project_id
+            if target_environment:
+                body["target_environment"] = target_environment
+            return await self._api(
+                endpoint=f"/api/authority/runs/{workflow_id}/retry",
+                body=self._authority_mutation_body(
+                    body,
+                    idempotency_key=idempotency_key,
+                    initiator_type=initiator_type,
+                    initiator_id=initiator_id,
+                ),
+            )
+        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(
@@ -787,8 +1356,32 @@ class WorkflowNamespace:
         )
         return result.get("events", result) if isinstance(result, dict) else result
 
-    async def cancel(self, execution_id: str) -> Dict[str, Any]:
-        """Cancel a saved-workflow execution."""
+    async def cancel(
+        self,
+        execution_id: str,
+        *,
+        target_project_id: Optional[str] = None,
+        target_environment: Optional[str] = None,
+        initiator_type: Optional[str] = None,
+        initiator_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Cancel a saved-workflow execution or Authority-backed run."""
+        if self._is_authority_run_id(execution_id):
+            body: Dict[str, Any] = {}
+            if target_project_id:
+                body["target_project_id"] = target_project_id
+            if target_environment:
+                body["target_environment"] = target_environment
+            return await self._api(
+                endpoint=f"/api/authority/runs/{execution_id}/cancel",
+                body=self._authority_mutation_body(
+                    body,
+                    idempotency_key=idempotency_key,
+                    initiator_type=initiator_type,
+                    initiator_id=initiator_id,
+                ),
+            )
         return await self._api(
             endpoint=f"/api/workflow/executions/{execution_id}/cancel",
             body={},

{dominus_sdk_python-2.16.0 → dominus_sdk_python-2.18.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.18.0
 Summary: Python SDK for the Dominus Orchestrator Platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary
@@ -49,7 +49,7 @@ Async Python SDK for CareBridge Dominus platform services. Routes calls through
 - Server-side, asyncio-first Python SDK (3.9+)
 - Namespace API with root-level shortcuts for common operations
 - Targets production Cloudflare Workers (gateway, JWT, logs) and Cloud Run (orchestrator)
-- Version: 2.16.0
+- Version: 2.18.0
 
 ## Quick Start
 
@@ -89,7 +89,15 @@ async for chunk in dominus.ai.stream_agent(
 ):
     print(chunk.get("content", ""), end="", flush=True)
 
-# Saved workflow lifecycle through workflow-manager
+# Preferred Authority-backed one-call lifecycle
+execution = await dominus.workflow.ensure(
+    "wf://carebridge/report-cycle",
+    subject="PCM47474562",
+    company="summit-radiology",
+    inputs={"report_snapshot": "ar://carebridge/summit-radiology/production/snapshot/report-1"},
+)
+
+# Saved workflow lifecycle through workflow-manager when you need explicit artifacts
 run = await dominus.workflow.create_run(
     workflow_id="wf_saved_123",
     context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "2.16.0"
+version = "2.18.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.18.0}/tests/test_workflow_lifecycle.py

@@ -1,4 +1,6 @@
 import pytest
+import base64
+import json
 
 from dominus.namespaces.ai import WorkflowSubNamespace
 from dominus.namespaces.workflow import WorkflowNamespace
@@ -53,6 +55,18 @@ class FakeClient:
             yield chunk
 
 
+def authority_run_id(**overrides):
+    payload = {
+        "project_id": "proj-1",
+        "environment": "production",
+        "workflow_id": "wf-instance",
+        "instance_id": "inst-1",
+    }
+    payload.update(overrides)
+    encoded = base64.urlsafe_b64encode(json.dumps(payload).encode("utf-8")).decode("utf-8")
+    return encoded.rstrip("=")
+
+
 @pytest.mark.asyncio
 async def test_ai_workflow_create_run_requires_inline_definition():
     namespace = WorkflowSubNamespace(FakeClient())
@@ -253,6 +267,66 @@ async def test_saved_workflow_facade_lifecycle_contract_supports_processor_shape
     assert streamed == [{"_event": "workflow_start"}]
 
 
+@pytest.mark.asyncio
+async def test_workflow_ensure_supports_authority_one_call_lifecycle():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+
+    await namespace.ensure(
+        "wf://carebridge/report-cycle",
+        subject="PCM47474562",
+        company="summit-radiology",
+        inputs={"report_snapshot": "ar://artifact"},
+        target_project_id="proj-1",
+        target_environment="production",
+    )
+
+    assert client.calls[0]["endpoint"] == "/api/authority/runs/ensure"
+    body = client.calls[0]["body"]
+    assert body["workflow_ref"] == "wf://carebridge/report-cycle"
+    assert body["subject"] == "PCM47474562"
+    assert body["company"] == "summit-radiology"
+    assert body["inputs"] == {"report_snapshot": "ar://artifact"}
+    assert body["target_project_id"] == "proj-1"
+    assert body["target_environment"] == "production"
+    assert isinstance(body["idempotency_key"], str) and body["idempotency_key"]
+
+
+@pytest.mark.asyncio
+async def test_workflow_get_detects_authority_run_ids():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+    run_id = authority_run_id()
+
+    await namespace.get(run_id)
+
+    assert client.calls[0]["endpoint"] == f"/api/authority/runs/{run_id}"
+    assert client.calls[0]["method"] == "GET"
+
+
+@pytest.mark.asyncio
+async def test_workflow_retry_nudge_and_cancel_support_authority_run_ids():
+    client = FakeClient()
+    namespace = WorkflowNamespace(client)
+    run_id = authority_run_id()
+
+    await namespace.retry(run_id, reason="manual-retry")
+    await namespace.nudge(run_id, reason="new-input", trigger_artifact="artifact-1")
+    await namespace.cancel(run_id)
+
+    assert [call["endpoint"] for call in client.calls] == [
+        f"/api/authority/runs/{run_id}/retry",
+        f"/api/authority/runs/{run_id}/nudge",
+        f"/api/authority/runs/{run_id}/cancel",
+    ]
+    assert client.calls[0]["body"]["reason"] == "manual-retry"
+    assert client.calls[1]["body"]["reason"] == "new-input"
+    assert client.calls[1]["body"]["trigger_artifact"] == "artifact-1"
+    assert isinstance(client.calls[0]["body"]["idempotency_key"], str)
+    assert isinstance(client.calls[1]["body"]["idempotency_key"], str)
+    assert isinstance(client.calls[2]["body"]["idempotency_key"], str)
+
+
 @pytest.mark.asyncio
 async def test_execute_pipeline_routes_to_native_pipeline_runner():
     client = FakeClient()
@@ -314,3 +388,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",
+        )