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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.17.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.17.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.17.0 → dominus_sdk_python-2.18.0}/dominus/__init__.py

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

{dominus_sdk_python-2.17.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
 
@@ -154,6 +157,90 @@ class WorkflowNamespace:
             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,
@@ -240,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")
 
@@ -693,15 +790,56 @@ class WorkflowNamespace:
         workflow_id: str,
         *,
         instance_id: Optional[str] = None,
-        group: str,
-        owner: str,
+        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,
@@ -815,6 +953,50 @@ class WorkflowNamespace:
         )
         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
@@ -855,13 +1037,35 @@ class WorkflowNamespace:
     async def nudge(
         self,
         workflow_id: str,
-        instance_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,
@@ -921,13 +1125,35 @@ class WorkflowNamespace:
     async def retry(
         self,
         workflow_id: str,
-        instance_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,
@@ -1130,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.17.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.17.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.17.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.17.0"
+version = "2.18.0"
 description = "Python SDK for the Dominus Orchestrator Platform"
 readme = "README.md"
 license = {text = "Proprietary"}

{dominus_sdk_python-2.17.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()