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-09-19-1300-sdk-python/00-reading-order.md; the latest cleanup audit is docs/janitor/2026-09-19-1300-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.13

Install

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

Quick Start

Token-required hello using only the developer-stable catalog verbs. Set project scope with DOMINUS_PROJECT or CLI select_project. Other SDK namespaces exist for operators and advanced use; this path is the stable teaching surface.

Set both values before the Python process imports the SDK singleton:

export DOMINUS_USER_TOKEN="your-user-token"
export DOMINUS_PROJECT="your-project-slug"

import asyncio

from dominus import dominus


async def main() -> None:
    run = await dominus.workflow.ensure(
        workflow_recipe_ref="recipe://workflow-recipe-v1/hello@v1",
    )

    stash_result = await dominus.stash.upsert(
        kind="config",
        scope={"env": "production"},
        value={"greeting": "hello"},
        item_key="hello",
    )
    await dominus.stash.get(stash_result["item"]["id"])

    timeline = await dominus.authority.get_run_timeline(run["run_id"])
    verdict = await dominus.authority.get_run_verdict(run["run_id"])


if __name__ == "__main__":
    asyncio.run(main())

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.13

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.13
File	Size	Uploaded
dominus_sdk_python-9.0.13.tar.gz	153.0 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for dominus-sdk-python 9.0.13
File	Interpreter	ABI	Platform	Reset
dominus_sdk_python-9.0.13-py3-none-any.whl 135.4 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 288.4 kB

Release files / dominus_sdk_python-9.0.13.tar.gz

Download URL	dominus_sdk_python-9.0.13.tar.gz
Size	153.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`a61abd263025d42ccb3fbec82665e1242b6c04d46ad4179a1032dbb26c749567`
BLAKE2b-256 checksum How to use checksums	`e18eed6b022ed71e3dd356d0ec7aaa1bd7b9f7c533d62c465a2c34f590871d6b`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`

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

Download URL	dominus_sdk_python-9.0.13-py3-none-any.whl
Size	135.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`445380951ea2735730ee87f62cd6de1d183234c300a6d7a754e81e164e9e7f5f`
BLAKE2b-256 checksum How to use checksums	`dc8add209fccfed1d71fa24945321c371513eb9488a863009474be3588a889ad`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.16`