Dominus SDK for Python

Async Python SDK for the Dominus gateway-first service plane.

Agent Guide

Start with docs/agent-guide/INDEX.md. The current snapshot is docs/agent-guide/2026-08-04-sdk-python/00-reading-order.md; the latest cleanup audit is docs/janitor/2026-08-04-sdk-python-cleanup-audit.md.

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
Transport compatibility for wrapped {success,data} responses and unwrapped Warden/control-plane success objects
Local helpers for JWT verification, trace propagation, retries, and console capture
Current package version: 9.0.1

Install

pip install dominus-sdk-python
pip install dominus-sdk-python[jwt]
pip install dominus-sdk-python[dev]

Quick Start

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(
    workflow_recipe_ref="recipe://workflow-recipe-v1/report-cycle@v3",
    subject="PCM47474562",
    company="summit-radiology",
)

timeline = await dominus.authority.get_run_timeline(
    run["run_id"],
    since="2026-04-11T08:33:00Z",
    until="2026-04-11T09:33:00Z",
)

timeline_archive = await dominus.authority.get_timeline_archive_status(
    app_slug="carebridge-summit",
    env="production",
)
archive_batch = await dominus.authority.archive_timelines(
    max_hours=24,
    max_runtime_ms=600000,
)
logs_archive = await dominus.logs.get_archive_status(
    all_scopes=True,
    include_buffer=True,
    limit=5,
)
machine_logs = await dominus.logs.tail(
    machine_id="mach-abc-123",
    since="2026-04-11T08:33:00Z",
    level="error",
)
policy = await dominus.platform.ensure_policy_decision(
    {
        "group": "dominus",
        "repository": "carebridgesystems/dominus-platform-worker",
    },
    actor_context={"type": "user", "id": "operator-1"},
)
coder_run = await dominus.coder.ensure_run(
    policy_decision_id=policy["data"]["policy_decision"]["decision_id"],
    workflow_recipe_ref="recipe://workflow-recipe-v1/coder-feature@head",
    repository="carebridgesystems/dominus-platform-worker",
    executor="managed_anthropic",
    instructions="Fix failing tests",
    actor_context={"type": "user", "id": "operator-1"},
)

# Archive maintenance is explicit and dry-run first.
verify = await dominus.authority.verify_timeline_archive_manifests(
    since="2026-04-01T00:00:00Z",
    until="2026-04-02T00:00:00Z",
)
prune = await dominus.logs.prune_archive_retention(
    retention_days=90,
    dry_run=True,
)
buffer_proof = await dominus.logs.dry_run_archive_buffer_maintenance(
    sample_limit=100,
)
buffer_cleanup = await dominus.logs.run_archive_buffer_maintenance(
    dry_run=False,
    confirm="DELETE_ARCHIVE_BUFFER_RESIDUE",
    salvage_missing_archive=True,
    sample_limit=500,
    max_archive_buckets=24,
    batch_runs=5,
    max_runtime_ms=8000,
)

schedules = await dominus.authority.list_schedules(all_scopes=True)

Stash Managed Tables

dominus.stash.tables provides a typed client for small, scoped JSONB tables without exposing SQL. Every call requires env, scope (self or group), and table; self and group tables resolve to independent project and shared databases.

spec = await dominus.stash.tables.define(
    env="production",
    scope="self",
    table="jobs",
    if_revision=0,
    primary_key={"field": "id", "generate": "uuid"},
    fields={
        "id": {"type": "uuid", "required": True},
        "status": {"type": "string", "required": True},
        "priority": {"type": "integer"},
    },
)

row = await dominus.stash.tables.put_row(
    env="production",
    scope="self",
    table="jobs",
    if_revision=0,
    row={"status": "queued", "priority": 5},
)

page = await dominus.stash.tables.select(
    env="production",
    scope="self",
    table="jobs",
    where={
        "or": [
            {"field": "status", "op": "eq", "value": "queued"},
            {"field": "priority", "op": "gte", "value": 5},
        ]
    },
    page_size=50,
)

Use if_revision for table definitions and single-row put/delete compare-and- swap. update_where instead requires if_spec_revision and max_affected. Cursors are opaque keyset tokens. delete_row is a hard delete and returns a durable mutation receipt; there is no soft-delete or restore lifecycle.

Browser Automation

dominus.browser exposes the first-class Dominus browser automation primitive through authenticated gateway routes under /svc/browser/*. SDK methods use /api/browser/* internally with gateway routing enabled; worker-local routes remain /health and /runs/*.

health = await dominus.browser.get_health()
run = await dominus.browser.ensure_run(
    idempotency_key="route-check-1",
    target={"url": "https://example.com/dashboard"},
    provider="auto",
    mode="playwright",
    capture_policy={
        "screenshots": "never",
        "trace": "never",
        "har": "never",
        "video": "never",
        "dom_snapshot": "never",
        "raw_response_bodies": "never",
        "phi_risk": "possible",
    },
    assertions=[{"kind": "status_code", "expected": 200}],
)
await dominus.browser.start_run(run["run_id"])
status = await dominus.browser.get_run_status(run["run_id"])

Cloudflare Browser Run is the default provider. Browserbase is the fallback for future persistent authenticated/HITL work. Browser run metadata is runtime state owned by the browser worker; Artifact V2 is only for sanitized result/capture payloads.

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:

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

Default HTTP targets are the production gateway (https://gateway.getdominus.app); they do not change based on your app’s git branch or PyPI package variant. Set DOMINUS_GATEWAY_URL (or DOMINUS_BASE_URL / DOMINUS_JWT_URL) only for local or custom routing.
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
Finite workflow/orchestration replay routes may return text/event-stream; the SDK normalizes them into event lists
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 recipe-backed 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, provisioning targets, deploys, managed clients, context
`browser`	Browser Worker	Browser run health, ensure/start/status/result/retry/nudge/cancel/timeline/dossier
`deployer`	Deployer	Thin operator control-plane request surface
`warden`	Warden	Thin operator control-plane request surface
`platform`	Platform Worker	Group/repository policy decisions with actor attribution
`coder`	Coder Runtime	Policy-bound Coder run lifecycle with workflow/pipeline recipe launch sources
`publisher`	Publisher	Release/channel/signing build and artifact operations
`stash`	Stash	Items, managed tables, kinds, bookmarks, watches, artifact facade
`recipes`	Recipe Worker	Recipe type registry, publish, validate, get/list
`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.

Guardian navigation helpers expose nav-row path on create_nav_item() and update_nav_item(). Use that field when a sidebar item must route to a concrete URL independent of, or more specific than, the linked Guardian page row.

Documentation

Architecture - request flow, gateway routing, resilience
Services Reference - namespace inventory and endpoint mapping
Development - setup, testing, publishing, extension patterns

Verification

pip install -e .[dev]
python -m pytest tests -q
python -m build

License

Proprietary - CareBridge Systems

Release files for dominus-sdk-python 9.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dominus-sdk-python 9.0.1
File	Size	Uploaded
dominus_sdk_python-9.0.1.tar.gz	136.3 kB	Aug 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dominus-sdk-python 9.0.1
File	Interpreter	ABI	Platform	Reset
dominus_sdk_python-9.0.1-py3-none-any.whl 127.3 kB Aug 4, 2026	Python 3	none	any	Details

Total release size: 263.6 kB

Release files / dominus_sdk_python-9.0.1.tar.gz

Download URL	dominus_sdk_python-9.0.1.tar.gz
Size	136.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`1805b3eb887cebeabdda1dcf6d38039bcfa2fcc240578e55ba6cc62a63507cf1`
BLAKE2b-256 checksum How to use checksums	`b9575706332e363d2f71061f1819944efb42ca9958c329e588dd65a392cbc359`
Upload date	Aug 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`

Release files / dominus_sdk_python-9.0.1-py3-none-any.whl

Download URL	dominus_sdk_python-9.0.1-py3-none-any.whl
Size	127.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`a7f9fa7d9321e706ab41b75008ee5450fecb6dab094ffee05d4bb92825036c65`
BLAKE2b-256 checksum How to use checksums	`084a68eb73fc38122cc5faea4c59aa6f12f2ef378b85a6a4fb089d61d5de56fa`
Upload date	Aug 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.15`