dominus-sdk-python 2.14.0__tar.gz → 2.15.1__tar.gz

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.14.0
+Version: 2.15.1
 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.12.0
+- Version: 2.15.1
 
 ## Quick Start
 
@@ -89,8 +89,20 @@ async for chunk in dominus.ai.stream_agent(
 ):
     print(chunk.get("content", ""), end="", flush=True)
 
-# Workflow execution
-result = await dominus.workflow.execute(workflow_id, context={"key": "value"})
+# Saved workflow lifecycle through workflow-manager
+run = await dominus.workflow.create_run(
+    workflow_id="wf_saved_123",
+    context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},
+)
+await dominus.workflow.validate_run(run["run_id"])
+result = await dominus.workflow.start_run(run["run_id"])
+
+# Raw orchestration lifecycle with inline workflow definition
+raw_run = await dominus.ai.workflow.create_run(
+    workflow_definition={"workflow": {"name": "raw"}, "agents": {}, "artifacts": {}},
+)
+await dominus.ai.workflow.validate_run(raw_run["run_id"])
+raw_result = await dominus.ai.workflow.start_run(raw_run["run_id"])
 ```
 
 ## Architecture (SDK View)
@@ -116,7 +128,7 @@ DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
 | `secrets` | Warden | Secrets CRUD |
 | `db` | Scribe | Database CRUD with optional secure-table audit |
 | `secure` / `db_secure` | Scribe | Audit-logged data access (requires reason/actor) |
-| `redis` | Whisperer | Cache, locks, counters, hashes |
+| `redis` | Redis Worker | Cache, locks, counters, hashes |
 | `files` | Archivist | Object storage with compliance mode |
 | `auth` | Guardian | Users, roles, scopes, tenants, clients, pages, nav, subtypes, secure tables (147 methods) |
 | `ddl` | Smith | Schema DDL, migrations, tenant provisioning, schema builder |
@@ -127,7 +139,7 @@ DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
 | `health` | Orchestrator | Health/ping/warmup |
 | `admin` | Admin | Reseed/reset admin category |
 | `ai` | Agent Runtime | Agent execution, LLM completions, RAG, artifacts, results, orchestration, STT/TTS |
-| `workflow` | Workflow Manager | Workflow CRUD, categories/pipelines, templates, execution |
+| `workflow` | Workflow Manager | Workflow CRUD, pipelines/templates, saved-workflow run lifecycle, native pipeline runner |
 | `oracle` / `stt` | Oracle | Real-time streaming STT with VAD (WebSocket, requires `oracle` extras) |
 | `fastapi` | Local | FastAPI route auth decorators (`@jwt`, `@psk`, `@scopes`) |
 
@@ -173,6 +185,13 @@ dominus.release_console()     # stop capturing
 - [Architecture](docs/architecture.md) -- Request flow, resilience, JWT verification
 - [Services Reference](docs/services.md) -- Complete namespace and method inventory
 - [Development](docs/development.md) -- Setup, testing, adding APIs
+- [Workflow hard-cut release notes](docs/workflow-hard-cut-release.md) -- cutover notes and operational checks
+
+## Workflow Surfaces
+
+- `dominus.workflow.*` is the saved-workflow facade through `dominus-workflow-manager`. Use it for stored workflow IDs and the artifact-aware run lifecycle: `create_run -> register_artifact -> validate_run -> start_run`.
+- `dominus.ai.workflow.*` is the raw orchestration surface. It requires inline `workflow_definition` data. It does not support saved-workflow IDs directly.
+- `dominus.workflow.execute_pipeline()` runs stored pipelines through workflow-manager's native orchestration-backed runner.
 
 ## License
 

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/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.12.0
+- Version: 2.15.1
 
 ## Quick Start
 
@@ -47,8 +47,20 @@ async for chunk in dominus.ai.stream_agent(
 ):
     print(chunk.get("content", ""), end="", flush=True)
 
-# Workflow execution
-result = await dominus.workflow.execute(workflow_id, context={"key": "value"})
+# Saved workflow lifecycle through workflow-manager
+run = await dominus.workflow.create_run(
+    workflow_id="wf_saved_123",
+    context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},
+)
+await dominus.workflow.validate_run(run["run_id"])
+result = await dominus.workflow.start_run(run["run_id"])
+
+# Raw orchestration lifecycle with inline workflow definition
+raw_run = await dominus.ai.workflow.create_run(
+    workflow_definition={"workflow": {"name": "raw"}, "agents": {}, "artifacts": {}},
+)
+await dominus.ai.workflow.validate_run(raw_run["run_id"])
+raw_result = await dominus.ai.workflow.start_run(raw_run["run_id"])
 ```
 
 ## Architecture (SDK View)
@@ -74,7 +86,7 @@ DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
 | `secrets` | Warden | Secrets CRUD |
 | `db` | Scribe | Database CRUD with optional secure-table audit |
 | `secure` / `db_secure` | Scribe | Audit-logged data access (requires reason/actor) |
-| `redis` | Whisperer | Cache, locks, counters, hashes |
+| `redis` | Redis Worker | Cache, locks, counters, hashes |
 | `files` | Archivist | Object storage with compliance mode |
 | `auth` | Guardian | Users, roles, scopes, tenants, clients, pages, nav, subtypes, secure tables (147 methods) |
 | `ddl` | Smith | Schema DDL, migrations, tenant provisioning, schema builder |
@@ -85,7 +97,7 @@ DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
 | `health` | Orchestrator | Health/ping/warmup |
 | `admin` | Admin | Reseed/reset admin category |
 | `ai` | Agent Runtime | Agent execution, LLM completions, RAG, artifacts, results, orchestration, STT/TTS |
-| `workflow` | Workflow Manager | Workflow CRUD, categories/pipelines, templates, execution |
+| `workflow` | Workflow Manager | Workflow CRUD, pipelines/templates, saved-workflow run lifecycle, native pipeline runner |
 | `oracle` / `stt` | Oracle | Real-time streaming STT with VAD (WebSocket, requires `oracle` extras) |
 | `fastapi` | Local | FastAPI route auth decorators (`@jwt`, `@psk`, `@scopes`) |
 
@@ -131,6 +143,13 @@ dominus.release_console()     # stop capturing
 - [Architecture](docs/architecture.md) -- Request flow, resilience, JWT verification
 - [Services Reference](docs/services.md) -- Complete namespace and method inventory
 - [Development](docs/development.md) -- Setup, testing, adding APIs
+- [Workflow hard-cut release notes](docs/workflow-hard-cut-release.md) -- cutover notes and operational checks
+
+## Workflow Surfaces
+
+- `dominus.workflow.*` is the saved-workflow facade through `dominus-workflow-manager`. Use it for stored workflow IDs and the artifact-aware run lifecycle: `create_run -> register_artifact -> validate_run -> start_run`.
+- `dominus.ai.workflow.*` is the raw orchestration surface. It requires inline `workflow_definition` data. It does not support saved-workflow IDs directly.
+- `dominus.workflow.execute_pipeline()` runs stored pipelines through workflow-manager's native orchestration-backed runner.
 
 ## License
 

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/dominus/__init__.py

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

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/dominus/config/endpoints.py

@@ -37,7 +37,7 @@ LOGS_URL = os.environ.get("DOMINUS_LOGS_URL", _DEFAULT_LOGS_URL)
 BASE_URL = os.environ.get("DOMINUS_BASE_URL", _DEFAULT_BASE_URL)
 
 # Legacy aliases (all point to orchestrator now) - DEPRECATED
-SOVEREIGN_URL = BASE_URL
+SOVEREIGN_URL = BASE_URL  # Deprecated: use BASE_URL or get_gateway_url()
 ARCHITECT_URL = BASE_URL
 ORCHESTRATOR_URL = BASE_URL
 WARDEN_URL = BASE_URL
@@ -107,7 +107,7 @@ def get_base_url() -> str:
 
 # DEPRECATED - use get_base_url()
 def get_sovereign_url(environment: str = None) -> str:
-    """Deprecated: Use get_base_url() instead."""
+    """Deprecated: Use get_base_url() instead. 'Sovereign' is the legacy name for the gateway."""
     return BASE_URL
 
 

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/dominus/helpers/cache.py

@@ -197,4 +197,4 @@ orchestrator_circuit_breaker = CircuitBreaker(
 )
 
 # Backward compatibility alias
-sovereign_circuit_breaker = orchestrator_circuit_breaker
+gateway_circuit_breaker = orchestrator_circuit_breaker

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/dominus/helpers/core.py

@@ -11,7 +11,7 @@ import json
 import time
 from typing import Any, Optional
 
-from .cache import dominus_cache, sovereign_circuit_breaker, exponential_backoff_with_jitter
+from .cache import dominus_cache, gateway_circuit_breaker, exponential_backoff_with_jitter
 
 # Max retries for HTTP requests (reduced from implicit to explicit)
 MAX_RETRIES = 3
@@ -339,14 +339,14 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     proxy_config = get_proxy_config()
 
     # Circuit breaker check
-    if not sovereign_circuit_breaker.can_execute():
+    if not gateway_circuit_breaker.can_execute():
         raise RuntimeError(
             f"Circuit breaker OPEN for auth - "
             f"too many recent failures. Will retry after recovery timeout."
         )
 
-    if sovereign_circuit_breaker.state == sovereign_circuit_breaker.HALF_OPEN:
-        sovereign_circuit_breaker.record_half_open_call()
+    if gateway_circuit_breaker.state == gateway_circuit_breaker.HALF_OPEN:
+        gateway_circuit_breaker.record_half_open_call()
 
     headers = {
         "Authorization": f"Bearer {psk_token}",
@@ -384,17 +384,17 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
 
                 if not result.get("success"):
                     error_msg = result.get("error", "Unknown auth error")
-                    sovereign_circuit_breaker.record_failure()
+                    gateway_circuit_breaker.record_failure()
                     raise RuntimeError(f"Auth error: {error_msg}")
 
                 data = result.get("data", {})
                 jwt = data.get("access_token") or data.get("token")
                 if not jwt:
-                    sovereign_circuit_breaker.record_failure()
+                    gateway_circuit_breaker.record_failure()
                     raise RuntimeError("No JWT token in auth response")
 
                 # Success - record it
-                sovereign_circuit_breaker.record_success()
+                gateway_circuit_breaker.record_success()
                 return jwt
 
         except httpx.TimeoutException as e:
@@ -407,7 +407,7 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 )
                 await asyncio.sleep(delay)
                 continue
-            sovereign_circuit_breaker.record_failure()
+            gateway_circuit_breaker.record_failure()
             raise RuntimeError(f"Failed to get JWT: {e}") from e
 
         except httpx.NetworkError as e:
@@ -420,21 +420,21 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
                 )
                 await asyncio.sleep(delay)
                 continue
-            sovereign_circuit_breaker.record_failure()
+            gateway_circuit_breaker.record_failure()
             raise RuntimeError(f"Failed to get JWT: {e}") from e
 
         except httpx.HTTPStatusError as e:
             last_error = e
             # 4xx errors (except 401 which is retried above) should not be retried
             if 400 <= e.response.status_code < 500 and e.response.status_code != 401:
-                sovereign_circuit_breaker.record_failure()
+                gateway_circuit_breaker.record_failure()
                 raise RuntimeError(f"Failed to get JWT: {e}") from e
             # For other errors, we've already handled retries in the status check above
-            sovereign_circuit_breaker.record_failure()
+            gateway_circuit_breaker.record_failure()
             raise RuntimeError(f"Failed to get JWT: {e}") from e
 
     # Should not reach here, but just in case
-    sovereign_circuit_breaker.record_failure()
+    gateway_circuit_breaker.record_failure()
     raise RuntimeError(f"Failed to get JWT after {JWT_MINT_RETRIES} retries: {last_error}")
 
 

{dominus_sdk_python-2.14.0 → dominus_sdk_python-2.15.1}/dominus/namespaces/ai.py

@@ -565,32 +565,95 @@ class WorkflowSubNamespace(GatewayMixin):
     def __init__(self, client: "Dominus"):
         self._client = client
 
+    @staticmethod
+    def _require_inline_workflow_definition(
+        workflow_definition: Optional[Dict[str, Any]],
+        workflow_id: Optional[str],
+        method_name: str,
+    ) -> Dict[str, Any]:
+        if isinstance(workflow_definition, dict):
+            return workflow_definition
+        if workflow_id:
+            raise ValueError(
+                f"dominus.ai.workflow.{method_name}() does not support saved workflow IDs. "
+                "Pass workflow_definition for raw orchestration or use dominus.workflow.create_run() "
+                "for saved-workflow execution."
+            )
+        raise ValueError(
+            f"dominus.ai.workflow.{method_name}() requires workflow_definition for raw orchestration execution."
+        )
+
+    @staticmethod
+    def _build_start_config(
+        *,
+        mode: Optional[str] = None,
+        timeout_seconds: Optional[int] = None,
+        save_events: Optional[bool] = None,
+        webhook_url: Optional[str] = None,
+        environment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        config: Dict[str, Any] = {}
+        if mode:
+            config["mode"] = mode
+        if timeout_seconds is not None:
+            config["timeout_seconds"] = timeout_seconds
+        if save_events is not None:
+            config["save_events"] = save_events
+        if webhook_url:
+            config["webhook_url"] = webhook_url
+        if environment:
+            config["environment"] = environment
+        return config
+
     async def execute(
         self,
-        workflow_id: str,
-        input: Dict[str, Any],
+        workflow_definition: Optional[Dict[str, Any]] = None,
+        *,
+        workflow_id: Optional[str] = None,
+        initial_artifacts: Optional[Dict[str, Any]] = None,
+        input: Optional[Dict[str, Any]] = None,
         conversation_id: Optional[str] = None,
         mode: str = "blocking",
-        webhook_url: Optional[str] = None
+        webhook_url: Optional[str] = None,
+        timeout_seconds: Optional[int] = None,
+        save_events: Optional[bool] = None,
+        environment: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
-        Execute a multi-agent workflow.
+        Execute a raw orchestration workflow definition.
 
         Args:
-            workflow_id: Workflow identifier
-            input: Workflow input data
+            workflow_definition: Inline orchestration workflow definition
+            workflow_id: Unsupported for raw orchestration; use dominus.workflow.create_run()
+            initial_artifacts: Initial artifact key -> artifact ID mapping
+            input: Legacy alias for initial_artifacts
             conversation_id: Optional conversation ID for context
             mode: Execution mode ("blocking", "streaming", "async")
             webhook_url: Optional webhook for completion notification
+            timeout_seconds: Optional execution timeout
+            save_events: Whether to persist execution events
+            environment: Optional execution environment override
 
         Returns:
             Dict with "execution_id", "status", "output" (if blocking)
         """
         body: Dict[str, Any] = {
-            "workflow_id": workflow_id,
-            "input": input,
-            "mode": mode
+            "workflow_definition": self._require_inline_workflow_definition(
+                workflow_definition,
+                workflow_id,
+                "execute",
+            ),
         }
+        if initial_artifacts:
+            body["initial_artifacts"] = initial_artifacts
+        elif input:
+            body["initial_artifacts"] = input
+        body["config"] = self._build_start_config(
+            mode=mode,
+            timeout_seconds=timeout_seconds,
+            save_events=save_events,
+            environment=environment,
+        )
         if conversation_id:
             body["conversation_id"] = conversation_id
         if webhook_url:
@@ -601,6 +664,50 @@ class WorkflowSubNamespace(GatewayMixin):
             body=body
         )
 
+    async def stream_execute(
+        self,
+        workflow_definition: Optional[Dict[str, Any]] = None,
+        *,
+        workflow_id: Optional[str] = None,
+        initial_artifacts: Optional[Dict[str, Any]] = None,
+        input: Optional[Dict[str, Any]] = None,
+        conversation_id: Optional[str] = None,
+        timeout_seconds: Optional[int] = None,
+        save_events: Optional[bool] = None,
+        environment: Optional[str] = None,
+        on_chunk: Optional[Callable[[Dict[str, Any]], None]] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Execute a raw orchestration workflow definition with SSE streaming.
+        """
+        body: Dict[str, Any] = {
+            "workflow_definition": self._require_inline_workflow_definition(
+                workflow_definition,
+                workflow_id,
+                "stream_execute",
+            ),
+            "config": self._build_start_config(
+                mode="streaming",
+                timeout_seconds=timeout_seconds,
+                save_events=save_events,
+                environment=environment,
+            ),
+        }
+        if initial_artifacts:
+            body["initial_artifacts"] = initial_artifacts
+        elif input:
+            body["initial_artifacts"] = input
+        if conversation_id:
+            body["conversation_id"] = conversation_id
+
+        async for chunk in self._api_stream(
+            endpoint="/api/orchestration/execute",
+            body=body,
+            on_chunk=on_chunk,
+            timeout=float(timeout_seconds or 600),
+        ):
+            yield chunk
+
     async def validate(
         self,
         workflow_definition: Dict[str, Any]
@@ -616,35 +723,40 @@ class WorkflowSubNamespace(GatewayMixin):
         """
         return await self._api(
             endpoint="/api/orchestration/validate",
-            body={"definition": workflow_definition}
+            body={"workflow_definition": workflow_definition}
         )
 
     async def messages(
         self,
         execution_id: str,
-        limit: int = 100,
-        offset: int = 0
+        count: int = 50,
     ) -> List[Dict[str, Any]]:
         """Get messages from an execution."""
         result = await self._api(
-            endpoint=f"/api/orchestration/messages/{execution_id}",
-            body={"limit": limit, "offset": offset}
+            endpoint=f"/api/orchestration/messages/{execution_id}?count={count}",
+            method="GET",
         )
         return result.get("messages", result) if isinstance(result, dict) else result
 
     async def events(
         self,
         execution_id: str,
-        from_timestamp: Optional[str] = None
+        from_id: Optional[str] = None,
+        count: Optional[int] = None,
     ) -> List[Dict[str, Any]]:
         """Replay events from an execution."""
-        body: Dict[str, Any] = {}
-        if from_timestamp:
-            body["from"] = from_timestamp
+        query = []
+        if from_id:
+            query.append(f"from_id={from_id}")
+        if count is not None:
+            query.append(f"count={count}")
+        endpoint = f"/api/orchestration/events/{execution_id}"
+        if query:
+            endpoint += f"?{'&'.join(query)}"
 
         result = await self._api(
-            endpoint=f"/api/orchestration/events/{execution_id}",
-            body=body if body else None
+            endpoint=endpoint,
+            method="GET",
         )
         return result.get("events", result) if isinstance(result, dict) else result
 
@@ -662,6 +774,158 @@ class WorkflowSubNamespace(GatewayMixin):
             method="GET"
         )
 
+    async def cancel(self, execution_id: str) -> Dict[str, Any]:
+        """Cancel a running workflow execution."""
+        return await self._api(
+            endpoint=f"/api/orchestration/cancel/{execution_id}",
+            body={},
+        )
+
+    async def create_run(
+        self,
+        workflow_definition: Optional[Dict[str, Any]] = None,
+        *,
+        workflow_id: Optional[str] = None,
+        run_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        environment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Create a raw orchestration run for the two-phase lifecycle.
+        """
+        body: Dict[str, Any] = {
+            "workflow_definition": self._require_inline_workflow_definition(
+                workflow_definition,
+                workflow_id,
+                "create_run",
+            ),
+        }
+        if run_id:
+            body["run_id"] = run_id
+        if metadata:
+            body["metadata"] = metadata
+        if environment:
+            body["environment"] = environment
+
+        return await self._api(
+            endpoint="/api/orchestration/runs",
+            body=body,
+        )
+
+    async def get_run(self, run_id: str) -> Dict[str, Any]:
+        """Get raw orchestration run state."""
+        return await self._api(
+            endpoint=f"/api/orchestration/runs/{run_id}",
+            method="GET",
+        )
+
+    async def get_manifest(self, run_id: str) -> Dict[str, Any]:
+        """Get the required-artifact manifest for a raw orchestration run."""
+        return await self._api(
+            endpoint=f"/api/orchestration/runs/{run_id}/manifest",
+            method="GET",
+        )
+
+    async def register_artifact(
+        self,
+        run_id: str,
+        artifact_key: str,
+        artifact_id: str,
+        *,
+        source_namespace: str = "conversation",
+        source_conversation_id: Optional[str] = None,
+        source_project: Optional[str] = None,
+        source_env: Optional[str] = None,
+        source_project_id: Optional[str] = None,
+        source_tenant: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        metadata_trusted: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """
+        Register an uploaded artifact with a raw orchestration run.
+        """
+        body: Dict[str, Any] = {
+            "artifact_key": artifact_key,
+            "artifact_id": artifact_id,
+        }
+        if source_namespace:
+            body["source_namespace"] = source_namespace
+        if source_conversation_id:
+            body["source_conversation_id"] = source_conversation_id
+        if source_project:
+            body["source_project"] = source_project
+        if source_env:
+            body["source_env"] = source_env
+        if source_project_id:
+            body["source_project_id"] = source_project_id
+        if source_tenant:
+            body["source_tenant"] = source_tenant
+        if metadata:
+            body["metadata"] = metadata
+        if metadata_trusted is not None:
+            body["metadata_trusted"] = metadata_trusted
+
+        return await self._api(
+            endpoint=f"/api/orchestration/runs/{run_id}/artifacts",
+            body=body,
+        )
+
+    async def validate_run(self, run_id: str) -> Dict[str, Any]:
+        """Validate that a raw orchestration run is ready to start."""
+        return await self._api(
+            endpoint=f"/api/orchestration/runs/{run_id}/validate",
+            body={},
+        )
+
+    async def start_run(
+        self,
+        run_id: str,
+        *,
+        mode: str = "blocking",
+        timeout_seconds: Optional[int] = None,
+        save_events: Optional[bool] = None,
+        webhook_url: Optional[str] = None,
+        environment: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start a raw orchestration run after artifacts are registered."""
+        return await self._api(
+            endpoint=f"/api/orchestration/runs/{run_id}/start",
+            body={
+                "config": self._build_start_config(
+                    mode=mode,
+                    timeout_seconds=timeout_seconds,
+                    save_events=save_events,
+                    webhook_url=webhook_url,
+                    environment=environment,
+                )
+            },
+        )
+
+    async def stream_start_run(
+        self,
+        run_id: str,
+        *,
+        timeout_seconds: Optional[int] = None,
+        save_events: Optional[bool] = None,
+        environment: Optional[str] = None,
+        on_chunk: Optional[Callable[[Dict[str, Any]], None]] = None,
+    ) -> AsyncGenerator[Dict[str, Any], None]:
+        """Start a raw orchestration run with SSE streaming."""
+        async for chunk in self._api_stream(
+            endpoint=f"/api/orchestration/runs/{run_id}/start",
+            body={
+                "config": self._build_start_config(
+                    mode="streaming",
+                    timeout_seconds=timeout_seconds,
+                    save_events=save_events,
+                    environment=environment,
+                )
+            },
+            on_chunk=on_chunk,
+            timeout=float(timeout_seconds or 600),
+        ):
+            yield chunk
+
 
 # ========================================
 # Main AI Namespace