riskkernel 0.3.0__py3-none-any.whl

riskkernel/__init__.py

@@ -0,0 +1,59 @@
+"""RiskKernel Python SDK — Surface 2 (deep control).
+
+A thin client over the self-hosted RiskKernel daemon. The Go core makes every
+deterministic decision (budgets, halts, approval policy); this package just makes
+governed runs ergonomic from Python.
+
+Quickstart::
+
+    import riskkernel as rk
+
+    rt = rk.Runtime(base_url="http://localhost:7070")
+    with rt.governed_run(name="research", budget=rt.budget(dollars=1.00, loops=20)) as run:
+        cfg = run.proxy_config()   # route your LLM client through the governing proxy
+        for _ in range(100):
+            run.step()             # raises BudgetExceeded when loops/time run out
+            ...                    # your agent reasoning + tool calls
+            run.checkpoint("after-step", {"messages": messages})
+"""
+
+from .client import RiskKernel
+from .errors import (
+    APIError,
+    ApprovalDenied,
+    ApprovalTimeout,
+    BudgetExceeded,
+    RiskKernelError,
+)
+from .approval import ApprovalGate, governed_tool
+from .runtime import (
+    Budget,
+    Decision,
+    Run,
+    Runtime,
+    configure,
+    current_run,
+    default_runtime,
+    governed_run,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "RiskKernel",
+    "Runtime",
+    "Run",
+    "Budget",
+    "Decision",
+    "ApprovalGate",
+    "governed_run",
+    "governed_tool",
+    "current_run",
+    "configure",
+    "default_runtime",
+    "RiskKernelError",
+    "APIError",
+    "BudgetExceeded",
+    "ApprovalDenied",
+    "ApprovalTimeout",
+]

riskkernel/adapters/__init__.py

@@ -0,0 +1,8 @@
+"""Framework adapters that bind a RiskKernel governed run to popular agent
+frameworks. Each adapter lazily imports its framework, so the core SDK has no
+third-party dependencies and you only pay for what you use.
+
+- ``langchain``      — a CallbackHandler (loop/time enforcement per LLM call).
+- ``claude_agent``   — a PreToolUse hook for the Claude Agent SDK (approval gate).
+- ``openai_agents``  — RunHooks for the OpenAI Agents SDK (steps + approval gate).
+"""

riskkernel/adapters/claude_agent.py

@@ -0,0 +1,75 @@
+"""Claude Agent SDK adapter: a PreToolUse hook that routes side-effecting tool
+calls through the RiskKernel approval gate. Maps cleanly to the Claude Agent SDK's
+permission model (``permissionDecision: "deny"`` blocks a tool).
+
+    from riskkernel.adapters.claude_agent import make_pre_tool_use_hook
+    hook = make_pre_tool_use_hook(run, side_effect_for={"Bash": "exec", "Write": "write"})
+    # register `hook` as your PreToolUse hook in the Claude Agent SDK options.
+
+The hook signature follows the Claude Agent SDK: it receives the hook input
+(containing the tool name and input) and returns a decision dict. Because SDK
+versions differ slightly, the returned shape is the documented
+``hookSpecificOutput`` / ``permissionDecision`` form; adjust if your version
+differs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional
+
+from ..runtime import Run
+
+
+def make_pre_tool_use_hook(
+    run: Run,
+    side_effect_for: Optional[Dict[str, str]] = None,
+    default_side_effect: str = "write",
+    timeout: Optional[float] = None,
+) -> Callable[..., dict]:
+    """Build a PreToolUse hook bound to a governed run.
+
+    Args:
+        run: the governed Run.
+        side_effect_for: map of tool name -> side-effect label. Tools not listed
+            use ``default_side_effect``. A tool mapped to "" (empty) is treated as
+            read-only and never gated.
+        default_side_effect: side effect for unlisted tools.
+        timeout: max seconds to await a human decision.
+    """
+    side_effect_for = side_effect_for or {}
+
+    def hook(input_data: Any = None, *args: Any, **kwargs: Any) -> dict:
+        tool_name, tool_input = _extract(input_data, kwargs)
+        side_effect = side_effect_for.get(tool_name, default_side_effect)
+        decision = run.approve(
+            tool_name or "tool", side_effect=side_effect,
+            arguments={"input": _stringify(tool_input)}, timeout=timeout,
+        )
+        if decision.approved:
+            return {}  # allow (no decision == proceed)
+        return {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": decision.reason or "denied via RiskKernel approval gate",
+            }
+        }
+
+    return hook
+
+
+def _extract(input_data: Any, kwargs: dict):
+    """Pull tool name + input out of the hook payload across SDK shapes."""
+    data = input_data if isinstance(input_data, dict) else kwargs
+    name = data.get("tool_name") or data.get("toolName") or data.get("name") or ""
+    tinput = data.get("tool_input") or data.get("toolInput") or data.get("input")
+    return name, tinput
+
+
+def _stringify(v: Any) -> Any:
+    try:
+        import json
+        json.dumps(v)
+        return v
+    except Exception:
+        return repr(v)

riskkernel/adapters/langchain.py

@@ -0,0 +1,82 @@
+"""LangChain / LangGraph adapter: a callback handler that enforces a governed
+run's loop and time budgets, ticking one step per LLM call. Point your LangChain
+LLM at the governing proxy (``run.proxy_config()``) for token/cost/budget metering;
+this handler adds the outer-loop enforcement the proxy can't see.
+
+    from riskkernel.adapters.langchain import RiskKernelCallbackHandler
+    handler = RiskKernelCallbackHandler(run)
+    llm.invoke(prompt, config={"callbacks": [handler]})
+
+A BudgetExceeded raised here propagates out of the LangChain call, halting the
+chain — exactly when the run is out of budget.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..approval import ApprovalGate
+from ..runtime import Run
+
+
+def _base_handler():
+    # Inherit the real base class when LangChain is installed (best integration);
+    # otherwise fall back to object so the module still imports.
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler  # type: ignore
+        return BaseCallbackHandler
+    except Exception:
+        try:
+            from langchain.callbacks.base import BaseCallbackHandler  # type: ignore
+            return BaseCallbackHandler
+        except Exception:
+            return object
+
+
+class RiskKernelCallbackHandler(_base_handler()):  # type: ignore[misc]
+    """Enforces loop/time budgets and (optionally) gates tools on approval.
+
+    Args:
+        run: the governed Run.
+        gate_tools: if True, every tool call must pass the approval gate.
+        tool_side_effect: side-effect label reported for gated tools.
+    """
+
+    # LangChain swallows exceptions raised inside a callback — it logs them and
+    # keeps running — UNLESS the handler sets raise_error=True. Without this, a
+    # BudgetExceeded (or ApprovalDenied) raised in a hook below would be silently
+    # dropped and the chain would keep spending past its budget. This single flag
+    # is what makes the deterministic halt actually stop the LangChain run.
+    raise_error = True
+
+    def __init__(self, run: Run, gate_tools: bool = False,
+                 tool_side_effect: str = "tool"):
+        self.run = run
+        self.gate_tools = gate_tools
+        self.tool_side_effect = tool_side_effect
+        self._gate = ApprovalGate(run)
+
+    # One LLM call == one governed step. Raises BudgetExceeded when spent.
+    def on_llm_start(self, serialized: Any, prompts: Any, **kwargs: Any) -> None:
+        self.run.step()
+
+    def on_chat_model_start(self, serialized: Any, messages: Any, **kwargs: Any) -> None:
+        self.run.step()
+
+    def on_tool_start(self, serialized: Any, input_str: Any, **kwargs: Any) -> None:
+        if not self.gate_tools:
+            return
+        name = ""
+        if isinstance(serialized, dict):
+            name = serialized.get("name", "")
+        self._gate.require(name or "tool", side_effect=self.tool_side_effect,
+                           arguments={"input": _stringify(input_str)})
+
+
+def _stringify(v: Any) -> Any:
+    try:
+        import json
+        json.dumps(v)
+        return v
+    except Exception:
+        return repr(v)

riskkernel/adapters/openai_agents.py

@@ -0,0 +1,49 @@
+"""OpenAI Agents SDK adapter: lifecycle hooks that tick a governed step per agent
+turn and gate tools through the approval gate.
+
+    from riskkernel.adapters.openai_agents import RiskKernelRunHooks
+    hooks = RiskKernelRunHooks(run, gate_tools=True)
+    await Runner.run(agent, input, hooks=hooks)
+
+The OpenAI Agents SDK calls ``on_agent_start``/``on_tool_start`` (async). We tick a
+step on each agent start (loop/time enforcement) and, when ``gate_tools`` is set,
+await approval before a tool runs — raising ApprovalDenied to block it.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from ..approval import ApprovalGate
+from ..runtime import Run
+
+
+def _base_hooks():
+    try:
+        from agents import RunHooks  # type: ignore  (openai-agents)
+        return RunHooks
+    except Exception:
+        return object
+
+
+class RiskKernelRunHooks(_base_hooks()):  # type: ignore[misc]
+    """RunHooks that bind a governed run to an OpenAI Agents run."""
+
+    def __init__(self, run: Run, gate_tools: bool = False,
+                 tool_side_effect: str = "tool", timeout: Optional[float] = None):
+        self.run = run
+        self.gate_tools = gate_tools
+        self.tool_side_effect = tool_side_effect
+        self.timeout = timeout
+        self._gate = ApprovalGate(run)
+
+    async def on_agent_start(self, context: Any = None, agent: Any = None, **kwargs: Any) -> None:
+        # One agent turn == one governed step (enforces loop/time budgets).
+        self.run.step()
+
+    async def on_tool_start(self, context: Any = None, agent: Any = None,
+                            tool: Any = None, **kwargs: Any) -> None:
+        if not self.gate_tools:
+            return
+        name = getattr(tool, "name", None) or str(tool)
+        self._gate.require(name, side_effect=self.tool_side_effect, timeout=self.timeout)

riskkernel/approval.py

@@ -0,0 +1,86 @@
+"""Human-in-the-loop approval helpers for the SDK."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable, Optional
+
+from .errors import ApprovalDenied, RiskKernelError
+from .runtime import Decision, Run, current_run
+
+
+class ApprovalGate:
+    """Gates side-effecting actions on human approval. Wraps a Run and asks the
+    daemon (deterministic policy) whether a call needs approval, then blocks until
+    a human resolves it.
+
+        gate = ApprovalGate(run)
+        if gate.allow("mcp://shell", side_effect="exec", arguments={"cmd": cmd}):
+            run_shell(cmd)
+    """
+
+    def __init__(self, run: Optional[Run] = None):
+        self._run = run
+
+    def _resolve_run(self) -> Run:
+        run = self._run or current_run()
+        if run is None:
+            raise RiskKernelError("ApprovalGate used outside a governed run")
+        return run
+
+    def decide(self, tool: str, side_effect: str = "", arguments: Optional[dict] = None,
+               step_index: int = 0, timeout: Optional[float] = None) -> Decision:
+        """Return the Decision (blocking until resolved). Does not raise on denial."""
+        return self._resolve_run().approve(
+            tool, side_effect=side_effect, arguments=arguments,
+            step_index=step_index, timeout=timeout,
+        )
+
+    def allow(self, tool: str, side_effect: str = "", arguments: Optional[dict] = None,
+              step_index: int = 0, timeout: Optional[float] = None) -> bool:
+        """Convenience boolean: True if approved."""
+        return self.decide(tool, side_effect, arguments, step_index, timeout).approved
+
+    def require(self, tool: str, side_effect: str = "", arguments: Optional[dict] = None,
+                step_index: int = 0, timeout: Optional[float] = None) -> None:
+        """Raise ApprovalDenied if not approved (use to guard before a side effect)."""
+        d = self.decide(tool, side_effect, arguments, step_index, timeout)
+        if not d.approved:
+            raise ApprovalDenied(tool, d.reason)
+
+
+def governed_tool(_fn: Optional[Callable] = None, *, tool: Optional[str] = None,
+                  side_effect: str = "write", timeout: Optional[float] = None):
+    """Decorator for a side-effecting tool function: before it runs, ask the
+    approval gate (under the current governed run). Raises ApprovalDenied if the
+    human says no.
+
+        @governed_tool(side_effect="write")
+        def write_file(path, content): ...
+    """
+
+    def decorate(fn: Callable) -> Callable:
+        tool_name = tool or fn.__name__
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            ApprovalGate().require(
+                tool_name, side_effect=side_effect,
+                arguments={"args": _safe(args), "kwargs": _safe(kwargs)},
+                timeout=timeout,
+            )
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorate(_fn) if _fn is not None else decorate
+
+
+def _safe(obj: Any) -> Any:
+    """Best-effort JSON-able rendering of call arguments for the approver to read."""
+    try:
+        import json
+        json.dumps(obj)
+        return obj
+    except Exception:
+        return repr(obj)

riskkernel/client.py

@@ -0,0 +1,153 @@
+"""Thin HTTP client for the RiskKernel daemon's /v1 API.
+
+Stdlib only (urllib) — no third-party dependencies, so ``pip install riskkernel``
+stays light and auditable. This client carries NO governance logic: the Go daemon
+makes every deterministic decision. The client just relays calls and surfaces the
+daemon's verdicts (e.g. a 402 becomes ``BudgetExceeded``).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Optional
+from urllib.parse import quote as _q
+
+from .errors import APIError, BudgetExceeded
+
+
+class RiskKernel:
+    """Client for a running RiskKernel daemon."""
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:7070",
+        token: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    # --- low-level ---
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None) -> Any:
+        url = self.base_url + path
+        data = None
+        headers = {"Accept": "application/json"}
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.token:
+            headers["Authorization"] = "Bearer " + self.token
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            payload = {}
+            try:
+                payload = json.loads(raw)
+            except Exception:
+                pass
+            code = payload.get("code", "")
+            message = payload.get("message", e.reason or "")
+            # 402 == the governor halted the run on a budget.
+            if e.code == 402:
+                raise BudgetExceeded(code, message) from None
+            raise APIError(e.code, code, message) from None
+        except urllib.error.URLError as e:
+            raise APIError(0, "connection_error",
+                           f"cannot reach daemon at {self.base_url}: {e.reason}") from None
+
+    # --- runs ---
+
+    def create_run(self, name: Optional[str] = None, budget: Optional[dict] = None,
+                   metadata: Optional[dict] = None) -> dict:
+        body: dict = {}
+        if name:
+            body["name"] = name
+        if budget:
+            body["budget"] = budget
+        if metadata:
+            body["metadata"] = metadata
+        return self._request("POST", "/v1/runs", body)
+
+    def get_run(self, run_id: str) -> dict:
+        return self._request("GET", f"/v1/runs/{run_id}")
+
+    def begin_step(self, run_id: str) -> int:
+        """Register a loop iteration. Raises BudgetExceeded (402) if the loop or
+        time budget is spent."""
+        out = self._request("POST", f"/v1/runs/{run_id}/steps", {})
+        return int(out.get("stepIndex", 0))
+
+    def checkpoint(self, run_id: str, name: str = "", payload: Optional[dict] = None) -> None:
+        self._request("POST", f"/v1/runs/{run_id}/checkpoints",
+                      {"name": name, "payload": payload or {}})
+
+    def latest_checkpoint(self, run_id: str) -> Optional[dict]:
+        try:
+            return self._request("GET", f"/v1/checkpoints/{run_id}")
+        except APIError as e:
+            if e.status == 404:
+                return None
+            raise
+
+    def cancel(self, run_id: str, reason: str = "") -> dict:
+        return self._request("POST", f"/v1/runs/{run_id}/cancel", {"reason": reason})
+
+    # --- approvals ---
+
+    def request_approval(self, run_id: str, tool: str, side_effect: str = "",
+                         arguments: Optional[dict] = None, step_index: int = 0) -> dict:
+        """Request approval for a (possibly side-effecting) tool call. Returns a
+        dict with ``status``: ``approved`` (allowed by policy) or ``pending``
+        (a human must decide; poll ``get_approval``)."""
+        return self._request("POST", f"/v1/runs/{run_id}/approvals", {
+            "tool": tool, "sideEffect": side_effect,
+            "arguments": arguments or {}, "stepIndex": step_index,
+        })
+
+    def get_approval(self, approval_id: str) -> dict:
+        return self._request("GET", f"/v1/approvals/{approval_id}")
+
+    def resolve_approval(self, run_id: str, approval_id: str, approve: bool,
+                         reason: str = "", decided_by: str = "sdk") -> dict:
+        return self._request("POST", f"/v1/runs/{run_id}/approve", {
+            "approvalId": approval_id,
+            "decision": "approve" if approve else "deny",
+            "reason": reason, "decidedBy": decided_by,
+        })
+
+    # --- git-native memory ---
+
+    def list_memory(self, namespace: str = "", query: str = "") -> list:
+        """List (or keyword-search) the user-owned markdown/YAML memory entries."""
+        q = []
+        if namespace:
+            q.append("namespace=" + _q(namespace))
+        if query:
+            q.append("q=" + _q(query))
+        path = "/v1/memory" + ("?" + "&".join(q) if q else "")
+        return self._request("GET", path)
+
+    def read_memory(self, name: str, namespace: str = "") -> dict:
+        """Read one memory file's content + metadata."""
+        path = f"/v1/memory/entry?name={_q(name)}"
+        if namespace:
+            path += "&namespace=" + _q(namespace)
+        return self._request("GET", path)
+
+    def list_facts(self, namespace: str = "") -> list:
+        path = "/v1/memory/facts" + ("?namespace=" + _q(namespace) if namespace else "")
+        return self._request("GET", path)
+
+    def put_fact(self, namespace: str, key: str, value: str, run_id: str = "") -> dict:
+        return self._request("PUT", "/v1/memory/facts", {
+            "namespace": namespace, "key": key, "value": value, "runId": run_id,
+        })

riskkernel/errors.py

@@ -0,0 +1,40 @@
+"""Exceptions raised by the RiskKernel SDK."""
+
+from __future__ import annotations
+
+
+class RiskKernelError(Exception):
+    """Base class for all SDK errors."""
+
+
+class APIError(RiskKernelError):
+    """The daemon returned an unexpected (non-2xx) response."""
+
+    def __init__(self, status: int, code: str = "", message: str = ""):
+        self.status = status
+        self.code = code
+        self.message = message
+        super().__init__(f"riskkernel API error {status} {code}: {message}")
+
+
+class BudgetExceeded(RiskKernelError):
+    """A governed run hit one of its hard budgets (the deterministic governor
+    halted it). ``reason`` is the machine-readable HaltReason, e.g.
+    ``token_budget_exceeded`` or ``loop_budget_exceeded``."""
+
+    def __init__(self, reason: str, message: str = ""):
+        self.reason = reason
+        super().__init__(message or f"run halted: {reason}")
+
+
+class ApprovalDenied(RiskKernelError):
+    """A human denied a side-effecting tool call gated by the approval gate."""
+
+    def __init__(self, tool: str, reason: str = ""):
+        self.tool = tool
+        self.reason = reason
+        super().__init__(f"approval denied for {tool}" + (f": {reason}" if reason else ""))
+
+
+class ApprovalTimeout(RiskKernelError):
+    """No human resolved a pending approval within the configured timeout."""

riskkernel/runtime.py

@@ -0,0 +1,226 @@
+"""High-level governed-run ergonomics over the thin client.
+
+The runtime is still thin: budgets, loop/time enforcement, checkpoints, and
+approval decisions all happen in the Go daemon. This module just makes them
+pleasant to use from Python (context managers, decorators, a current-run var).
+"""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+import os
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+
+from .client import RiskKernel
+from .errors import ApprovalTimeout
+
+# The run currently in scope (set by governed_run), so @governed_tool and
+# checkpoint() can find it without threading it through every call.
+_current_run: contextvars.ContextVar[Optional["Run"]] = contextvars.ContextVar(
+    "riskkernel_current_run", default=None
+)
+
+
+def current_run() -> Optional["Run"]:
+    """Return the governed run currently in scope, or None."""
+    return _current_run.get()
+
+
+@dataclass
+class Budget:
+    """Hard per-run limits. Any field left None is unlimited for that dimension."""
+
+    tokens: Optional[int] = None
+    dollars: Optional[float] = None
+    loops: Optional[int] = None
+    seconds: Optional[int] = None
+
+    def to_dict(self) -> dict:
+        out: dict = {}
+        if self.tokens is not None:
+            out["tokens"] = self.tokens
+        if self.dollars is not None:
+            out["dollars"] = self.dollars
+        if self.loops is not None:
+            out["loops"] = self.loops
+        if self.seconds is not None:
+            out["seconds"] = self.seconds
+        return out
+
+
+@dataclass
+class Decision:
+    approved: bool
+    required: bool = True
+    reason: str = ""
+    by: str = ""
+
+
+class Run:
+    """A governed run bound to a daemon run id."""
+
+    def __init__(self, client: RiskKernel, data: dict,
+                 poll_interval: float = 2.0, timeout: Optional[float] = None):
+        self._client = client
+        self._poll = poll_interval
+        self._timeout = timeout
+        self.id: str = data["id"]
+        self.data = data
+
+    def step(self) -> int:
+        """Register a loop iteration; raises BudgetExceeded if loop/time budget is spent."""
+        return self._client.begin_step(self.id)
+
+    def checkpoint(self, name: str = "", payload: Optional[dict] = None) -> None:
+        self._client.checkpoint(self.id, name, payload)
+
+    def latest_checkpoint(self) -> Optional[dict]:
+        return self._client.latest_checkpoint(self.id)
+
+    def cancel(self, reason: str = "") -> dict:
+        return self._client.cancel(self.id, reason)
+
+    def status(self) -> dict:
+        return self._client.get_run(self.id)
+
+    def proxy_config(self) -> dict:
+        """Config for routing this run's model calls through the governing proxy.
+        Point your LLM client's base URL here and send the header so every call is
+        metered, priced, and budget-enforced under this run."""
+        return {
+            "base_url": self._client.base_url + "/v1",
+            "headers": {"X-RiskKernel-Run-Id": self.id},
+        }
+
+    def approve(self, tool: str, side_effect: str = "", arguments: Optional[dict] = None,
+                step_index: int = 0, poll_interval: Optional[float] = None,
+                timeout: Optional[float] = None) -> Decision:
+        """Request approval for a tool call, blocking (polling) until a human
+        resolves it. Returns a Decision; raises ApprovalTimeout if none arrives."""
+        res = self._client.request_approval(self.id, tool, side_effect, arguments, step_index)
+        if res.get("status") == "approved":
+            return Decision(True, bool(res.get("required", True)))
+        approval_id = res["id"]
+        interval = poll_interval if poll_interval is not None else self._poll
+        limit = timeout if timeout is not None else self._timeout
+        deadline = (time.monotonic() + limit) if limit is not None else None
+        while True:
+            a = self._client.get_approval(approval_id)
+            st = a.get("status")
+            if st == "approved":
+                return Decision(True, True, a.get("reason", ""), a.get("decidedBy", ""))
+            if st == "denied":
+                return Decision(False, True, a.get("reason", ""), a.get("decidedBy", ""))
+            if deadline is not None and time.monotonic() > deadline:
+                raise ApprovalTimeout(f"no decision for approval {approval_id} within {limit}s")
+            time.sleep(interval)
+
+
+class Runtime:
+    """Entry point: holds a client and default approval-polling settings."""
+
+    def __init__(self, client: Optional[RiskKernel] = None,
+                 base_url: str = "http://localhost:7070", token: Optional[str] = None,
+                 approval_poll_interval: float = 2.0,
+                 approval_timeout: Optional[float] = None):
+        self.client = client or RiskKernel(base_url, token)
+        self._poll = approval_poll_interval
+        self._timeout = approval_timeout
+
+    def budget(self, tokens: Optional[int] = None, dollars: Optional[float] = None,
+               loops: Optional[int] = None, seconds: Optional[int] = None) -> Budget:
+        return Budget(tokens, dollars, loops, seconds)
+
+    @contextmanager
+    def governed_run(self, name: Optional[str] = None,
+                     budget: Optional[Budget | dict] = None,
+                     metadata: Optional[dict] = None, cancel_on_error: bool = True):
+        """Context manager that opens a governed run, sets it as the current run,
+        and cancels it if the body raises (unless cancel_on_error=False)."""
+        b = budget.to_dict() if isinstance(budget, Budget) else budget
+        data = self.client.create_run(name=name, budget=b, metadata=metadata)
+        run = Run(self.client, data, self._poll, self._timeout)
+        token = _current_run.set(run)
+        try:
+            yield run
+        except Exception:
+            if cancel_on_error:
+                try:
+                    run.cancel("error")
+                except Exception:
+                    pass
+            raise
+        finally:
+            _current_run.reset(token)
+
+    @contextmanager
+    def resume_run(self, run_id: str):
+        """Attach to an existing governed run by id — the resume path after a crash.
+
+        Unlike governed_run, this neither creates nor cancels the run: the daemon
+        reloads non-terminal runs on restart with the budget and usage they had
+        already spent, so enforcement continues without re-spending. Fetch
+        ``run.latest_checkpoint()`` to pick your work back up where it left off::
+
+            with rt.resume_run(run_id) as run:
+                cp = run.latest_checkpoint()
+                start = cp["payload"]["cursor"] if cp else 0
+                for i in range(start, total):
+                    run.step()                       # counts against the SAME budget
+                    ...
+                    run.checkpoint("step", {"cursor": i + 1})
+
+        Raises APIError(404) if the run id is unknown.
+        """
+        data = self.client.get_run(run_id)
+        run = Run(self.client, data, self._poll, self._timeout)
+        token = _current_run.set(run)
+        try:
+            yield run
+        finally:
+            _current_run.reset(token)
+
+
+# Module-level default runtime, configured from the environment, for the
+# decorator/convenience API.
+_default_runtime: Optional[Runtime] = None
+
+
+def default_runtime() -> Runtime:
+    global _default_runtime
+    if _default_runtime is None:
+        _default_runtime = Runtime(
+            base_url=os.environ.get("RISKKERNEL_BASE_URL", "http://localhost:7070"),
+            token=os.environ.get("RISKKERNEL_API_TOKEN"),
+        )
+    return _default_runtime
+
+
+def configure(runtime: Runtime) -> None:
+    """Override the module-level default runtime (used by the decorators)."""
+    global _default_runtime
+    _default_runtime = runtime
+
+
+def governed_run(_fn: Optional[Callable] = None, *, name: Optional[str] = None,
+                 budget: Optional[Budget | dict] = None, runtime: Optional[Runtime] = None):
+    """Decorator: run the wrapped function inside a governed run. The run is
+    available via current_run() (and passed as the ``run`` kwarg if the function
+    declares one)."""
+
+    def decorate(fn: Callable) -> Callable:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            rt = runtime or default_runtime()
+            run_name = name or fn.__name__
+            with rt.governed_run(name=run_name, budget=budget) as run:
+                if "run" in fn.__code__.co_varnames and "run" not in kwargs:
+                    kwargs["run"] = run
+                return fn(*args, **kwargs)
+        return wrapper
+
+    return decorate(_fn) if _fn is not None else decorate

riskkernel-0.3.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: riskkernel
+Version: 0.3.0
+Summary: Thin Python client for the RiskKernel reliability runtime (Surface 2).
+Project-URL: Homepage, https://github.com/prashar32/riskkernel
+Project-URL: Source, https://github.com/prashar32/riskkernel
+Author: Adarsh Prashar
+License-Expression: Apache-2.0
+Keywords: agents,budget,governance,guardrails,llm,reliability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# riskkernel (Python SDK)
+
+The Python SDK for [RiskKernel](https://github.com/prashar32/riskkernel) — **Surface 2**, deep control over a governed agent run.
+
+It is a **thin client** over the self-hosted RiskKernel daemon. Every deterministic
+decision — budgets, loop/time halts, approval policy — happens in the Go core. The
+SDK just makes governed runs ergonomic from Python. **Core install is stdlib-only**
+(no third-party dependencies).
+
+```bash
+pip install riskkernel
+```
+
+## Quickstart
+
+```python
+import riskkernel as rk
+
+rt = rk.Runtime(base_url="http://localhost:7070")  # your daemon
+
+with rt.governed_run(name="research",
+                     budget=rt.budget(dollars=1.00, loops=20, seconds=300)) as run:
+    # Route your LLM client through the governing proxy so every model call is
+    # metered, priced, and budget-enforced under this run:
+    cfg = run.proxy_config()
+    #   cfg["base_url"]  -> http://localhost:7070/v1
+    #   cfg["headers"]   -> {"X-RiskKernel-Run-Id": "<run id>"}
+
+    for _ in range(100):
+        run.step()                      # raises rk.BudgetExceeded when loops/time run out
+        # ... your agent reasoning + tool calls ...
+        run.checkpoint("after-step", {"messages": messages})
+```
+
+When the governor halts the run (token / dollar / loop / time budget), the next
+`run.step()` — or a proxied model call — raises `rk.BudgetExceeded`.
+
+## Resume after a crash
+
+The daemon reloads non-terminal runs on restart with the budget and usage they had
+already spent, so a `SIGKILL`'d run keeps enforcing without re-spending. Reattach to
+it by id with `resume_run` and pick your work back up from the last checkpoint:
+
+```python
+with rt.resume_run(run_id) as run:          # attaches; never creates or cancels
+    cp = run.latest_checkpoint()            # the state you saved before the crash
+    start = cp["payload"]["cursor"] if cp else 0
+    for i in range(start, total):           # skip the steps you already paid for
+        run.step()                          # counts against the SAME budget
+        # ... your work ...
+        run.checkpoint("step", {"cursor": i + 1})
+```
+
+The run resumes against whatever budget it had left, so it can't overspend by
+restarting — `run.step()` still raises `rk.BudgetExceeded` at the original ceiling.
+
+## Human-in-the-loop tools
+
+Gate side-effecting tools on human approval (the daemon's policy decides what needs
+it; the call blocks until a human resolves it via CLI / web / webhook):
+
+```python
+from riskkernel import governed_tool, ApprovalGate
+
+@governed_tool(side_effect="write")
+def write_file(path, content):
+    ...                                  # only runs if approved; else rk.ApprovalDenied
+
+# or explicitly:
+gate = ApprovalGate(run)
+if gate.allow("mcp://shell", side_effect="exec", arguments={"cmd": cmd}):
+    run_shell(cmd)
+```
+
+## Framework adapters
+
+Lazy-imported, so you only pay for what you use:
+
+```python
+# LangChain / LangGraph — enforces loop/time budgets per LLM call
+from riskkernel.adapters.langchain import RiskKernelCallbackHandler
+llm.invoke(prompt, config={"callbacks": [RiskKernelCallbackHandler(run)]})
+
+# Claude Agent SDK — PreToolUse approval hook
+from riskkernel.adapters.claude_agent import make_pre_tool_use_hook
+hook = make_pre_tool_use_hook(run, side_effect_for={"Bash": "exec", "Write": "write"})
+
+# OpenAI Agents SDK — RunHooks (steps + tool approval)
+from riskkernel.adapters.openai_agents import RiskKernelRunHooks
+hooks = RiskKernelRunHooks(run, gate_tools=True)
+```
+
+## Configuration
+
+`Runtime(base_url=..., token=...)`, or the env vars `RISKKERNEL_BASE_URL` and
+`RISKKERNEL_API_TOKEN` (used by the decorator/convenience API and `default_runtime()`).
+
+## License
+
+Apache-2.0.

riskkernel-0.3.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+riskkernel/__init__.py,sha256=Kco_JE7sEnJHttf5p88N2QncDmZ6q4WlJki6yZwFu2k,1466
+riskkernel/approval.py,sha256=yN9_hgIgJ5D_23h73kOXffegKELadbsTle4cDcJewJs,3203
+riskkernel/client.py,sha256=T5F2yblkdjwG4sTfp0F-6ilNOlIy_QOhzuMtYMW4Ye4,6006
+riskkernel/errors.py,sha256=8SLENoCO4we60t1-cw_zJKdSmSCQCAPwZuF0d0jCRKk,1331
+riskkernel/runtime.py,sha256=tcqsFlX6SatMAd0yKswQ1iWLgjup3kkAzEiVEODHPDI,8781
+riskkernel/adapters/__init__.py,sha256=AMTzTVzuPfeKTJe9iqL4bvU7Ox_UfLaIXsI6ZKYRcoM,469
+riskkernel/adapters/claude_agent.py,sha256=LbMeI1TEVC8I9p3dPW1lT8GiQZohwnIb4lAJsR89NVQ,2844
+riskkernel/adapters/langchain.py,sha256=9gnQgKHL9yP5tw7YUB1m5aJ-nyeTCMYgunF2M1sP3Q8,3119
+riskkernel/adapters/openai_agents.py,sha256=xUkbJO7cQkAjs0wnUWLkBVZPIvoXmzel90yTzj_OXcc,1843
+riskkernel-0.3.0.dist-info/METADATA,sha256=iH-iK4jyXc9u4blA5yMcHBjkbt2ccKuhcjO_RV1GFkE,4554
+riskkernel-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+riskkernel-0.3.0.dist-info/RECORD,,

riskkernel-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any