Metadata-Version: 2.4
Name: dominus-sdk-python
Version: 2.15.1
Summary: Python SDK for the Dominus Orchestrator 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,orchestrator,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: oracle
Requires-Dist: websockets>=12.0; extra == "oracle"
Requires-Dist: sounddevice>=0.4.6; extra == "oracle"
Requires-Dist: numpy>=1.24.0; extra == "oracle"
Requires-Dist: webrtcvad>=2.0.10; extra == "oracle"
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"
Requires-Dist: websockets>=12.0; extra == "all"
Requires-Dist: sounddevice>=0.4.6; extra == "all"
Requires-Dist: numpy>=1.24.0; extra == "all"
Requires-Dist: webrtcvad>=2.0.10; extra == "all"

# Dominus SDK for Python

Async Python SDK for CareBridge Dominus platform services. Routes calls through the Dominus Gateway with JWT-based authentication, base64 wire encoding, retries, and circuit breaking.

## What This Is

- Server-side, asyncio-first Python SDK (3.9+)
- Namespace API with root-level shortcuts for common operations
- Targets production Cloudflare Workers (gateway, JWT, logs) and Cloud Run (orchestrator)
- Version: 2.15.1

## Quick Start

```python
import os
from dominus import dominus

os.environ["DOMINUS_TOKEN"] = "your-psk-token"

# Secrets
value = await dominus.secrets.get("DB_URL")
await dominus.secrets.upsert("API_KEY", "secret_value")

# Database CRUD
users = await dominus.db.query("users", filters={"status": "active"})
await dominus.db.insert("users", {"name": "John", "email": "john@example.com"})

# Redis caching
await dominus.redis.set("session:123", {"user": "john"}, ttl=3600)
value = await dominus.redis.get("session:123")

# File storage
result = await dominus.files.upload(data=buf, filename="report.pdf", category="reports")

# AI agent execution
result = await dominus.ai.run_agent(
    conversation_id="conv-123",
    system_prompt="You are helpful.",
    user_prompt="Hello!"
)

# Streaming AI
async for chunk in dominus.ai.stream_agent(
    conversation_id="conv-123",
    system_prompt="You are helpful.",
    user_prompt="Tell me a story"
):
    print(chunk.get("content", ""), end="", flush=True)

# Saved workflow lifecycle through workflow-manager
run = await dominus.workflow.create_run(
    workflow_id="wf_saved_123",
    context={"report_ref": {"report_id": "r-1", "accession": "a-1", "session_number": "2"}},
)
await dominus.workflow.validate_run(run["run_id"])
result = await dominus.workflow.start_run(run["run_id"])

# Raw orchestration lifecycle with inline workflow definition
raw_run = await dominus.ai.workflow.create_run(
    workflow_definition={"workflow": {"name": "raw"}, "agents": {}, "artifacts": {}},
)
await dominus.ai.workflow.validate_run(raw_run["run_id"])
raw_result = await dominus.ai.workflow.start_run(raw_run["run_id"])
```

## Architecture (SDK View)

```
DOMINUS_TOKEN (PSK) --> Gateway /jwt/mint --> JWT cached (14min TTL)
                                |
                                v
                    Gateway /svc/* (AI, workflow, logs)
                         or
                    Orchestrator /api/* (all other services)
```

- JSON requests/responses are base64-encoded for auth-required routes
- GET requests send no body; parameters go in the path or query string
- Gateway routing (`/api/*` -> `/svc/*`) is used by AI, workflow, and logs namespaces
- Orchestrator handles secrets, db, auth, ddl, files, redis, portal, courier, open, health, admin

## Namespaces

| Namespace | Service | Description |
|-----------|---------|-------------|
| `secrets` | Warden | Secrets CRUD |
| `db` | Scribe | Database CRUD with optional secure-table audit |
| `secure` / `db_secure` | Scribe | Audit-logged data access (requires reason/actor) |
| `redis` | Redis Worker | Cache, locks, counters, hashes |
| `files` | Archivist | Object storage with compliance mode |
| `auth` | Guardian | Users, roles, scopes, tenants, clients, pages, nav, subtypes, secure tables (147 methods) |
| `ddl` | Smith | Schema DDL, migrations, tenant provisioning, schema builder |
| `logs` | Logs Worker | Structured logging with callsite capture |
| `portal` | Portal | Login, sessions, profile, preferences, navigation, registration |
| `courier` | Courier | Postmark email delivery |
| `open` | Scribe Open | Raw SQL / DSN retrieval |
| `health` | Orchestrator | Health/ping/warmup |
| `admin` | Admin | Reseed/reset admin category |
| `ai` | Agent Runtime | Agent execution, LLM completions, RAG, artifacts, results, orchestration, STT/TTS |
| `workflow` | Workflow Manager | Workflow CRUD, pipelines/templates, saved-workflow run lifecycle, native pipeline runner |
| `oracle` / `stt` | Oracle | Real-time streaming STT with VAD (WebSocket, requires `oracle` extras) |
| `fastapi` | Local | FastAPI route auth decorators (`@jwt`, `@psk`, `@scopes`) |

## Configuration

**Required:**
- `DOMINUS_TOKEN` -- PSK token for gateway authentication

**Optional:**
- `DOMINUS_GATEWAY_URL` -- Override gateway URL (default: `https://gateway.getdominus.app`)
- `DOMINUS_JWT_URL` -- Override JWT worker URL (default: `https://jwt.getdominus.app`)
- `DOMINUS_LOGS_URL` -- Override logs worker URL (default: `https://logs.getdominus.app`)
- `DOMINUS_BASE_URL` -- Override orchestrator URL (default: production Cloud Run)
- `DOMINUS_HTTP_PROXY` / `DOMINUS_HTTPS_PROXY` -- httpx proxy configuration
- `DOMINUS_CAPTURE_CONSOLE` -- Set to `"true"` to auto-forward `print()` and `logging.*` to Logs Worker

## Installation

```bash
pip install dominus-sdk-python

# With optional extras
pip install dominus-sdk-python[jwt]      # Local JWT verification
pip install dominus-sdk-python[oracle]   # WebSocket STT (websockets, numpy, sounddevice, webrtcvad)
pip install dominus-sdk-python[all]      # Everything
```

## Console Capture

Forward `print()` and `logging.*` to the Dominus Logs Worker:

```python
# Automatic (via env var, before importing SDK):
os.environ["DOMINUS_CAPTURE_CONSOLE"] = "true"

# Manual:
dominus.capture_console()     # start capturing
dominus.release_console()     # stop capturing
```

## Documentation

- [Architecture](docs/architecture.md) -- Request flow, resilience, JWT verification
- [Services Reference](docs/services.md) -- Complete namespace and method inventory
- [Development](docs/development.md) -- Setup, testing, adding APIs
- [Workflow hard-cut release notes](docs/workflow-hard-cut-release.md) -- cutover notes and operational checks

## Workflow Surfaces

- `dominus.workflow.*` is the saved-workflow facade through `dominus-workflow-manager`. Use it for stored workflow IDs and the artifact-aware run lifecycle: `create_run -> register_artifact -> validate_run -> start_run`.
- `dominus.ai.workflow.*` is the raw orchestration surface. It requires inline `workflow_definition` data. It does not support saved-workflow IDs directly.
- `dominus.workflow.execute_pipeline()` runs stored pipelines through workflow-manager's native orchestration-backed runner.

## License

Proprietary - CareBridge Systems
