dominus-sdk-python 7.1.1

Python SDK for the Dominus gateway-first platform

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-06-27-0849-agent-guide/00-reading-order.md; the latest cleanup audit is docs/janitor/2026-06-27-0849-agent-guide-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: 7.1.0

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