dominus-sdk-python 3.0.0

Python SDK for the Dominus Orchestrator Platform

Dominus SDK for Python

Async Python SDK for CareBridge Dominus platform services. Routes calls through the Dominus Gateway with JWT-based authentication, base64 wire encoding, retries, and circuit breaking.

What This Is

• 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: 3.0.0

Quick Start

import os
from dominus import dominus

os.environ["DOMINUS_TOKEN"] = "your-psk-token"

# Secrets
value = await dominus.secrets.get("DB_URL")
await dominus.secrets.upsert("API_KEY", "secret_value")

# Database CRUD
users = await dominus.db.query("users", filters={"status": "active"})
await dominus.db.insert("users", {"name": "John", "email": "[e-mail]"})

# Redis caching
await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
value = await dominus.redis.get("session:123")

# File storage
result = await dominus.files.upload(data=buf, filename="report.pdf", category="reports")

# AI agent execution
result = await dominus.ai.run_agent(
    conversation_id="conv-123",
    system_prompt="You are helpful.",
    user_prompt="Hello!"
)

# Streaming AI
async for chunk in dominus.ai.stream_agent(
    conversation_id="conv-123",
    system_prompt="You are helpful.",
    user_prompt="Tell me a story"
):
    print(chunk.get("content", ""), end="", flush=True)

# 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"}},
)
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)

DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
                                |
                                v
                    Gateway /svc/* (AI, workflow, logs)
                         or
                    Orchestrator /api/* (all other services)

• JSON requests/responses are base64-encoded for auth-required routes
• GET requests send no body; parameters go in the path or query string
• Gateway routing (/api/* -> /svc/*) is used by AI, workflow, and logs namespaces
• Orchestrator handles secrets, db, auth, ddl, files, redis, portal, courier, open, health, admin

Namespaces

Namespace	Service	Description
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	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
logs	Logs Worker	Structured logging with callsite capture
portal	Portal	Login, sessions, profile, preferences, navigation, registration
courier	Courier	Postmark email delivery
open	Scribe Open	Raw SQL / DSN retrieval
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, 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)

Configuration

Required:

• DOMINUS_TOKEN -- PSK token for gateway authentication

Optional:

• DOMINUS_GATEWAY_URL -- Override gateway URL (default: https://gateway.getdominus.app)
• DOMINUS_JWT_URL -- Override JWT worker URL (default: https://jwt.getdominus.app)
• DOMINUS_LOGS_URL -- Override logs worker URL (default: https://logs.getdominus.app)
• DOMINUS_BASE_URL -- Override orchestrator URL (default: production Cloud Run)
• DOMINUS_HTTP_PROXY / DOMINUS_HTTPS_PROXY -- httpx proxy configuration
• DOMINUS_CAPTURE_CONSOLE -- Set to "true" to auto-forward print() and logging.* to Logs Worker

Installation

pip install dominus-sdk-python

# With optional extras
pip install dominus-sdk-python[jwt]      # Local JWT verification
pip install dominus-sdk-python[oracle]   # WebSocket STT (websockets, numpy, sounddevice, webrtcvad)
pip install dominus-sdk-python[all]      # Everything

Console Capture

Forward print() and logging.* to the Dominus Logs Worker:

# Automatic (via env var, before importing SDK):
os.environ["DOMINUS_CAPTURE_CONSOLE"] = "true"

# Manual:
dominus.capture_console()     # start capturing
dominus.release_console()     # stop capturing

Documentation

• Architecture -- Request flow, resilience, JWT verification
• Services Reference -- Complete namespace and method inventory
• Development -- Setup, testing, adding APIs
• Workflow hard-cut release notes -- cutover notes and operational checks

Verification (local)

pip install -e .
python -m pytest tests -q

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

Proprietary - CareBridge Systems