Skip to main content

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 shared dominus-service-core codec
  • 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. 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

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, 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

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)

Source distribution for dominus-sdk-python 9.1.1
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)

Table of built distributions (wheels) for dominus-sdk-python 9.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

9.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page