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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 2.17.0
+Version: 2.18.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.16.0
+- Version: 2.18.1
 
 ## 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.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.16.0
+- Version: 2.18.1
 
 ## 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.1}/dominus/__init__.py

@@ -154,6 +154,8 @@ from .helpers.cache import (
 from .helpers.core import (
     verify_jwt_locally,
     is_jwt_valid,
+    mint_selected_project_jwt,
+    delegate_jwt,
 )
 
 # Export trace utilities for distributed tracing
@@ -180,7 +182,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "2.17.0"
+__version__ = "2.18.1"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -250,6 +252,8 @@ __all__ = [
     # JWT verification utilities
     "verify_jwt_locally",
     "is_jwt_valid",
+    "mint_selected_project_jwt",
+    "delegate_jwt",
     # Trace utilities
     "generate_trace_id",
     "get_current_trace_id",

{dominus_sdk_python-2.17.0 → dominus_sdk_python-2.18.1}/dominus/helpers/core.py

@@ -521,29 +521,31 @@ async def _ensure_valid_jwt(psk_token: str, sovereign_url: str) -> str:
         return jwt
 
 
-async def delegate_jwt(
+async def mint_selected_project_jwt(
     psk_token: str,
     target_project_id: str,
     target_environment: str,
     use_shared: bool = False
 ) -> str:
     """
-    Mint a delegated JWT for a target project.
+    Mint a selected-project JWT for a target project.
 
-    This is used by admin-level services (like MCP) to get JWTs
-    that allow operations on behalf of other projects.
+    This is used by admin-level services to act within a selected project
+    context. The compatibility route name remains `/jwt/delegate`, but
+    the canonical contract is selected-project targeting, not a separate
+    delegated token family.
 
     Args:
         psk_token: Admin PSK token (DOMINUS_TOKEN for admin project)
         target_project_id: UUID of the target project
         target_environment: Environment (development, staging, production)
-        use_shared: If True, includes shared_project_id in claims
+        use_shared: Deprecated compatibility flag; selected-project JWTs infer shared context from the target project
 
     Returns:
-        Delegated JWT token string with system=delegated
+        Selected-project JWT string
 
     Raises:
-        RuntimeError: If delegation fails
+        RuntimeError: If selected-project minting fails
     """
     from ..config.endpoints import get_gateway_url, get_proxy_config
     gateway_url = get_gateway_url()
@@ -557,13 +559,11 @@ async def delegate_jwt(
         "X-Parent-Span-Id": get_current_span_id(),
     }
 
-    # Body format for /jwt/delegate endpoint
     body_json = {
         "target_project_id": target_project_id,
         "target_environment": target_environment
     }
-    if use_shared:
-        body_json["use_shared"] = True
+    _ = use_shared
 
     body_b64 = _b64_encode(body_json)
 
@@ -576,13 +576,13 @@ async def delegate_jwt(
             result = _b64_decode(response.text)
 
             if not result.get("success"):
-                error_msg = result.get("error", "Unknown delegation error")
-                raise RuntimeError(f"Delegation error: {error_msg}")
+                error_msg = result.get("error", "Unknown selected-project mint error")
+                raise RuntimeError(f"Selected-project mint error: {error_msg}")
 
             data = result.get("data", {})
             jwt = data.get("token") or data.get("access_token")
             if not jwt:
-                raise RuntimeError("No JWT token in delegation response")
+                raise RuntimeError("No JWT token in selected-project mint response")
 
             return jwt
 
@@ -594,10 +594,31 @@ async def delegate_jwt(
                 error_detail = error_body.get("error") or str(error_body)
         except Exception:
             error_detail = e.response.text[:200] if e.response.text else str(e)
-        raise RuntimeError(f"Delegation failed: {error_detail}") from e
+        raise RuntimeError(f"Selected-project JWT mint failed: {error_detail}") from e
 
     except Exception as e:
-        raise RuntimeError(f"Delegation failed: {e}") from e
+        raise RuntimeError(f"Selected-project JWT mint failed: {e}") from e
+
+
+async def delegate_jwt(
+    psk_token: str,
+    target_project_id: str,
+    target_environment: str,
+    use_shared: bool = False
+) -> str:
+    """
+    Compatibility alias for :func:`mint_selected_project_jwt`.
+
+    .. deprecated::
+        Prefer :func:`mint_selected_project_jwt` for new code; "delegated" naming is
+        legacy terminology only.
+    """
+    return await mint_selected_project_jwt(
+        psk_token=psk_token,
+        target_project_id=target_project_id,
+        target_environment=target_environment,
+        use_shared=use_shared,
+    )
 
 
 def verify_token_format(token: str) -> bool:

{dominus_sdk_python-2.17.0 → dominus_sdk_python-2.18.1}/dominus/namespaces/artifacts.py

@@ -4,10 +4,14 @@ Artifacts Namespace - Temporary artifact storage.
 Provides auto-tiered artifact storage (Redis < 1MB, B2 >= 1MB)
 with TTL-based expiration. Routes through gateway to artifact-worker.
 
+The artifact worker returns HTTP 410 for legacy paths (/store, /retrieve, /list, /delete).
+This SDK only calls /api/artifact/v2/*; convenience ``store``/``retrieve``/``delete`` map
+those shapes to V2 compatibility addressing (see ``store_v2`` for canonical addressed writes).
+
 Usage:
     from dominus import dominus
 
-    # Store
+    # Prefer store_v2 / addressed refs for new code; legacy-shaped store maps to V2 internally
     result = await dominus.artifacts.store(data="base64data...", ttl_seconds=7200)
 
     # Retrieve
@@ -271,6 +275,21 @@ class ArtifactsNamespace:
     def __init__(self, client: "Dominus"):
         self._client = client
 
+    async def _legacy_project_context(self) -> tuple[str, str]:
+        """project_id and env from the cached service JWT (for V1-shaped -> V2 compat calls)."""
+        from ..helpers.core import _ensure_valid_jwt
+        from ..start import _BASE_URL, _TOKEN
+
+        jwt = await _ensure_valid_jwt(_TOKEN, _BASE_URL)
+        claims = await self._client.validate_jwt(jwt)
+        pid = _safe_string(claims.get("project_id"))
+        env = _safe_string(claims.get("env")) or "production"
+        if not pid:
+            raise RuntimeError(
+                "dominus.artifacts legacy methods require project_id on the service JWT",
+            )
+        return pid, env
+
     async def _api(
         self,
         endpoint: str,
@@ -293,19 +312,27 @@ class ArtifactsNamespace:
         category: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
-        List artifacts for the current project/environment.
+        List artifact heads (V2 / legacy kind) for the service JWT project.
 
-        Args:
-            limit: Max items to return (default 100, max 500)
-            category: Optional category filter
-
-        Returns:
-            {artifacts: [...], count: int, total_size_bytes: int}
+        Category filtering is client-side when rows include ``category``.
         """
-        body: Dict[str, Any] = {"limit": limit}
+        project_id, environment = await self._legacy_project_context()
+        lim = max(1, min(int(limit or 100), 500))
+        raw = await self.list_v2(
+            lim,
+            group="dominus",
+            owner=f"project:{project_id}",
+            environment=environment,
+            kind="legacy",
+        )
+        artifacts = list(raw.get("artifacts") or [])
         if category:
-            body["category"] = category
-        return await self._api("/api/artifact/list", body=body)
+            artifacts = [a for a in artifacts if (a or {}).get("category") == category]
+        count = raw.get("count", len(artifacts))
+        total = raw.get("total_size_bytes")
+        if total is None:
+            total = sum(int((a or {}).get("size_bytes") or 0) for a in artifacts)
+        return {"artifacts": artifacts, "count": count, "total_size_bytes": total}
 
     async def get_health(self) -> Dict[str, Any]:
         """Check artifact worker health."""
@@ -320,52 +347,56 @@ class ArtifactsNamespace:
         content_type: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
-        Store an artifact.
-
-        Args:
-            data: Base64-encoded data
-            key: Optional caller-provided key (UUID generated if not provided)
-            ttl_seconds: Time-to-live in seconds (default 3600)
-            category: Optional category for organization
-
-        Returns:
-            {key, ref, storage_type, size_bytes, expires_at}
+        Legacy-shaped store mapped to V2 (dominus / project:{id} / legacy / encoded key).
         """
-        body: Dict[str, Any] = {
-            "data": data,
-            "ttl_seconds": ttl_seconds,
+        import uuid
+
+        project_id, environment = await self._legacy_project_context()
+        use_key = key or str(uuid.uuid4())
+        v2 = await self.store_v2(
+            group="dominus",
+            owner=f"project:{project_id}",
+            environment=environment,
+            kind="legacy",
+            artifact_key=quote(use_key, safe=""),
+            data=data,
+            ttl_seconds=ttl_seconds,
+            category=category,
+            content_type=content_type,
+        )
+        disp = build_display_artifact_ref(use_key)
+        return {
+            "key": use_key,
+            "ref": v2.get("compatibility_ref") or v2.get("head_ref") or disp,
+            "storage_type": v2.get("storage_type") or "redis",
+            "size_bytes": v2.get("size_bytes", 0),
+            "expires_at": v2.get("expires_at") or "",
         }
-        if key:
-            body["key"] = key
-        if category:
-            body["category"] = category
-        if content_type:
-            body["content_type"] = content_type
-        return await self._api("/api/artifact/store", body=body)
 
     async def retrieve(self, key: str) -> Dict[str, Any]:
         """
-        Retrieve an artifact by key.
-
-        Args:
-            key: Artifact key
-
-        Returns:
-            {key, data, storage_type, size_bytes, expires_at}
+        Retrieve by key via V2 display ref + target_project_id (compat with legacy data).
         """
-        return await self._api("/api/artifact/retrieve", body={"key": key})
+        project_id, _environment = await self._legacy_project_context()
+        return await self._api(
+            "/api/artifact/v2/retrieve",
+            body={
+                "ref": f"{DISPLAY_REF_PREFIX}{key}",
+                "target_project_id": project_id,
+            },
+        )
 
     async def delete(self, key: str) -> Dict[str, Any]:
-        """
-        Delete an artifact by key.
-
-        Args:
-            key: Artifact key
-
-        Returns:
-            {deleted: bool, key: str}
-        """
-        return await self._api("/api/artifact/delete", body={"key": key})
+        """Delete legacy compatibility head via V2 selector."""
+        project_id, environment = await self._legacy_project_context()
+        await self.delete_v2(
+            group="dominus",
+            owner=f"project:{project_id}",
+            environment=environment,
+            kind="legacy",
+            artifact_key=quote(key, safe=""),
+        )
+        return {"deleted": True, "key": key}
 
     async def cleanup(
         self,
@@ -373,19 +404,12 @@ class ArtifactsNamespace:
         limit: int = 100,
     ) -> Dict[str, Any]:
         """
-        Cleanup expired artifacts (admin only).
-
-        Args:
-            force: Skip throttle check
-            limit: Max items to clean (default 100)
+        HTTP /cleanup is not exposed on the worker; opportunistic cleanup runs after v2 store.
 
-        Returns:
-            {cleaned: int, skipped: bool}
+        Returns a skipped sentinel for API compatibility.
         """
-        body: Dict[str, Any] = {"limit": limit}
-        if force:
-            body["force"] = True
-        return await self._api("/api/artifact/cleanup", body=body)
+        del force, limit
+        return {"cleaned": 0, "skipped": True}
 
     def _selector_body(self, options: Dict[str, Any]) -> Dict[str, Any]:
         body: Dict[str, Any] = {}

{dominus_sdk_python-2.17.0 → dominus_sdk_python-2.18.1}/dominus/namespaces/logs.py

@@ -11,6 +11,7 @@ import sys
 import time
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Optional, Tuple, TYPE_CHECKING
+from urllib.parse import urlencode
 
 if TYPE_CHECKING:
     from ..start import Dominus
@@ -321,6 +322,13 @@ class LogsNamespace:
         minutes: int = 10,
         limit: int = 100,
         trace_id: Optional[str] = None,
+        since: Optional[str] = None,
+        company: Optional[str] = None,
+        subject: Optional[str] = None,
+        run_id: Optional[str] = None,
+        deploy_id: Optional[str] = None,
+        installation_id: Optional[str] = None,
+        artifact_ref: Optional[str] = None,
     ) -> List[Dict[str, Any]]:
         """Tail recent logs from the Logs Worker.
 
@@ -330,18 +338,39 @@ class LogsNamespace:
             minutes: Time window — 1, 10, or 60 (default: 10)
             limit: Maximum results, 1-1000 (default: 100)
             trace_id: Optional trace_id filter to return only events from a specific trace
+            since: Optional ISO timestamp lower bound
+            company: Optional canonical company slug filter
+            subject: Optional domain subject filter
+            run_id: Optional workflow or Authority run id filter
+            deploy_id: Optional deploy authority id filter
+            installation_id: Optional managed-client installation id filter
+            artifact_ref: Optional artifact ref filter
 
         Returns:
             List of log event dicts
         """
-        params = []
+        params: Dict[str, Any] = {}
         if minutes != 10:
-            params.append(f"minutes={minutes}")
+            params["minutes"] = minutes
         if limit != 100:
-            params.append(f"limit={limit}")
+            params["limit"] = limit
         if trace_id:
-            params.append(f"trace_id={trace_id}")
-        qs = "&".join(params)
+            params["trace_id"] = trace_id
+        if since:
+            params["since"] = since
+        if company:
+            params["company"] = company
+        if subject:
+            params["subject"] = subject
+        if run_id:
+            params["run_id"] = run_id
+        if deploy_id:
+            params["deploy_id"] = deploy_id
+        if installation_id:
+            params["installation_id"] = installation_id
+        if artifact_ref:
+            params["artifact_ref"] = artifact_ref
+        qs = urlencode(params)
         endpoint = f"/api/logs/tail?{qs}" if qs else "/api/logs/tail"
 
         try:
@@ -372,7 +401,7 @@ class LogsNamespace:
         Returns:
             List of log event dicts
         """
-        return await self.tail(minutes=minutes, limit=limit)
+        return await self.tail(minutes=minutes, limit=limit, **kwargs)
 
     async def batch(
         self,