Metadata-Version: 2.4
Name: dominus-sdk-python
Version: 3.0.4
Summary: Python SDK for the Dominus gateway-first platform
Author-email: CareBridge Systems <dev@carebridge.io>
License: Proprietary
Project-URL: Homepage, https://github.com/carebridgesystems/dominus-sdk-python
Project-URL: Repository, https://github.com/carebridgesystems/dominus-sdk-python
Keywords: dominus,carebridge,sdk,gateway,api,async
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: jwt
Requires-Dist: PyJWT>=2.8.0; extra == "jwt"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Provides-Extra: all
Requires-Dist: PyJWT>=2.8.0; extra == "all"

# Dominus SDK for Python

Async Python SDK for the Dominus gateway-first service plane.

## 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
- Local helpers for JWT verification, trace propagation, retries, and console capture
- Current package version: `3.0.4`

## Install

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

## Quick Start

```python
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(
    "wf://carebridge/report-cycle",
    subject="PCM47474562",
    company="summit-radiology",
)

timeline = await dominus.workflow.get_run_timeline(run["run_id"])
```

## 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:

```python
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
- 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 canonical 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, companies, deploys, managed clients, context |
| `deployer` | Deployer | Thin operator control-plane request surface |
| `warden` | Warden | Thin operator control-plane request surface |
| `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.

## Documentation

- [Architecture](docs/architecture.md) - request flow, gateway routing, resilience
- [Services Reference](docs/services.md) - namespace inventory and endpoint mapping
- [Development](docs/development.md) - setup, testing, publishing, extension patterns

## Verification

```bash
pip install -e .[dev]
python -m pytest tests -q
python -m build
```

## License

Proprietary - CareBridge Systems
