decidio 0.1.0__py3-none-any.whl

decidio/__init__.py

@@ -0,0 +1,40 @@
+"""@decidio/guard (Python) — the one-line approval gate for AI-agent actions.
+
+    from decidio import guard
+    @guard.approve(lambda o: {"action": "createOpportunity", "amount": o["amount"]})
+    async def create_opp(o): ...        # no rename, no call-site change
+
+    # or the wrap form, when you cannot decorate the definition:
+    create_opp = guard.protect(create_opp_raw,
+        lambda o: {"action": "createOpportunity", "amount": o["Amount"], "scope": "Opportunity"})
+
+Decidio gates (proceed | route | block) + records a portable, verifiable Authority
+Receipt the customer owns; the AGENT executes its own action on resume. Decidio never
+executes and holds no downstream credentials.
+"""
+from .guard import Guard, GuardConfig, guard, protect, approve, ApprovalContext
+from .resume import (
+    ResumeController,
+    PendingAction,
+    PendingStore,
+    MemoryPendingStore,
+    FilePendingStore,
+    sign_body,
+    verify_signature,
+)
+from .errors import (
+    DecidioError,
+    DecidioBlocked,
+    DecidioRejected,
+    DecidioSuspended,
+    DecidioTimeout,
+)
+
+__all__ = [
+    "guard", "protect",
+    "approve", "Guard", "GuardConfig", "ApprovalContext",
+    "ResumeController", "PendingAction", "PendingStore", "MemoryPendingStore", "FilePendingStore",
+    "sign_body", "verify_signature",
+    "DecidioError", "DecidioBlocked", "DecidioRejected", "DecidioSuspended", "DecidioTimeout",
+]
+__version__ = "0.1.0"

decidio/__main__.py

@@ -0,0 +1,8 @@
+import sys
+try:
+    sys.stdout.reconfigure(encoding="utf-8")
+except Exception:
+    pass
+from .cli import main
+
+raise SystemExit(main())

decidio/_client.py

@@ -0,0 +1,71 @@
+"""Low-level gate transport — the HTTP calls to Decidio's agent floor.
+
+Pluggable `Transport` so the SDK is testable offline (inject a fake) and so a host
+can swap in its own HTTP stack. Default uses urllib (stdlib — the core stays
+dependency-free). Shared by the gate (authorize) and the resume controller
+(status/confirm) so there's one transport contract.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from urllib.parse import quote
+from typing import Any, Optional, Protocol, Tuple
+
+
+class Transport(Protocol):
+    def request(self, method: str, url: str, headers: dict, body: Optional[str]) -> Tuple[int, str]:
+        ...
+
+
+class UrllibTransport:
+    def __init__(self, timeout: float = 30.0):
+        self.timeout = timeout
+
+    def request(self, method: str, url: str, headers: dict, body: Optional[str]) -> Tuple[int, str]:
+        data = body.encode("utf-8") if body is not None else None
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return resp.status, resp.read().decode("utf-8")
+        except urllib.error.HTTPError as e:  # 4xx/5xx still carry a body
+            return e.code, e.read().decode("utf-8")
+
+
+def _headers(api_token: Optional[str]) -> dict:
+    h = {"content-type": "application/json"}
+    if api_token:
+        h["authorization"] = f"Bearer {api_token}"
+    return h
+
+
+def post(transport: Transport, api_url: str, path: str, body: dict, api_token: Optional[str]) -> Any:
+    status, text = transport.request("POST", api_url.rstrip("/") + path, _headers(api_token), json.dumps(body))
+    if not (200 <= status < 300):
+        raise RuntimeError(f"decidio {path} {status}: {text}")
+    return json.loads(text) if text else {}
+
+
+def get(transport: Transport, api_url: str, path: str, api_token: Optional[str]) -> Any:
+    status, text = transport.request("GET", api_url.rstrip("/") + path, _headers(api_token), None)
+    if not (200 <= status < 300):
+        raise RuntimeError(f"decidio {path} {status}")
+    return json.loads(text) if text else {}
+
+
+def confirm(transport: Transport, api_url: str, api_token: Optional[str], decision_id: str, captured: Any, requester_identity: Optional[dict] = None) -> None:
+    """Report the captured source response. A `requester_identity` bound proof lets the gate
+    grant the wrapper tier (application_confirmed); without it the server caps at agent_asserted."""
+    body: dict = {
+        "decisionId": decision_id,
+        "capturedResponse": captured if captured is not None else None,
+        "source": "wrapper",
+    }
+    if requester_identity is not None:
+        body["requesterIdentity"] = requester_identity
+    post(transport, api_url, "/agent/confirm", body, api_token)
+
+
+def status_of(transport: Transport, api_url: str, api_token: Optional[str], decision_id: str) -> dict:
+    return get(transport, api_url, "/agent/status/" + quote(decision_id, safe=""), api_token)

decidio/adapters/__init__.py

@@ -0,0 +1,35 @@
+"""Engine adapters — each maps the Decidio gate onto an engine's native durable wait.
+Thin by rule (see _common): only the suspend/resume translation lives here.
+
+`bind(name, ...)` backs `guard.protect(fn, describe, adapter=name)` for engines whose
+wait primitive is contextvar-based (LangGraph `interrupt`, Temporal `wait_condition`) —
+those are true drop-ins. Engines that pass an explicit handle (Inngest `step`, OpenAI
+Agents `RunState`) are used via their own `gate(...)` functions (they need the handle
+at call time); see decidio/adapters/{inngest,openai}.py.
+"""
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+
+
+def bind(name: str, guard: Any, fn: Callable[..., Any], describe: Callable[..., dict]) -> Callable[..., Any]:
+    if name == "langgraph":
+        from . import langgraph as lg
+
+        # functools.wraps for the same reason the core wrapper has it: OpenAI function-calling
+        # and LangChain @tool build the tool schema by INTROSPECTING the function, and an
+        # adapter-bound tool reporting `wrapped(*args, **kwargs)` hands the model an empty schema.
+        @functools.wraps(fn)
+        def wrapped(*a: Any, **k: Any) -> Any:
+            return lg.gate(guard, describe(*a, **k), lambda: fn(*a, **k))
+        return wrapped
+
+    if name in ("inngest", "temporal", "openai"):
+        # These pass an explicit handle at call time (Inngest `step`, Temporal workflow
+        # self, OpenAI RunState), so they can't be a no-arg `protect` drop-in.
+        raise ValueError(
+            f'the "{name}" adapter needs the engine handle at call time — call '
+            f"decidio.adapters.{name}.gate(...) directly (see its docstring)."
+        )
+    raise ValueError(f'unknown adapter "{name}"')

decidio/adapters/_common.py

@@ -0,0 +1,50 @@
+"""Shared adapter core — the thin-adapter rule in code. Every engine adapter reuses
+these gate calls; only the *suspend/resume* translation differs per engine. Policy,
+sealing, and the record live in Decidio (the core), never in an adapter."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .. import _client
+
+
+@dataclass
+class AuthResult:
+    decision: str          # "proceed" | "route" | "block"
+    decision_id: str
+    receipt_id: Optional[str] = None
+    reason: Optional[str] = None
+
+
+def authorize(guard: Any, ctx: dict, resume_url: Optional[str] = None) -> AuthResult:
+    cfg = guard.config
+    # Omit None optionals — the server's zod schema rejects null for optional fields.
+    body = {"requester": cfg.agent_id, "action": ctx["action"], "amount": ctx["amount"]}
+    if ctx.get("scope") is not None:
+        body["scope"] = ctx["scope"]
+    if cfg.source_system is not None:
+        body["sourceSystem"] = cfg.source_system
+    # Sign the bound proof so an adapter-path agent can prove its identity + auto-approve.
+    if cfg.agent_key and cfg.agent_did:
+        from ..signing import sign_bound_proof
+        body["requesterIdentity"] = sign_bound_proof(cfg.agent_key, agent_id=cfg.agent_id, did=cfg.agent_did, action=ctx["action"], amount=ctx["amount"], scope=ctx.get("scope"), workspace_id=getattr(cfg, "workspace_id", None))
+    url = resume_url or cfg.resume_url
+    if url:
+        body["resumeUrl"] = url
+    auth = _client.post(guard.transport, cfg.api_url, "/agent/authorize", body, cfg.api_token)
+    return AuthResult(auth["decision"], auth["decisionId"], auth.get("receiptId"), auth.get("reason"))
+
+
+def confirm(guard: Any, decision_id: str, result: Any) -> None:
+    cfg = guard.config
+    try:
+        # Sign the confirm (bound to {action:"confirm", scope:decisionId}) so the adapter path
+        # earns application_confirmed; without a key the server caps it at agent_asserted.
+        ri = None
+        if cfg.agent_key and cfg.agent_did:
+            from ..signing import sign_bound_proof
+            ri = sign_bound_proof(cfg.agent_key, agent_id=cfg.agent_id, did=cfg.agent_did, action="confirm", amount=0, scope=decision_id, workspace_id=getattr(cfg, "workspace_id", None))
+        _client.confirm(guard.transport, cfg.api_url, cfg.api_token, decision_id, result, ri)
+    except Exception as e:  # noqa: BLE001 — best-effort; the action already happened
+        print(f"[decidio] confirm failed (action succeeded): {e}")

decidio/adapters/inngest.py

@@ -0,0 +1,60 @@
+"""Inngest adapter (Python) — durable suspend via the engine's native
+`step.wait_for_event` (mirror of the verified TS Inngest adapter). Decidio keeps its
+ONE signed-webhook contract; a bridge translates that webhook into the Inngest event
+that wakes the suspended function (see `resume_event`).
+
+Usage inside an Inngest function `async def fn(ctx, step)`:
+    out = await decidio.adapters.inngest.gate(step, guard, ctx, run=lambda: create_opp(o))
+"""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..errors import DecidioBlocked, DecidioRejected
+from ._common import authorize, confirm
+
+DECIDIO_RESUME_EVENT = "decidio/decision.resolved"
+
+
+def _authorize_dict(guard: Any, ctx: dict) -> dict:
+    a = authorize(guard, ctx)
+    return {"decision": a.decision, "decisionId": a.decision_id, "receiptId": a.receipt_id, "reason": a.reason}
+
+
+async def gate(step: Any, guard: Any, ctx: dict, run: Callable[[], Any], timeout: str = "30d") -> Any:
+    # authorize as a memoized step (a replay doesn't re-ask the gate)
+    auth = await step.run("decidio-authorize", lambda: _authorize_dict(guard, ctx))
+    if auth["decision"] == "block":
+        raise DecidioBlocked(auth.get("reason") or "blocked by policy", auth["decisionId"])
+    if auth["decision"] == "route":
+        # durably suspend until the resume event for THIS decision arrives (process may die)
+        ev = await step.wait_for_event(
+            "decidio-await-approval",
+            event=DECIDIO_RESUME_EVENT,
+            timeout=timeout,
+            if_exp=f'async.data.decisionId == "{auth["decisionId"]}"',
+        )
+        if ev is None:
+            raise TimeoutError(f"decidio approval timed out ({auth['decisionId']})")
+        data = getattr(ev, "data", None) or (ev.get("data") if isinstance(ev, dict) else {}) or {}
+        verdict = data.get("verdict")
+        if verdict == "rejected":
+            raise DecidioRejected("rejected by approver", auth["decisionId"])
+        if verdict not in ("approved", "auto_approved"):
+            raise DecidioBlocked("not approved", auth["decisionId"])
+    result = await step.run("agent-action", run)
+    await step.run("decidio-confirm", lambda: confirm(guard, auth["decisionId"], result))
+    return result
+
+
+def resume_event(webhook_body: dict) -> dict:
+    """Translate Decidio's signed resume webhook into the Inngest event payload to send
+    (`await inngest_client.send(Event(name=..., data=...))`) — wakes the suspended gate."""
+    return {
+        "name": DECIDIO_RESUME_EVENT,
+        "data": {
+            "decisionId": str(webhook_body.get("decisionId")),
+            "verdict": webhook_body.get("verdict"),
+            "reason": webhook_body.get("reason"),
+        },
+    }

decidio/adapters/langgraph.py

@@ -0,0 +1,62 @@
+"""LangGraph adapter — durable suspend via the engine's native `interrupt()`.
+
+`interrupt()` is contextvar-based (it finds the running graph itself), so the Decidio
+gate fits LangGraph as a true drop-in: inside a node, `guard.protect(fn, describe,
+adapter="langgraph")(...)` authorizes; on `route` it calls `interrupt(...)`, which
+durably pauses the graph (the checkpointer persists state — the process can die). When
+Decidio's approval webhook resumes the graph with `Command(resume={"verdict": ...})`,
+`interrupt()` returns that payload and the node runs the agent's own action + confirms.
+
+Decidio is the approval system; the host bridges its webhook to the graph resume:
+    cmd = decidio_resume_command(webhook_body)         # build the Command
+    graph.invoke(cmd, config={"configurable": {"thread_id": thread_for(decisionId)}})
+(The host maps decisionId → thread_id; that mapping is host state, like any LangGraph
+human-in-the-loop resume.)
+"""
+from __future__ import annotations
+
+import inspect
+
+from ..resume import _complete
+
+from typing import Any, Callable
+
+from langgraph.types import Command, interrupt  # verified primitive
+
+from .._client import post as _post  # noqa: F401  (kept for parity; gate uses _common)
+from ..errors import DecidioBlocked, DecidioRejected
+from ._common import authorize, confirm
+
+
+def gate(guard: Any, ctx: dict, run: Callable[[], Any]) -> Any:
+    """Run `run()` behind the Decidio gate inside a LangGraph node."""
+    auth = authorize(guard, ctx)
+    if auth.decision == "block":
+        raise DecidioBlocked(auth.reason or "blocked by policy", auth.decision_id)
+    if auth.decision == "route":
+        # Durable pause. On resume, interrupt() returns the Command(resume=...) payload.
+        resumed = interrupt({"decidio": {
+            "decisionId": auth.decision_id, "action": ctx["action"],
+            "amount": ctx["amount"], "scope": ctx.get("scope"),
+        }})
+        verdict = resumed.get("verdict") if isinstance(resumed, dict) else resumed
+        if verdict == "rejected":
+            raise DecidioRejected(((resumed or {}).get("reason") if isinstance(resumed, dict) else None) or "rejected by approver", auth.decision_id)
+        if verdict not in ("approved", "auto_approved"):
+            raise DecidioBlocked("not approved", auth.decision_id)
+    result = run()
+    # The core wrapper became async-aware, but adapters are dispatched BEFORE that branch, so
+    # this path kept the original bug: an `async def` action returned a coroutine, which was
+    # then handed to confirm() and failed json.dumps — printing "action succeeded" for an action
+    # that had not started, and stranding the receipt below application_confirmed. temporal.py
+    # already awaited; langgraph did not. Every equivalent path, not just the one that was reported.
+    if inspect.isawaitable(result):
+        result = _complete(result)
+    confirm(guard, auth.decision_id, result)
+    return result
+
+
+def decidio_resume_command(webhook_body: dict) -> Command:
+    """Translate Decidio's signed resume webhook into the LangGraph resume Command.
+    Pass it to graph.invoke/stream with the paused run's thread_id."""
+    return Command(resume={"verdict": webhook_body.get("verdict"), "reason": webhook_body.get("reason")})

decidio/adapters/openai.py

@@ -0,0 +1,62 @@
+"""OpenAI Agents SDK adapter — gate tool-approval interruptions through Decidio, with
+durable suspend via the SDK's native RunState serialization.
+
+The OpenAI Agents loop surfaces tool-approval interruptions on the RunState
+(`state.get_interruptions()` → ToolApprovalItem); you `state.approve(item)` /
+`state.reject(item)` then resume with `Runner.run(agent, state)`. RunState serializes
+(`state.to_string()` / `RunState.from_string(agent, s)`), which is the durability: park
+the serialized state agent-side on `route`, resume on Decidio's approval.
+
+    state = result.to_state()
+    resolved, pending = decidio.adapters.openai.gate_interruptions(guard, state, describe)
+    if pending:                         # a human must decide — persist + suspend
+        store.put(decisionId, state.to_string()); return  # process may exit
+    result = await Runner.run(agent, state)   # all resolved → resume the run
+    # on Decidio approval webhook (per pending item):
+    #   state = RunState.from_string(agent, parked); decidio.adapters.openai.apply_resume(state, item, verdict)
+    #   result = await Runner.run(agent, state)
+
+`describe(item)` maps a ToolApprovalItem → {"action","amount","scope"} (e.g.
+lambda i: {"action": i.tool_name, "amount": json.loads(i.arguments).get("amount", 0)}).
+This adapter is duck-typed on the state/item (no hard `agents` import) so it stays thin.
+"""
+from __future__ import annotations
+
+from typing import Any, Callable, List, Optional, Tuple
+
+from ._common import authorize
+
+
+def gate_interruptions(
+    guard: Any,
+    state: Any,
+    describe: Callable[[Any], dict],
+) -> Tuple[List[Tuple[Any, str, str]], List[Tuple[Any, str]]]:
+    """Ask Decidio for each pending tool-approval on `state`.
+    proceed → state.approve(item); block → state.reject(item); route → left for a human
+    (durable). Returns (resolved, pending):
+      resolved = [(item, verdict, decisionId)]  applied to the state now
+      pending  = [(item, decisionId)]           awaiting a human decision via Decidio
+    If `pending` is non-empty, persist state.to_string() and suspend; resume per
+    `apply_resume` when Decidio approves."""
+    resolved: List[Tuple[Any, str, str]] = []
+    pending: List[Tuple[Any, str]] = []
+    for item in state.get_interruptions():
+        auth = authorize(guard, describe(item))
+        if auth.decision == "proceed":
+            state.approve(item)
+            resolved.append((item, "approved", auth.decision_id))
+        elif auth.decision == "block":
+            state.reject(item, rejection_message=auth.reason or "blocked by policy")
+            resolved.append((item, "blocked", auth.decision_id))
+        else:  # route → a human decides via Decidio; the host parks + resumes
+            pending.append((item, auth.decision_id))
+    return resolved, pending
+
+
+def apply_resume(state: Any, item: Any, verdict: str, *, rejection_message: Optional[str] = None) -> None:
+    """Apply a Decidio verdict to a resumed RunState (after RunState.from_string)."""
+    if verdict in ("approved", "auto_approved"):
+        state.approve(item)
+    else:
+        state.reject(item, rejection_message=rejection_message or "rejected by approver")

decidio/adapters/temporal.py

@@ -0,0 +1,80 @@
+"""Temporal adapter — durable suspend via the engine's native `workflow.wait_condition`
+plus a Decidio resume signal. Temporal gives the strongest durability (the workflow
+survives worker restarts for days); the agent's action runs on resume.
+
+Compose `DecidioSignalState` into your workflow and expose a signal that records the
+verdict; `gate()` authorizes (via an activity), waits on the signal, then runs + confirms:
+
+    class MyWorkflow(DecidioSignalState):
+        @workflow.signal
+        def decidio_resume(self, decision_id: str, verdict: str, reason: str | None = None):
+            self.decidio_set(decision_id, verdict, reason)
+        @workflow.run
+        async def run(self, o):
+            return await decidio.adapters.temporal.gate(self, guard, ctx, run=lambda: create_opp(o))
+
+Decidio's webhook bridges to `client.get_workflow_handle(wf_id).signal(MyWorkflow.decidio_resume, decisionId, verdict)`.
+Run authorize/confirm as ACTIVITIES (HTTP side effects belong in activities, not the
+workflow) — `_authorize_activity`/`_confirm_activity` are provided for that.
+"""
+from __future__ import annotations
+
+import inspect
+from typing import Any, Callable, Dict, Optional, Tuple
+
+from ..errors import DecidioBlocked, DecidioRejected
+from ._common import authorize, confirm
+
+
+class DecidioSignalState:
+    """Mixin: a per-decision verdict store a Temporal signal handler writes to."""
+
+    def __init__(self) -> None:
+        self._decidio_verdicts: Dict[str, Tuple[str, Optional[str]]] = {}
+
+    def decidio_set(self, decision_id: str, verdict: str, reason: Optional[str] = None) -> None:
+        self._decidio_verdicts[decision_id] = (verdict, reason)
+
+    def decidio_resolved(self, decision_id: str) -> bool:
+        return decision_id in self._decidio_verdicts
+
+
+# Activity bodies (register these with your worker; they hold the HTTP side effects).
+def _authorize_activity(guard: Any, ctx: dict) -> dict:
+    a = authorize(guard, ctx)
+    return {"decision": a.decision, "decisionId": a.decision_id, "receiptId": a.receipt_id, "reason": a.reason}
+
+
+def _confirm_activity(guard: Any, decision_id: str, result: Any) -> None:
+    confirm(guard, decision_id, result)
+
+
+async def gate(
+    wf: DecidioSignalState,
+    guard: Any,
+    ctx: dict,
+    run: Callable[[], Any],
+    *,
+    authorize_fn: Optional[Callable[[], dict]] = None,
+    confirm_fn: Optional[Callable[[str, Any], None]] = None,
+) -> Any:
+    """Gate inside a Temporal workflow. `authorize_fn`/`confirm_fn` let you route the
+    HTTP through activities (recommended); they default to direct calls for tests."""
+    from temporalio import workflow  # lazy: only needed inside a workflow runtime
+
+    auth = (authorize_fn or (lambda: _authorize_activity(guard, ctx)))()
+    if auth["decision"] == "block":
+        raise DecidioBlocked(auth.get("reason") or "blocked by policy", auth["decisionId"])
+    if auth["decision"] == "route":
+        decision_id = auth["decisionId"]
+        await workflow.wait_condition(lambda: wf.decidio_resolved(decision_id))
+        verdict, reason = wf._decidio_verdicts[decision_id]
+        if verdict == "rejected":
+            raise DecidioRejected(reason or "rejected by approver", decision_id)
+        if verdict not in ("approved", "auto_approved"):
+            raise DecidioBlocked("not approved", decision_id)
+    result = run()
+    if inspect.isawaitable(result):   # the agent's action may be async — await it (TS awaits too)
+        result = await result
+    (confirm_fn or (lambda did, r: _confirm_activity(guard, did, r)))(auth["decisionId"], result)
+    return result