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-10-16-1300-sdk-python/00-reading-order.md; the latest
cleanup audit is docs/janitor/2026-10-16-1300-sdk-python-cleanup-audit.md.
Knowledge graph: graphify-out/GRAPH_REPORT.md — query with graphify-run query "<question>" before grepping.
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.16
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. SetDOMINUS_GATEWAY_URL(orDOMINUS_BASE_URL/DOMINUS_JWT_URL) only for local or custom routing. DOMINUS_TOKENis exchanged for a JWT throughPOST /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,upsertlist_tables,query_table,insert_row,update_rows,delete_rowsadd_table,add_column,delete_table,delete_columnawait 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
Metadata
Release files for dominus-sdk-python 9.0.16
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dominus_sdk_python-9.0.16.tar.gz | 155.8 kB | Without provenance | Details for dominus_sdk_python-9.0.16.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dominus_sdk_python-9.0.16-py3-none-any.whl | Python 3 | none | any | Details for dominus_sdk_python-9.0.16-py3-none-any.whl |
Total release size: 291.5 kB
Release files / dominus_sdk_python-9.0.16.tar.gz
| Download URL | dominus_sdk_python-9.0.16.tar.gz |
|---|---|
| Size | 155.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3cca91cd6d07ef8e8a48d6c9dd659826c40d0c0efb762dbfda7d3dd708b7c1f0
|
|
BLAKE2b-256 checksum How to use checksums |
d775b9ed87e06fad8c060cb9571dca7dccafccb0a095809f2edcd911f96f4306
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Release files / dominus_sdk_python-9.0.16-py3-none-any.whl
| Download URL | dominus_sdk_python-9.0.16-py3-none-any.whl |
|---|---|
| Size | 135.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9eaa59b987f6a197c6a3d304b480af376ffdfc1a161281a4a35f0555d4cb961
|
|
BLAKE2b-256 checksum How to use checksums |
48b9a65de042cbf9849eea83cae8838701c10f1c66df58c34dfac2420677d16f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.17
|
Security for dominus-sdk-python 9.0.16
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.