dominus-sdk-python 4.5.0__tar.gz → 4.6.1__tar.gz

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 4.5.0
+Version: 4.6.1
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus/__init__.py

@@ -112,6 +112,7 @@ from .namespaces.processor import ProcessorNamespace
 from .namespaces.sync import SyncNamespace
 from .namespaces.authority import AuthorityNamespace
 from .namespaces.browser import BrowserNamespace
+from .namespaces.recipes import RecipesNamespace
 from .namespaces.deployer import DeployerNamespace
 from .namespaces.warden import WardenNamespace
 
@@ -164,7 +165,7 @@ from .errors import (
     TimeoutError as DominusTimeoutError,
 )
 
-__version__ = "4.5.0"
+__version__ = "4.6.1"
 __all__ = [
     # Main SDK instance
     "dominus",
@@ -215,6 +216,7 @@ __all__ = [
     "SyncNamespace",
     "AuthorityNamespace",
     "BrowserNamespace",
+    "RecipesNamespace",
     "DeployerNamespace",
     "WardenNamespace",
     # AI namespace for agent-runtime operations

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus/namespaces/__init__.py

@@ -16,6 +16,7 @@ from .processor import ProcessorNamespace
 from .sync import SyncNamespace
 from .authority import AuthorityNamespace
 from .browser import BrowserNamespace
+from .recipes import RecipesNamespace
 from .deployer import DeployerNamespace
 from .warden import WardenNamespace
 from .ai import (
@@ -44,6 +45,7 @@ __all__ = [
     "SyncNamespace",
     "AuthorityNamespace",
     "BrowserNamespace",
+    "RecipesNamespace",
     "DeployerNamespace",
     "WardenNamespace",
     "AiNamespace",

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus/namespaces/browser.py

@@ -77,7 +77,7 @@ class BrowserNamespace:
     async def ensure_run(
         self,
         *,
-        target: Dict[str, Any],
+        target: Optional[Dict[str, Any]] = None,
         idempotency_key: Optional[str] = None,
         run_kind: Optional[str] = None,
         route_label: Optional[str] = None,
@@ -92,11 +92,29 @@ class BrowserNamespace:
         org_id: Optional[str] = None,
         app_slug: Optional[str] = None,
         env: Optional[str] = None,
+        recipe_ref: Optional[str] = None,
+        recipe: Optional[Any] = None,
+        recipe_inputs: Optional[Dict[str, Any]] = None,
         timeout: float = 30.0,
     ) -> Dict[str, Any]:
         """
         Ensure a browser run. ``POST /api/browser/runs/ensure``.
 
+        ``target`` shorthand, ``recipe_ref``, or inline ``recipe`` must be
+        present. When ``recipe_ref`` is set, the worker resolves the
+        recipe through the recipe-worker, parses it, resolves variables, and
+        runs it through the recipe executor — supporting multi-step flows
+        including clicks, fills, assertions, extracts, and stash-backed
+        credential fills.
+
+        ``recipe`` may be an inline YAML string or JSON object for one-off
+        runs. Stable/shared recipes should be published and referenced via
+        ``recipe_ref``. Target/assertion shorthand runs are synthesized into a
+        ``browser-recipe-v1`` recipe internally; there is no separate runner path.
+
+        ``recipe_inputs`` supplies scalar values consumed by ``recipe-input://``
+        variable refs declared in the recipe's vars map.
+
         Browser run metadata remains browser-worker runtime state. Artifact V2
         is used for sanitized `browser-run` result payloads and, when opted-in
         via ``capture_policy["storage_state"] = "always"`` plus
@@ -109,8 +127,8 @@ class BrowserNamespace:
         lookup, returns no storage_state on first call) or an explicit
         ``session_artifact_ref`` (hard-error if the ref does not exist).
         """
-        if not target:
-            raise ValueError("target is required")
+        if not target and not recipe_ref and recipe is None:
+            raise ValueError("target, recipe_ref, or recipe is required")
         body = _compact({
             "idempotency_key": idempotency_key,
             "run_kind": run_kind,
@@ -127,6 +145,9 @@ class BrowserNamespace:
             "org_id": org_id,
             "app_slug": app_slug,
             "env": env,
+            "recipe_ref": recipe_ref,
+            "recipe": recipe,
+            "recipe_inputs": recipe_inputs,
         })
         return await self._post("/api/browser/runs/ensure", body, timeout=timeout)
 

dominus_sdk_python-4.6.1/dominus/namespaces/recipes.py

@@ -0,0 +1,165 @@
+"""
+Recipes Namespace - kernel-tier recipe protocol.
+
+Routes through ``/svc/recipe/*`` on the Dominus gateway. The recipe worker
+owns the type registry, JSON-Schema-based publish validation, three-tier
+resolution (project -> group -> platform), and B2-backed durable storage.
+
+Recipe types currently registered:
+  - browser-recipe (owned by dominus-browser-worker; body version is browser-recipe-v1)
+
+Refs follow ``recipe://{type}/{name}[@v{N}][?tier={tier}]``.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+def _compact(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in payload.items() if v is not None and v != ""}
+
+
+class RecipesNamespace:
+    """
+    Recipe worker namespace.
+
+    Usage::
+
+        types = await dominus.recipes.list_types()
+        await dominus.recipes.publish(
+            type="browser-recipe",
+            tier="platform",
+            name="health-check",
+            body="version: browser-recipe-v1\\nsteps:\\n  - kind: goto\\n    url: https://x/\\n",
+        )
+        recipe = await dominus.recipes.get(type="browser-recipe", name="health-check")
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def _post(self, endpoint: str, body: Optional[Dict[str, Any]] = None, *, timeout: float = 30.0) -> Dict[str, Any]:
+        return await self._client._request(
+            endpoint=endpoint,
+            method="POST",
+            body=body or {},
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def _get(self, endpoint: str, *, timeout: float = 30.0) -> Dict[str, Any]:
+        return await self._client._request(
+            endpoint=endpoint,
+            method="GET",
+            use_gateway=True,
+            timeout=timeout,
+        )
+
+    async def list_types(self, *, owning_worker: Optional[str] = None, timeout: float = 15.0) -> Dict[str, Any]:
+        """List registered recipe types. ``GET /api/recipe/types``."""
+        query = f"?owning_worker={owning_worker}" if owning_worker else ""
+        return await self._get(f"/api/recipe/types{query}", timeout=timeout)
+
+    async def get_type(self, name: str, *, timeout: float = 15.0) -> Dict[str, Any]:
+        """Fetch a registered recipe type's schema. ``GET /api/recipe/types/{name}``."""
+        return await self._get(f"/api/recipe/types/{name}", timeout=timeout)
+
+    async def publish(
+        self,
+        *,
+        type: str,
+        tier: str,
+        name: str,
+        body: str,
+        description: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> Dict[str, Any]:
+        """Publish a recipe. ``POST /api/recipe/recipes/publish``."""
+        return await self._post(
+            "/api/recipe/recipes/publish",
+            _compact({
+                "type": type,
+                "tier": tier,
+                "name": name,
+                "body": body,
+                "description": description,
+            }),
+            timeout=timeout,
+        )
+
+    async def validate(
+        self,
+        *,
+        type: str,
+        body: str,
+        timeout: float = 15.0,
+    ) -> Dict[str, Any]:
+        """Validate a recipe body against its type schema. ``POST /api/recipe/recipes/validate``."""
+        return await self._post(
+            "/api/recipe/recipes/validate",
+            {"type": type, "body": body},
+            timeout=timeout,
+        )
+
+    async def list(
+        self,
+        *,
+        type: Optional[str] = None,
+        tier: Optional[str] = None,
+        name_prefix: Optional[str] = None,
+        timeout: float = 15.0,
+    ) -> Dict[str, Any]:
+        """List recipes filtered by type/tier/name. ``GET /api/recipe/recipes/list``."""
+        params: List[str] = []
+        if type:
+            params.append(f"type={type}")
+        if tier:
+            params.append(f"tier={tier}")
+        if name_prefix:
+            params.append(f"name_prefix={name_prefix}")
+        query = ("?" + "&".join(params)) if params else ""
+        return await self._get(f"/api/recipe/recipes/list{query}", timeout=timeout)
+
+    async def get(
+        self,
+        *,
+        type: str,
+        name: str,
+        version: Optional[int] = None,
+        tier: Optional[str] = None,
+        timeout: float = 15.0,
+    ) -> Dict[str, Any]:
+        """Resolve a recipe through the three-tier chain. ``GET /api/recipe/recipes/{type}/{name}[@v{N}]``."""
+        path = f"/api/recipe/recipes/{type}/{name}"
+        if version is not None:
+            path += f"@v{version}"
+        if tier:
+            path += f"?tier={tier}"
+        return await self._get(path, timeout=timeout)
+
+    async def register_type(
+        self,
+        *,
+        name: str,
+        owning_worker: str,
+        schema_version: int,
+        json_schema: Dict[str, Any],
+        timeout: float = 15.0,
+    ) -> Dict[str, Any]:
+        """Register a recipe type. ``POST /api/recipe/types/register``.
+
+        Owning workers do this on cold start. Normal callers should not need it.
+        """
+        return await self._post(
+            "/api/recipe/types/register",
+            {
+                "name": name,
+                "owning_worker": owning_worker,
+                "schema_version": schema_version,
+                "json_schema": json_schema,
+            },
+            timeout=timeout,
+        )

dominus_sdk_python-4.6.1/dominus/namespaces/stash.py

@@ -0,0 +1,275 @@
+"""
+Stash Namespace - per-scope durable items (credentials + configs).
+
+Routes through ``/svc/stash/*`` on the Dominus gateway. The stash worker
+stores items in each project's ``stash.*`` schema and transparently falls
+back to a designated shared project on read.
+"""
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..start import Dominus
+
+
+class StashNamespace:
+    """
+    Stash worker namespace.
+
+    Usage:
+        item = await dominus.stash.resolve(
+            kind="credential.vendor.fuji_synapse",
+            scope={"user_id": user_id, "organization_code": "piedmont"},
+            purpose="extraction",
+        )
+        await dominus.stash.mark_verified(id=item["id"], purpose="extraction")
+    """
+
+    def __init__(self, client: "Dominus"):
+        self._client = client
+
+    async def upsert(
+        self,
+        *,
+        kind: str,
+        scope: Dict[str, Any],
+        value: Dict[str, Any],
+        id: Optional[str] = None,
+        target: Optional[str] = None,
+        item_key: Optional[str] = None,
+        role: Optional[str] = None,
+        priority: Optional[int] = None,
+        is_sensitive: Optional[bool] = None,
+        rotation_interval_days: Optional[int] = None,
+        expires_at: Optional[str] = None,
+        purpose: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Insert or update a stash item."""
+        body: Dict[str, Any] = {"kind": kind, "scope": scope, "value": value}
+        if id is not None:
+            body["id"] = id
+        if target is not None:
+            body["target"] = target
+        if item_key is not None:
+            body["item_key"] = item_key
+        if role is not None:
+            body["role"] = role
+        if priority is not None:
+            body["priority"] = priority
+        if is_sensitive is not None:
+            body["is_sensitive"] = is_sensitive
+        if rotation_interval_days is not None:
+            body["rotation_interval_days"] = rotation_interval_days
+        if expires_at is not None:
+            body["expires_at"] = expires_at
+        if purpose is not None:
+            body["purpose"] = purpose
+        return await self._client._request(
+            endpoint="/svc/stash/items/upsert",
+            body=body,
+            use_gateway=True,
+        )
+
+    async def get(
+        self,
+        id: str,
+        *,
+        purpose: Optional[str] = None,
+        include_shared: Optional[bool] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Fetch a single item by id; decrypts sensitive values."""
+        body: Dict[str, Any] = {"id": id}
+        if purpose is not None:
+            body["purpose"] = purpose
+        if include_shared is not None:
+            body["include_shared"] = include_shared
+        result = await self._client._request(
+            endpoint="/svc/stash/items/get",
+            body=body,
+            use_gateway=True,
+        )
+        return result.get("item") if isinstance(result, dict) else None
+
+    async def resolve(
+        self,
+        *,
+        kind: str,
+        scope: Dict[str, Any],
+        purpose: str,
+        fallback_roles: Optional[List[str]] = None,
+        health_status_in: Optional[List[str]] = None,
+        machine_id: Optional[str] = None,
+        include_shared: Optional[bool] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Resolve the best-priority match by (kind, scope) with fallback walk."""
+        body: Dict[str, Any] = {"kind": kind, "scope": scope, "purpose": purpose}
+        if fallback_roles is not None:
+            body["fallback_roles"] = fallback_roles
+        if health_status_in is not None:
+            body["health_status_in"] = health_status_in
+        if machine_id is not None:
+            body["machine_id"] = machine_id
+        if include_shared is not None:
+            body["include_shared"] = include_shared
+        result = await self._client._request(
+            endpoint="/svc/stash/items/resolve",
+            body=body,
+            use_gateway=True,
+        )
+        return result.get("item") if isinstance(result, dict) else None
+
+    async def list(
+        self,
+        *,
+        kind: Optional[str] = None,
+        scope: Optional[Dict[str, Any]] = None,
+        role: Optional[str] = None,
+        health_status: Optional[Any] = None,
+        scope_origin: Optional[str] = None,
+        include_deleted: Optional[bool] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """List items by (kind, partial scope, role, health). Metadata only."""
+        body: Dict[str, Any] = {}
+        if kind is not None:
+            body["kind"] = kind
+        if scope is not None:
+            body["scope"] = scope
+        if role is not None:
+            body["role"] = role
+        if health_status is not None:
+            body["health_status"] = health_status
+        if scope_origin is not None:
+            body["scope_origin"] = scope_origin
+        if include_deleted is not None:
+            body["include_deleted"] = include_deleted
+        if limit is not None:
+            body["limit"] = limit
+        if offset is not None:
+            body["offset"] = offset
+        return await self._client._request(
+            endpoint="/svc/stash/items/list",
+            body=body,
+            use_gateway=True,
+        )
+
+    async def mark_verified(
+        self, *, id: str, purpose: str, detail: Optional[str] = None
+    ) -> Optional[Dict[str, Any]]:
+        """Mark an item as verified after a successful use; resets failure_count."""
+        body: Dict[str, Any] = {"id": id, "purpose": purpose}
+        if detail is not None:
+            body["detail"] = detail
+        result = await self._client._request(
+            endpoint="/svc/stash/items/mark-verified",
+            body=body,
+            use_gateway=True,
+        )
+        return result.get("item") if isinstance(result, dict) else None
+
+    async def mark_failed(
+        self,
+        *,
+        id: str,
+        purpose: str,
+        failure_reason: Optional[str] = None,
+        detail: Optional[str] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Mark an item as failed; increments failure_count, sets last_failed_at."""
+        body: Dict[str, Any] = {"id": id, "purpose": purpose}
+        if failure_reason is not None:
+            body["failure_reason"] = failure_reason
+        if detail is not None:
+            body["detail"] = detail
+        result = await self._client._request(
+            endpoint="/svc/stash/items/mark-failed",
+            body=body,
+            use_gateway=True,
+        )
+        return result.get("item") if isinstance(result, dict) else None
+
+    async def delete(self, id: str, *, purpose: Optional[str] = None) -> bool:
+        """Soft-delete an item (sets deleted_at)."""
+        body: Dict[str, Any] = {"id": id}
+        if purpose is not None:
+            body["purpose"] = purpose
+        result = await self._client._request(
+            endpoint="/svc/stash/items/delete",
+            body=body,
+            use_gateway=True,
+        )
+        return bool(result.get("deleted")) if isinstance(result, dict) else False
+
+    async def register_kind(
+        self,
+        *,
+        kind: str,
+        is_sensitive: Optional[bool] = None,
+        value_schema: Optional[Dict[str, Any]] = None,
+        default_rotation_days: Optional[int] = None,
+        verification_probe_ref: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Register or update a kind in stash.kind_registry. Admin-scoped."""
+        body: Dict[str, Any] = {"kind": kind}
+        if is_sensitive is not None:
+            body["is_sensitive"] = is_sensitive
+        if value_schema is not None:
+            body["value_schema"] = value_schema
+        if default_rotation_days is not None:
+            body["default_rotation_days"] = default_rotation_days
+        if verification_probe_ref is not None:
+            body["verification_probe_ref"] = verification_probe_ref
+        if description is not None:
+            body["description"] = description
+        result = await self._client._request(
+            endpoint="/svc/stash/kinds/register",
+            body=body,
+            use_gateway=True,
+        )
+        return result.get("kind", {}) if isinstance(result, dict) else {}
+
+    async def list_kinds(self) -> List[Dict[str, Any]]:
+        """List registered kinds (own + shared merged)."""
+        result = await self._client._request(
+            endpoint="/svc/stash/kinds/list",
+            body={},
+            use_gateway=True,
+        )
+        return result.get("kinds", []) if isinstance(result, dict) else []
+
+    async def query_audit(
+        self,
+        *,
+        item_id: Optional[str] = None,
+        kind: Optional[str] = None,
+        caller_id: Optional[str] = None,
+        action: Optional[str] = None,
+        occurred_after: Optional[str] = None,
+        occurred_before: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """Query the append-only audit log. Hashes only — never plaintext."""
+        body: Dict[str, Any] = {}
+        if item_id is not None:
+            body["item_id"] = item_id
+        if kind is not None:
+            body["kind"] = kind
+        if caller_id is not None:
+            body["caller_id"] = caller_id
+        if action is not None:
+            body["action"] = action
+        if occurred_after is not None:
+            body["occurred_after"] = occurred_after
+        if occurred_before is not None:
+            body["occurred_before"] = occurred_before
+        if limit is not None:
+            body["limit"] = limit
+        if offset is not None:
+            body["offset"] = offset
+        return await self._client._request(
+            endpoint="/svc/stash/audit/query",
+            body=body,
+            use_gateway=True,
+        )

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus/start.py

@@ -182,6 +182,14 @@ class Dominus:
         self.deployer = DeployerNamespace(self)
         self.warden = WardenNamespace(self)
 
+        # Stash worker (per-scope durable items: credentials + configs)
+        from .namespaces.stash import StashNamespace
+        self.stash = StashNamespace(self)
+
+        # Recipe worker (kernel-tier; hosts browser-recipe-v1 today, workflow + envoy + others later)
+        from .namespaces.recipes import RecipesNamespace
+        self.recipes = RecipesNamespace(self)
+
         # Cache for JWT public key
         self._public_key_cache = None
 

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dominus-sdk-python
-Version: 4.5.0
+Version: 4.6.1
 Summary: Python SDK for the Dominus gateway-first platform
 Author-email: CareBridge Systems <dev@carebridge.io>
 License: Proprietary

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/dominus_sdk_python.egg-info/SOURCES.txt

@@ -31,9 +31,11 @@ dominus/namespaces/jobs.py
 dominus/namespaces/logs.py
 dominus/namespaces/portal.py
 dominus/namespaces/processor.py
+dominus/namespaces/recipes.py
 dominus/namespaces/redis.py
 dominus/namespaces/secrets.py
 dominus/namespaces/secure.py
+dominus/namespaces/stash.py
 dominus/namespaces/sync.py
 dominus/namespaces/warden.py
 dominus/namespaces/workflow.py

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dominus-sdk-python"
-version = "4.5.0"
+version = "4.6.1"
 description = "Python SDK for the Dominus gateway-first platform"
 readme = "README.md"
 license = {text = "Proprietary"}

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/tests/test_browser_namespace.py

@@ -59,6 +59,8 @@ async def test_browser_namespace_uses_gateway_routed_api_browser_paths(monkeypat
         ],
         authority={"run_id": "auth-run-1", "artifact_observations": True},
         metadata={"route": "dashboard"},
+        recipe={"version": "browser-recipe-v1", "steps": [{"kind": "goto", "url": "https://summit.example/dashboard"}]},
+        recipe_inputs={"tenant": "summit"},
     )
     await sdk.browser.start_run("br_123")
     await sdk.browser.get_run_status("br_123")
@@ -99,9 +101,11 @@ async def test_browser_namespace_uses_gateway_routed_api_browser_paths(monkeypat
         "run_id": "auth-run-1",
         "artifact_observations": True,
     }
+    assert ensure_body["recipe"]["version"] == "browser-recipe-v1"
+    assert ensure_body["recipe_inputs"] == {"tenant": "summit"}
 
 
 @pytest.mark.asyncio
-async def test_browser_ensure_run_requires_target(sdk):
-    with pytest.raises(ValueError, match="target is required"):
+async def test_browser_ensure_run_requires_target_or_recipe(sdk):
+    with pytest.raises(ValueError, match="target, recipe_ref, or recipe is required"):
         await sdk.browser.ensure_run(target={})

{dominus_sdk_python-4.5.0 → dominus_sdk_python-4.6.1}/tests/test_public_exports.py

@@ -1,6 +1,7 @@
 from dominus import (
     BrowserNamespace,
     DeployerNamespace,
+    RecipesNamespace,
     WardenNamespace,
     gateway_circuit_breaker,
     mint_selected_scope_jwt,
@@ -31,9 +32,11 @@ def test_top_level_exports_drop_delegate_alias():
     assert DeployerNamespace is not None
     assert WardenNamespace is not None
     assert BrowserNamespace is not None
+    assert RecipesNamespace is not None
 
 
 def test_singleton_exposes_browser_namespace():
     from dominus import dominus
 
     assert callable(dominus.browser.get_health)
+    assert callable(dominus.recipes.list_types)