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-26-1300-sdk-python/00-reading-order.md; the latest
cleanup audit is docs/janitor/2026-10-26-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
- Exact-target (
target.v1) transport on every request path, using the shareddominus-service-corecodec - Current package version:
9.1.0
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
Exact Target Transport
Passing a target.v1 identity makes a project-scoped call carry one atomic
pair: an exchanged exact ticket plus its byte-identical X-Dominus-Target
header (base64url(JCS(target.v1))). Ordinary requests, gateway_fetch,
streaming, upload, and download/binary all pair the same way, and the ticket
cache is keyed by the full target_fingerprint.v1 plus the credential context,
so changing any target field gets a new entry.
from dominus import Dominus, selected_scope_target
target = selected_scope_target("11111111-1111-4111-8111-111111111111", "production")
client = Dominus(exact_target=target) # default for every call
record = await client.mint_exact_target_ticket(target)
print(record.target_fingerprint, record.target_header)
await client.gateway_fetch("/svc/authority/runs") # carries the atomic pair
await client.gateway_fetch("/svc/authority/runs", exact_target=other_target)
The codec is the shared dominus-service-core target/hash contract; the SDK
does not fork it. That package stays off public indexes by decision, so it is
not a wheel dependency. Install it from its documented immutable git-tag lane
and the exact-target surface imports it lazily:
pip install "dominus-service-core @ git+https://github.com/carebridgesystems/dominus-service-core.git@service-core-v2.3.4"
Without it, base installs stay targetless and using the exact-target surface
raises ExactTargetDependencyError naming the lane. Legacy
gateway_org_id/gateway_env context adapts through
selected_scope_target(org_id, env); slugs and physical shared ids are refused,
and a returned target, fingerprint, selected claim, or ticket claim that
disagrees with the request fails before any Gateway call.
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.1.1
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.1.1.tar.gz | 173.6 kB | Without provenance | Details for dominus_sdk_python-9.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dominus_sdk_python-9.1.1-py3-none-any.whl | Python 3 | none | any | Details for dominus_sdk_python-9.1.1-py3-none-any.whl |
Total release size: 317.8 kB
Release files / dominus_sdk_python-9.1.1.tar.gz
| Download URL | dominus_sdk_python-9.1.1.tar.gz |
|---|---|
| Size | 173.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a576078d4c3ed62bf3007fcf0037239ba142660dda3aa2c696b6252e6c00668e
|
|
BLAKE2b-256 checksum How to use checksums |
8c5f3289af80c127a9765c2bbddabd1c68c5453e8bb06d3c40e15d01ee7311b6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / dominus_sdk_python-9.1.1-py3-none-any.whl
| Download URL | dominus_sdk_python-9.1.1-py3-none-any.whl |
|---|---|
| Size | 144.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
440567dfd9a56f317500e32ff7a1cdcb7092151c52c31ca63ecd10ac92539336
|
|
BLAKE2b-256 checksum How to use checksums |
4f3cc7ad584be8bed8f70076bdaa4fb959182dfbce128ff9fe15419ad9a1a5a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for dominus-sdk-python 9.1.1
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.