dominus-sdk-python 3.0.0__tar.gz → 3.0.2__tar.gz

dominus_sdk_python-3.0.2/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: dominus-sdk-python
+Version: 3.0.2
+Summary: Python SDK for the Dominus gateway-first platform
+Author-email: CareBridge Systems <dev@carebridge.io>
+License: Proprietary
+Project-URL: Homepage, https://github.com/carebridgesystems/dominus-sdk-python
+Project-URL: Repository, https://github.com/carebridgesystems/dominus-sdk-python
+Keywords: dominus,carebridge,sdk,gateway,api,async
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: bcrypt>=4.0.0
+Requires-Dist: cryptography>=41.0.0
+Provides-Extra: jwt
+Requires-Dist: PyJWT>=2.8.0; extra == "jwt"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: PyJWT>=2.8.0; extra == "all"
+
+# Dominus SDK for Python
+
+Async Python SDK for the Dominus gateway-first service plane.
+
+## What This Repo Ships
+
+- Python 3.9+ asyncio client for Dominus services
+- Namespace-first API with a small root shortcut surface
+- Gateway-scoped client mode for MCP and other user-JWT sessions
+- Local helpers for JWT verification, trace propagation, retries, and console capture
+- Current package version: `3.0.2`
+
+## Install
+
+```bash
+pip install dominus-sdk-python
+pip install dominus-sdk-python[jwt]
+pip install dominus-sdk-python[dev]
+```
+
+## Quick Start
+
+```python
+import os
+from dominus import dominus
+
+os.environ["DOMINUS_TOKEN"] = "your-psk-token"
+
+value = await dominus.secrets.get("DB_URL")
+users = await dominus.db.query("users", filters={"status": "active"})
+await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
+
+run = await dominus.workflow.ensure(
+    "wf://carebridge/report-cycle",
+    subject="PCM47474562",
+    company="summit-radiology",
+)
+
+timeline = await dominus.workflow.get_run_timeline(run["run_id"])
+```
+
+## Session-Scoped Clients
+
+Production MCP and other user-session callers should instantiate `Dominus` with
+gateway scope context instead of relying on the service-token flow:
+
+```python
+from dominus import Dominus
+
+client = Dominus(
+    gateway_user_token=user_jwt,
+    gateway_org_id=org_id,
+    gateway_app_slug=app_slug,
+    gateway_env=env,
+)
+
+me = await client.portal.me(user_token=user_jwt)
+```
+
+When these fields are set, `_request(..., use_gateway=True)` forwards the user
+JWT and selected scope headers directly through Gateway.
+
+## Transport Model
+
+- `DOMINUS_TOKEN` is exchanged for a JWT through `POST /jwt/mint`
+- Service JWTs are cached for 14 minutes with a 60-second refresh window
+- Auth-required worker routes still send base64-encoded JSON bodies as `text/plain`
+- Responses may arrive as legacy base64 JSON or raw JSON; the SDK accepts both
+- Gateway-routed namespaces translate `/api/*` to `/svc/*`
+- SSE and binary helpers bypass JSON decoding where appropriate
+
+## Namespace Inventory
+
+| Namespace | Backing surface | Purpose |
+|-----------|-----------------|---------|
+| `secrets` | Warden | Secrets CRUD |
+| `db` | DB Worker | Database CRUD and metadata |
+| `secure` | DB Worker | Audit-logged data access |
+| `redis` | Redis Worker | Cache, hashes, TTL, counters |
+| `files` | B2 / storage surfaces | File upload, fetch, listing, folders |
+| `auth` | Guardian + JWT routes | RBAC, tenants, pages, secure tables, JWKS |
+| `ddl` | Smith / DDL worker | Schema, migrations, provisioning |
+| `logs` | Logs Worker | Structured logs and tail/query helpers |
+| `portal` | Portal Worker | Login, sessions, profile, preferences, nav |
+| `courier` | Courier Worker | Template email delivery |
+| `health` | Gateway | Health and ping helpers |
+| `admin` | Admin Worker | Admin category reseed/reset |
+| `ai` | Agent Runtime | Agent, completion, RAG, artifacts, results, raw orchestration |
+| `workflow` | Workflow Manager + Authority | Saved workflow CRUD and canonical run lifecycle |
+| `artifacts` | Artifact Worker | Addressed V2 artifacts, bookmarks, watches |
+| `jobs` | Job Worker | Enqueue, poll, dead-letter management |
+| `processor` | Processor | Batch and single-job processing |
+| `sync` | Sync Worker | KV synchronization |
+| `authority` | Dominus Authority | Runs, companies, deploys, managed clients, context |
+| `fastapi` | Local decorators | `@jwt`, `@psk`, `@scopes(...)` |
+
+## Root Shortcuts
+
+The root `Dominus` object still exposes a small compatibility surface for common
+operations:
+
+- `get`, `upsert`
+- `list_tables`, `query_table`, `insert_row`, `update_rows`, `delete_rows`
+- `add_table`, `add_column`, `delete_table`, `delete_column`
+- `await dominus("secrets.get", key="DB_URL")`
+
+New code should prefer namespace APIs.
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - request flow, gateway routing, resilience
+- [Services Reference](docs/services.md) - namespace inventory and endpoint mapping
+- [Development](docs/development.md) - setup, testing, publishing, extension patterns
+
+## Verification
+
+```bash
+pip install -e .[dev]
+python -m pytest tests -q
+python -m build
+```
+
+## License
+
+Proprietary - CareBridge Systems

dominus_sdk_python-3.0.2/README.md

@@ -0,0 +1,125 @@
+# Dominus SDK for Python
+
+Async Python SDK for the Dominus gateway-first service plane.
+
+## What This Repo Ships
+
+- Python 3.9+ asyncio client for Dominus services
+- Namespace-first API with a small root shortcut surface
+- Gateway-scoped client mode for MCP and other user-JWT sessions
+- Local helpers for JWT verification, trace propagation, retries, and console capture
+- Current package version: `3.0.2`
+
+## Install
+
+```bash
+pip install dominus-sdk-python
+pip install dominus-sdk-python[jwt]
+pip install dominus-sdk-python[dev]
+```
+
+## Quick Start
+
+```python
+import os
+from dominus import dominus
+
+os.environ["DOMINUS_TOKEN"] = "your-psk-token"
+
+value = await dominus.secrets.get("DB_URL")
+users = await dominus.db.query("users", filters={"status": "active"})
+await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
+
+run = await dominus.workflow.ensure(
+    "wf://carebridge/report-cycle",
+    subject="PCM47474562",
+    company="summit-radiology",
+)
+
+timeline = await dominus.workflow.get_run_timeline(run["run_id"])
+```
+
+## Session-Scoped Clients
+
+Production MCP and other user-session callers should instantiate `Dominus` with
+gateway scope context instead of relying on the service-token flow:
+
+```python
+from dominus import Dominus
+
+client = Dominus(
+    gateway_user_token=user_jwt,
+    gateway_org_id=org_id,
+    gateway_app_slug=app_slug,
+    gateway_env=env,
+)
+
+me = await client.portal.me(user_token=user_jwt)
+```
+
+When these fields are set, `_request(..., use_gateway=True)` forwards the user
+JWT and selected scope headers directly through Gateway.
+
+## Transport Model
+
+- `DOMINUS_TOKEN` is exchanged for a JWT through `POST /jwt/mint`
+- Service JWTs are cached for 14 minutes with a 60-second refresh window
+- Auth-required worker routes still send base64-encoded JSON bodies as `text/plain`
+- Responses may arrive as legacy base64 JSON or raw JSON; the SDK accepts both
+- Gateway-routed namespaces translate `/api/*` to `/svc/*`
+- SSE and binary helpers bypass JSON decoding where appropriate
+
+## Namespace Inventory
+
+| Namespace | Backing surface | Purpose |
+|-----------|-----------------|---------|
+| `secrets` | Warden | Secrets CRUD |
+| `db` | DB Worker | Database CRUD and metadata |
+| `secure` | DB Worker | Audit-logged data access |
+| `redis` | Redis Worker | Cache, hashes, TTL, counters |
+| `files` | B2 / storage surfaces | File upload, fetch, listing, folders |
+| `auth` | Guardian + JWT routes | RBAC, tenants, pages, secure tables, JWKS |
+| `ddl` | Smith / DDL worker | Schema, migrations, provisioning |
+| `logs` | Logs Worker | Structured logs and tail/query helpers |
+| `portal` | Portal Worker | Login, sessions, profile, preferences, nav |
+| `courier` | Courier Worker | Template email delivery |
+| `health` | Gateway | Health and ping helpers |
+| `admin` | Admin Worker | Admin category reseed/reset |
+| `ai` | Agent Runtime | Agent, completion, RAG, artifacts, results, raw orchestration |
+| `workflow` | Workflow Manager + Authority | Saved workflow CRUD and canonical run lifecycle |
+| `artifacts` | Artifact Worker | Addressed V2 artifacts, bookmarks, watches |
+| `jobs` | Job Worker | Enqueue, poll, dead-letter management |
+| `processor` | Processor | Batch and single-job processing |
+| `sync` | Sync Worker | KV synchronization |
+| `authority` | Dominus Authority | Runs, companies, deploys, managed clients, context |
+| `fastapi` | Local decorators | `@jwt`, `@psk`, `@scopes(...)` |
+
+## Root Shortcuts
+
+The root `Dominus` object still exposes a small compatibility surface for common
+operations:
+
+- `get`, `upsert`
+- `list_tables`, `query_table`, `insert_row`, `update_rows`, `delete_rows`
+- `add_table`, `add_column`, `delete_table`, `delete_column`
+- `await dominus("secrets.get", key="DB_URL")`
+
+New code should prefer namespace APIs.
+
+## Documentation
+
+- [Architecture](docs/architecture.md) - request flow, gateway routing, resilience
+- [Services Reference](docs/services.md) - namespace inventory and endpoint mapping
+- [Development](docs/development.md) - setup, testing, publishing, extension patterns
+
+## Verification
+
+```bash
+pip install -e .[dev]
+python -m pytest tests -q
+python -m build
+```
+
+## License
+
+Proprietary - CareBridge Systems

{dominus_sdk_python-3.0.0 → dominus_sdk_python-3.0.2}/dominus/__init__.py

@@ -1,13 +1,9 @@
 """
 CB Dominus SDK - Ultra-flat async SDK for CareBridge Services
 
-Ultra-Flat API:
+Namespace-first API:
     from dominus import dominus
 
-    # Secrets (root level shortcuts)
-    value = await dominus.get("DB_URL")
-    await dominus.upsert("KEY", "value")
-
     # Secrets namespace
     value = await dominus.secrets.get("DB_URL")
     await dominus.secrets.upsert("KEY", "value")
@@ -38,7 +34,7 @@ Ultra-Flat API:
     await dominus.courier.send("welcome", to="user@example.com", from_email="hello@app.com", model={})
 
     # Secure table access with audit logging
-    rows = await dominus.db_secure.query("patients", context=SecureAccessContext(
+    rows = await dominus.secure.query("patients", context=SecureAccessContext(
         reason="Reviewing chart",
         actor=user_id
     ))
@@ -49,23 +45,16 @@ Ultra-Flat API:
     # Portal authentication
     session = await dominus.portal.login("user@example.com", "password", "tenant-id")
 
-    # Open DSN and raw SQL
-    dsn = await dominus.open.dsn()
-    result = await dominus.open.execute("SELECT * FROM users WHERE id = $1", {"1": user_id})
-
     # Health
     status = await dominus.health.check()
-    await dominus.health.ping()
-    await dominus.health.warmup()
 
-Backward Compatible APIs:
-    # String-based API
-    result = await dominus("secrets.get", key="DB_URL")
+Flat shortcuts remain for common gateway-backed secrets and DB operations:
+    value = await dominus.get("DB_URL")
+    await dominus.upsert("KEY", "value")
 
-    # Flat API (root level shortcuts for common operations)
-    await dominus.list_tables()
-    await dominus.query_table("users")
-    await dominus.insert_row("users", {"name": "John"})
+Supported string commands:
+    result = await dominus("secrets.get", key="DB_URL")
+    await dominus("sql.app.list_tables", schema="public")
 
 Crypto Helpers:
     from dominus import hash_password, hash_psk, generate_token
@@ -98,8 +87,6 @@ from .namespaces.redis import RedisNamespace
 from .namespaces.logs import LogsNamespace
 from .namespaces.courier import CourierNamespace
 from .namespaces.health import HealthNamespace
-from .namespaces.open import OpenNamespace
-
 # Export new namespaces (Node.js SDK parity)
 from .namespaces.artifacts import (
     ARTIFACT_REF_PREFIX,
@@ -123,14 +110,7 @@ from .namespaces.artifacts import (
 from .namespaces.jobs import JobsNamespace
 from .namespaces.processor import ProcessorNamespace
 from .namespaces.sync import SyncNamespace
-
-# Export Oracle namespace for speech-to-text
-from .namespaces.oracle import (
-    OracleNamespace,
-    OracleSession,
-    OracleSessionOptions,
-    VADState,
-)
+from .namespaces.authority import AuthorityNamespace
 
 # Export AI namespace for agent-runtime operations
 from .namespaces.ai import (
@@ -146,7 +126,7 @@ from .helpers.cache import (
     dominus_cache,
     CircuitBreaker,
     DominusCache,
-    orchestrator_circuit_breaker,
+    gateway_circuit_breaker,
     exponential_backoff_with_jitter,
 )
 
@@ -154,7 +134,7 @@ from .helpers.cache import (
 from .helpers.core import (
     verify_jwt_locally,
     is_jwt_valid,
-    mint_selected_project_jwt,
+    mint_selected_scope_jwt,
 )
 
 # Export trace utilities for distributed tracing
@@ -181,7 +161,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -209,7 +189,6 @@ __all__ = [
     "LogsNamespace",
     "CourierNamespace",
     "HealthNamespace",
-    "OpenNamespace",
     # New namespaces (Node.js SDK parity)
     "ARTIFACT_REF_PREFIX",
     "DISPLAY_REF_PREFIX",
@@ -231,11 +210,7 @@ __all__ = [
     "JobsNamespace",
     "ProcessorNamespace",
     "SyncNamespace",
-    # Oracle namespace for speech-to-text
-    "OracleNamespace",
-    "OracleSession",
-    "OracleSessionOptions",
-    "VADState",
+    "AuthorityNamespace",
     # AI namespace for agent-runtime operations
     "AiNamespace",
     "RagSubNamespace",
@@ -246,12 +221,12 @@ __all__ = [
     "dominus_cache",
     "CircuitBreaker",
     "DominusCache",
-    "orchestrator_circuit_breaker",
+    "gateway_circuit_breaker",
     "exponential_backoff_with_jitter",
     # JWT verification utilities
     "verify_jwt_locally",
     "is_jwt_valid",
-    "mint_selected_project_jwt",
+    "mint_selected_scope_jwt",
     # Trace utilities
     "generate_trace_id",
     "get_current_trace_id",

{dominus_sdk_python-3.0.0 → dominus_sdk_python-3.0.2}/dominus/config/endpoints.py

@@ -1,16 +1,16 @@
 """
 Dominus SDK Endpoints
 
-Gateway URL for service routing.
+Gateway URL for service routing and health checks.
 JWT URL for authentication (JWT minting).
 Logs URL for log ingestion.
-Orchestrator URL for service calls (legacy).
+Base URL for SDK requests (defaults to gateway).
 
 Configuration:
     Set DOMINUS_GATEWAY_URL to override the gateway URL.
     Set DOMINUS_JWT_URL to override the JWT minting URL.
     Set DOMINUS_LOGS_URL to override the logs URL.
-    Set DOMINUS_BASE_URL to override the orchestrator URL.
+    Set DOMINUS_BASE_URL to override the SDK request base URL.
     Example: export DOMINUS_BASE_URL=http://localhost:5000
 
 Usage:
@@ -22,7 +22,7 @@ import os
 _DEFAULT_GATEWAY_URL = "https://gateway.getdominus.app"
 _DEFAULT_JWT_URL = "https://jwt.getdominus.app"
 _DEFAULT_LOGS_URL = "https://logs.getdominus.app"
-_DEFAULT_BASE_URL = "https://dominus-orchestrator-production-775398158805.us-east4.run.app"
+_DEFAULT_BASE_URL = _DEFAULT_GATEWAY_URL
 
 # Gateway URL for service routing (can be overridden via DOMINUS_GATEWAY_URL)
 GATEWAY_URL = os.environ.get("DOMINUS_GATEWAY_URL", _DEFAULT_GATEWAY_URL)
@@ -33,11 +33,11 @@ JWT_URL = os.environ.get("DOMINUS_JWT_URL", _DEFAULT_JWT_URL)
 # Logs URL for log ingestion (can be overridden via DOMINUS_LOGS_URL)
 LOGS_URL = os.environ.get("DOMINUS_LOGS_URL", _DEFAULT_LOGS_URL)
 
-# Base URL for service calls (can be overridden via DOMINUS_BASE_URL environment variable)
+# Base URL for SDK requests (can be overridden via DOMINUS_BASE_URL environment variable)
 BASE_URL = os.environ.get("DOMINUS_BASE_URL", _DEFAULT_BASE_URL)
 
-# Legacy aliases (all point to orchestrator now) - DEPRECATED
-SOVEREIGN_URL = BASE_URL  # Deprecated: use BASE_URL or get_gateway_url()
+# Legacy aliases retained as gateway-first aliases.
+SOVEREIGN_URL = BASE_URL
 ARCHITECT_URL = BASE_URL
 ORCHESTRATOR_URL = BASE_URL
 WARDEN_URL = BASE_URL
@@ -97,17 +97,17 @@ def get_logs_url() -> str:
 
 def get_base_url() -> str:
     """
-    Get the dominus-orchestrator base URL for service calls.
+    Get the SDK request base URL.
 
     Returns the value of DOMINUS_BASE_URL environment variable if set,
-    otherwise returns the default production URL.
+    otherwise returns the default gateway URL.
     """
     return os.environ.get("DOMINUS_BASE_URL", _DEFAULT_BASE_URL)
 
 
 # DEPRECATED - use get_base_url()
 def get_sovereign_url(environment: str = None) -> str:
-    """Deprecated: Use get_base_url() instead. 'Sovereign' is the legacy name for the gateway."""
+    """Deprecated: Use get_base_url() instead."""
     return BASE_URL
 
 

{dominus_sdk_python-3.0.0 → dominus_sdk_python-3.0.2}/dominus/errors.py

@@ -6,6 +6,59 @@ Custom exceptions for the Dominus SDK with structured error information.
 from typing import Any, Dict, Optional
 
 
+def _first_string(*values: Any) -> Optional[str]:
+    for value in values:
+        if isinstance(value, str) and value.strip():
+            return value
+    return None
+
+
+def _first_bool(*values: Any) -> Optional[bool]:
+    for value in values:
+        if isinstance(value, bool):
+            return value
+    return None
+
+
+def _default_category_for_status(status_code: Optional[int]) -> Optional[str]:
+    if status_code in {400, 422}:
+        return "validation"
+    if status_code == 401:
+        return "auth"
+    if status_code == 403:
+        return "forbidden"
+    if status_code == 404:
+        return "not_found"
+    if status_code == 409:
+        return "conflict"
+    if status_code and status_code >= 500:
+        return "upstream"
+    return None
+
+
+def _normalize_kernel_details(
+    status_code: Optional[int],
+    details: Optional[Dict[str, Any]],
+) -> Dict[str, Any]:
+    normalized = dict(details or {})
+    category = _first_string(normalized.get("category")) or _default_category_for_status(status_code)
+    if category:
+        normalized["category"] = category
+    code = _first_string(normalized.get("code")) or (f"http.{status_code}" if status_code else None)
+    if code:
+        normalized["code"] = code
+    trace_id = _first_string(normalized.get("trace_id"), normalized.get("traceId"))
+    if trace_id:
+        normalized["trace_id"] = trace_id
+    request_id = _first_string(normalized.get("request_id"), normalized.get("requestId"))
+    if request_id:
+        normalized["request_id"] = request_id
+    retryable = _first_bool(normalized.get("retryable"))
+    if retryable is not None:
+        normalized["retryable"] = retryable
+    return normalized
+
+
 class DominusError(Exception):
     """
     Base exception for all Dominus SDK errors.
@@ -16,6 +69,8 @@ class DominusError(Exception):
     Attributes:
         message: Human-readable error message
         status_code: HTTP status code (if applicable)
+        code: Stable machine-readable error code
+        category: Error category from the kernel contract
         details: Additional error details from backend
         endpoint: The endpoint that was called (if applicable)
     """
@@ -29,12 +84,19 @@ class DominusError(Exception):
     ):
         self.message = message
         self.status_code = status_code
-        self.details = details or {}
+        self.details = _normalize_kernel_details(status_code, details)
         self.endpoint = endpoint
+        self.code = _first_string(self.details.get("code"))
+        self.category = _first_string(self.details.get("category"))
+        self.trace_id = _first_string(self.details.get("trace_id"), self.details.get("traceId"))
+        self.request_id = _first_string(self.details.get("request_id"), self.details.get("requestId"))
+        self.retryable = _first_bool(self.details.get("retryable"))
         super().__init__(self.message)
 
     def __str__(self) -> str:
         parts = [self.message]
+        if self.code:
+            parts.append(f"[{self.code}]")
         if self.status_code:
             parts.append(f"(status {self.status_code})")
         if self.endpoint:
@@ -45,10 +107,25 @@ class DominusError(Exception):
         return (
             f"DominusError(message={self.message!r}, "
             f"status_code={self.status_code}, "
+            f"code={self.code!r}, "
+            f"category={self.category!r}, "
             f"details={self.details!r}, "
             f"endpoint={self.endpoint!r})"
         )
 
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "message": self.message,
+            "status_code": self.status_code,
+            "code": self.code,
+            "category": self.category,
+            "details": self.details,
+            "endpoint": self.endpoint,
+            "trace_id": self.trace_id,
+            "request_id": self.request_id,
+            "retryable": self.retryable,
+        }
+
 
 class AuthenticationError(DominusError):
     """Raised when authentication fails (invalid token, expired JWT, etc.)."""

{dominus_sdk_python-3.0.0 → dominus_sdk_python-3.0.2}/dominus/helpers/cache.py

@@ -5,7 +5,7 @@ Exports:
     - CircuitBreaker: Circuit breaker class for resilience
     - DominusCache: Encrypted cache class
     - dominus_cache: Singleton cache instance
-    - orchestrator_circuit_breaker: Circuit breaker for orchestrator
+    - gateway_circuit_breaker: Circuit breaker used by gateway JWT minting
     - exponential_backoff_with_jitter: Backoff calculation utility
 """
 import time
@@ -189,12 +189,9 @@ class DominusCache:
 # Singleton instances
 dominus_cache = DominusCache(default_ttl=300)
 
-# Circuit breaker for orchestrator (prevents retry storms)
-orchestrator_circuit_breaker = CircuitBreaker(
+# Circuit breaker for gateway JWT minting (prevents retry storms)
+gateway_circuit_breaker = CircuitBreaker(
     failure_threshold=5,    # Open after 5 consecutive failures
     recovery_timeout=30.0,  # Try again after 30 seconds
     half_open_max_calls=1   # Allow 1 test call in half-open state
 )
-
-# Backward compatibility alias
-gateway_circuit_breaker = orchestrator_circuit_breaker