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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.15.1
+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.15.1
+- Version: 2.16.0
 
 ## Quick Start
 
@@ -192,6 +192,7 @@ dominus.release_console()     # stop capturing
 - `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.1 → 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.15.1
+- Version: 2.16.0
 
 ## Quick Start
 
@@ -150,6 +150,7 @@ dominus.release_console()     # stop capturing
 - `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.1 → 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.1"
+__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.1 → dominus_sdk_python-2.16.0}/dominus/helpers/core.py

@@ -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
@@ -348,9 +353,12 @@ async def _get_service_jwt(psk_token: str, base_url: str) -> str:
     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
@@ -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)