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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.15.0
+Version: 2.16.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.12.0
+- Version: 2.16.0
 
 ## 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,14 @@ 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.
+- `dominus.artifacts.*` now supports addressed V2 artifact refs alongside legacy helpers. Prefer `store_v2()`, `head_v2()`, `compare_v2()`, bookmark helpers, and watcher helpers with canonical `ar://{group}/{owner}/{environment}/{kind}/{artifact_key}` refs for new code; `target_project_id` / `use_shared` remain compatibility-only targeting concepts.
 
 ## License
 

{dominus_sdk_python-2.15.0 → dominus_sdk_python-2.16.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.12.0
+- Version: 2.16.0
 
 ## 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,14 @@ 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.
+- `dominus.artifacts.*` now supports addressed V2 artifact refs alongside legacy helpers. Prefer `store_v2()`, `head_v2()`, `compare_v2()`, bookmark helpers, and watcher helpers with canonical `ar://{group}/{owner}/{environment}/{kind}/{artifact_key}` refs for new code; `target_project_id` / `use_shared` remain compatibility-only targeting concepts.
 
 ## License
 

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

@@ -101,7 +101,25 @@ from .namespaces.health import HealthNamespace
 from .namespaces.open import OpenNamespace
 
 # Export new namespaces (Node.js SDK parity)
-from .namespaces.artifacts import ArtifactsNamespace
+from .namespaces.artifacts import (
+    ARTIFACT_REF_PREFIX,
+    DISPLAY_REF_PREFIX,
+    ARTIFACT_ENVIRONMENTS,
+    ArtifactsNamespace,
+    build_artifact_ref,
+    build_v2_artifact_ref,
+    build_pinned_artifact_ref,
+    build_legacy_artifact_ref,
+    build_display_artifact_ref,
+    parse_artifact_ref,
+    try_parse_artifact_ref,
+    validate_artifact_address,
+    is_artifact_ref,
+    is_pinned_artifact_ref,
+    is_head_artifact_ref,
+    is_legacy_artifact_ref,
+    is_display_artifact_ref,
+)
 from .namespaces.jobs import JobsNamespace
 from .namespaces.processor import ProcessorNamespace
 from .namespaces.sync import SyncNamespace
@@ -138,6 +156,16 @@ from .helpers.core import (
     is_jwt_valid,
 )
 
+# Export trace utilities for distributed tracing
+from .helpers.trace import (
+    generate_trace_id,
+    get_current_trace_id,
+    get_current_span_id,
+    start_trace,
+    end_trace,
+    with_trace,
+)
+
 # Export error classes
 from .errors import (
     DominusError,
@@ -152,7 +180,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "2.15.0"
+__version__ = "2.16.0"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -182,7 +210,23 @@ __all__ = [
     "HealthNamespace",
     "OpenNamespace",
     # New namespaces (Node.js SDK parity)
+    "ARTIFACT_REF_PREFIX",
+    "DISPLAY_REF_PREFIX",
+    "ARTIFACT_ENVIRONMENTS",
     "ArtifactsNamespace",
+    "build_artifact_ref",
+    "build_v2_artifact_ref",
+    "build_pinned_artifact_ref",
+    "build_legacy_artifact_ref",
+    "build_display_artifact_ref",
+    "parse_artifact_ref",
+    "try_parse_artifact_ref",
+    "validate_artifact_address",
+    "is_artifact_ref",
+    "is_pinned_artifact_ref",
+    "is_head_artifact_ref",
+    "is_legacy_artifact_ref",
+    "is_display_artifact_ref",
     "JobsNamespace",
     "ProcessorNamespace",
     "SyncNamespace",
@@ -206,6 +250,13 @@ __all__ = [
     # JWT verification utilities
     "verify_jwt_locally",
     "is_jwt_valid",
+    # Trace utilities
+    "generate_trace_id",
+    "get_current_trace_id",
+    "get_current_span_id",
+    "start_trace",
+    "end_trace",
+    "with_trace",
     # Error classes
     "DominusError",
     "AuthenticationError",

{dominus_sdk_python-2.15.0 → dominus_sdk_python-2.16.0}/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.15.0 → dominus_sdk_python-2.16.0}/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.15.0 → dominus_sdk_python-2.16.0}/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
@@ -112,8 +112,13 @@ async def _fetch_jwks() -> dict:
     proxy_config = get_proxy_config()
 
     try:
+        from .trace import get_current_trace_id, get_current_span_id
+        jwks_headers = {
+            "X-Trace-Id": get_current_trace_id(),
+            "X-Parent-Span-Id": get_current_span_id(),
+        }
         async with httpx.AsyncClient(timeout=10.0, proxy=proxy_config) as client:
-            response = await client.get(f"{gateway_url}/jwt/jwks")
+            response = await client.get(f"{gateway_url}/jwt/jwks", headers=jwks_headers)
             response.raise_for_status()
 
             # Response is base64 encoded
@@ -339,18 +344,21 @@ 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()
 
+    from .trace import get_current_trace_id, get_current_span_id
     headers = {
         "Authorization": f"Bearer {psk_token}",
-        "Content-Type": "text/plain"
+        "Content-Type": "text/plain",
+        "X-Trace-Id": get_current_trace_id(),
+        "X-Parent-Span-Id": get_current_span_id(),
     }
 
     # Body format for gateway /jwt/mint endpoint
@@ -384,17 +392,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 +415,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 +428,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}")
 
 
@@ -541,9 +549,12 @@ async def delegate_jwt(
     gateway_url = get_gateway_url()
     proxy_config = get_proxy_config()
 
+    from .trace import get_current_trace_id, get_current_span_id
     headers = {
         "Authorization": f"Bearer {psk_token}",
-        "Content-Type": "text/plain"
+        "Content-Type": "text/plain",
+        "X-Trace-Id": get_current_trace_id(),
+        "X-Parent-Span-Id": get_current_span_id(),
     }
 
     # Body format for /jwt/delegate endpoint
@@ -704,7 +715,11 @@ async def execute_with_retry(
     for attempt in range(MAX_RETRIES):
         try:
             # Prepare headers
-            headers = {}
+            from .trace import get_current_trace_id, get_current_span_id
+            headers = {
+                "X-Trace-Id": get_current_trace_id(),
+                "X-Parent-Span-Id": get_current_span_id(),
+            }
             if requires_auth:
                 headers["Authorization"] = f"Bearer {_b64_token(token)}"
 
@@ -827,9 +842,12 @@ async def execute_bridge_call(
     jwt = await _ensure_valid_jwt(token, base_url)
 
     # Prepare Bridge API request with JWT
+    from .trace import get_current_trace_id, get_current_span_id
     headers = {
         "Authorization": f"Bearer {jwt}",
-        "Content-Type": "text/plain"
+        "Content-Type": "text/plain",
+        "X-Trace-Id": get_current_trace_id(),
+        "X-Parent-Span-Id": get_current_span_id(),
     }
 
     # Body format: {"method": "...", "params": {...}}
@@ -972,8 +990,11 @@ async def _execute_auth_call(
     gateway_url = get_gateway_url()
     proxy_config = get_proxy_config()
 
+    from .trace import get_current_trace_id, get_current_span_id
     headers = {
-        "Content-Type": "text/plain"
+        "Content-Type": "text/plain",
+        "X-Trace-Id": get_current_trace_id(),
+        "X-Parent-Span-Id": get_current_span_id(),
     }
 
     # Add PSK header only if token provided (auth.jwks is public)

dominus_sdk_python-2.16.0/dominus/helpers/trace.py

@@ -0,0 +1,97 @@
+"""
+Distributed Tracing Module for Dominus Python SDK.
+
+Provides contextvars-based trace context propagation.
+Every SDK HTTP request automatically includes X-Trace-Id and X-Parent-Span-Id headers.
+
+Usage patterns:
+
+    # Auto mode (default) — each request gets a unique trace_id
+    await dominus.db.query("users")
+
+    # Manual grouping — all requests within scope share one trace_id
+    async with with_trace() as trace_id:
+        await dominus.db.query("users")
+        await dominus.logs.info("queried users")
+
+    # Imperative scope
+    trace_id = start_trace()
+    await dominus.db.query("users")
+    end_trace()
+"""
+
+import uuid
+from contextvars import ContextVar
+from contextlib import asynccontextmanager
+from typing import Optional
+
+
+# ContextVar for trace ID — safe for concurrent async tasks
+_active_trace_id: ContextVar[Optional[str]] = ContextVar("_active_trace_id", default=None)
+
+
+def generate_trace_id() -> str:
+    """Generate a new trace ID (UUID v4)."""
+    return str(uuid.uuid4())
+
+
+def get_current_trace_id() -> str:
+    """Get the current trace ID from context.
+
+    - If inside a ``with_trace()`` or ``start_trace()`` scope, returns the scoped trace_id.
+    - Otherwise, generates a new unique trace_id per call (auto mode).
+    """
+    return _active_trace_id.get() or generate_trace_id()
+
+
+def get_current_span_id() -> str:
+    """Generate a per-call span ID for parent-child tracking.
+
+    Each SDK HTTP call is a sub-span. The span_id generated here
+    is sent as X-Parent-Span-Id so the callee service knows its parent span.
+    """
+    return str(uuid.uuid4())
+
+
+def start_trace() -> str:
+    """Start a manual trace scope.
+
+    Sets the trace_id in the current context. All SDK requests
+    in this context will share the same trace_id.
+
+    Returns:
+        The new trace_id
+    """
+    trace_id = generate_trace_id()
+    _active_trace_id.set(trace_id)
+    return trace_id
+
+
+def end_trace() -> None:
+    """End the current manual trace scope.
+
+    Clears the trace_id from context so subsequent calls
+    revert to auto-mode (unique trace_id per call).
+    """
+    _active_trace_id.set(None)
+
+
+@asynccontextmanager
+async def with_trace():
+    """Async context manager for trace grouping.
+
+    All SDK requests within the ``async with`` block share one trace_id.
+    Safe for concurrent async tasks — uses contextvars.
+
+    Usage::
+
+        async with with_trace() as trace_id:
+            await dominus.db.query("users")
+            await dominus.logs.info("queried users")
+    """
+    trace_id = generate_trace_id()
+    token = _active_trace_id.set(trace_id)
+    try:
+        yield trace_id
+    finally:
+        _active_trace_id.reset(token)