sakrit 0.0.1__py3-none-any.whl

sakrit/__about__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# 0.0.1 is the placeholder release that claims the PyPI name (roadmap: claim the
+# name independent of launch date). The real launch ships 0.1.0 with the three
+# stability promises in STABILITY.md in force.
+__version__ = "0.0.1"

sakrit/__init__.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Sakrit — exactly-once effects for AI agents.
+
+A thin, framework-agnostic layer that sits between an AI agent and the tools it
+calls, guaranteeing that every action with real-world consequences happens
+exactly once — even across crashes, resumes, retries, and parallel plans.
+
+Importing ``sakrit`` never imports a framework. Framework adapters live under
+``sakrit.adapters`` and are imported explicitly (e.g.
+``from sakrit.adapters.langgraph import LangGraphAdapter``).
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from sakrit.__about__ import __version__
+from sakrit.core import EffectDecl, Metrics, SqliteLedger, current_key
+from sakrit.engine import Sakrit
+
+__all__ = [
+    "EffectDecl",
+    "Metrics",
+    "Sakrit",
+    "SqliteLedger",
+    "__version__",
+    "current_key",
+    "safe",
+]
+
+_F = TypeVar("_F", bound=Callable[..., object])
+
+
+def safe(fn: _F) -> _F:
+    """Mark a callable as *reviewed and deliberately unguarded*.
+
+    Runtime-inert — returns ``fn`` unchanged, no wrapper, no cost. Its consumer is
+    ``sakrit doctor`` (static scan), which suppresses findings inside a function
+    decorated ``@sakrit.safe``. Use it to annotate-and-move-on after reviewing a
+    doctor finding that is genuinely non-consequential or guarded elsewhere; the
+    marker records that a human decided so.
+    """
+    return fn

sakrit/adapters/__init__.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Runtime adapters — the framework-facing surface.
+
+Each adapter sources a :class:`~sakrit.core.coordinate.Coordinate` from its
+runtime and satisfies :class:`~sakrit.core.adapter.RuntimeAdapter`. Framework
+imports belong *here*, never in ``sakrit.core``.
+
+:class:`~sakrit.adapters.fake.FakeAdapter` is the in-memory reference the whole
+core test suite runs against — see the FakeAdapter rule in ``docs/design.md`` §11.
+
+Shipped adapters (each behind its extra, each with a conformance gate):
+
+- ``sakrit.adapters.langgraph`` — ``call_site = checkpoint_ns`` (interrupt/resume).
+- ``sakrit.adapters.openai_agents`` — ``call_site = tool_call_id`` (RunState resume).
+
+**CrewAI: no adapter ships, deliberately.** Probed empirically at crewai 1.15.7:
+an adapter is only honest if the runtime exposes a step identity that is stable
+across its durable re-execution regime, and CrewAI exposes none ambiently —
+``Task.id`` is a fresh uuid per process and ``Crew.replay`` maps stored outputs
+to tasks *by index*, while the Flow contextvars (``current_flow_id``) carry a
+fresh per-kickoff execution id even when ``@persist`` restores state under the
+app-supplied durable id. A coordinate built on either would re-key on every
+restart — a guard that dedups nothing. Integrate CrewAI through the ladder
+instead: a business ``key=``, or ``with sk.step(name=..., scope=<the same
+durable id you give @persist>)``. Re-evaluate if CrewAI ever exposes its
+persisted state id ambiently.
+"""
+
+from sakrit.adapters.fake import FakeAdapter
+
+__all__ = ["FakeAdapter"]

sakrit/adapters/fake.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+"""FakeAdapter — the in-memory reference adapter.
+
+The FakeAdapter rule (``docs/design.md`` §11): the entire core test suite must pass
+against this adapter with **no framework imported**. If a core test needs
+LangGraph, the seam has leaked. It is therefore three things at once — the proof of
+framework-agnosticism, the hermetic test harness, and the reference the second real
+adapter is written against.
+
+It models a deterministic runtime: the test places the adapter at a logical step
+via :meth:`at`, and *re-placing* it at the same step (as a replay would) yields the
+same coordinate — so the core's dedup can be exercised without any real framework.
+"""
+
+from __future__ import annotations
+
+from sakrit.core.coordinate import Capabilities, Coordinate, Stability
+
+
+class FakeAdapter:
+    """A controllable, framework-free :class:`~sakrit.core.adapter.RuntimeAdapter`."""
+
+    def __init__(self, scope: str = "fake-run") -> None:
+        self._scope = scope
+        self._current: Coordinate | None = None
+        self._terminal = False
+
+    # --- test controls ----------------------------------------------------
+    def at(self, call_site: str, *, occurrence: int = 1, plan_epoch: int = 0) -> Coordinate:
+        """Place the adapter at a logical step (deterministic; re-callable to model
+        a replay re-executing the same step)."""
+        self._current = Coordinate(
+            scope=self._scope,
+            call_site=call_site.encode("utf-8"),
+            occurrence=occurrence,
+            plan_epoch=plan_epoch,
+        )
+        return self._current
+
+    def clear(self) -> None:
+        """Simulate being outside any step (``current_coordinate`` → ``None``)."""
+        self._current = None
+
+    def mark_terminal(self) -> None:
+        self._terminal = True
+
+    # --- RuntimeAdapter (v1 stable surface) -------------------------------
+    def current_coordinate(self) -> Coordinate | None:
+        return self._current
+
+    # --- ReservedAdapter (P5-4: semantics unfixed, not yet consumed) ------
+    def stability_domain(self) -> Stability:
+        # A deterministic in-memory runtime replays exactly; no re-planning.
+        return Stability.REPLAY | Stability.RETRY
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities.NONE
+
+    def scope_terminal(self, scope: str) -> bool:
+        return self._terminal

sakrit/adapters/langgraph.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The LangGraph adapter — ``call_site = checkpoint_ns``.
+
+Sources the coordinate from ``get_config()`` inside a node: ``scope = thread_id``,
+``call_site = checkpoint_ns`` (the ``"<node>:<deterministic-uuid>"`` the
+conformance test proved byte-stable across resume and unique per step —
+``docs/dev-notes/callsite-conformance.md``).
+
+**Loud refusals must reach the app, not the model (Fable C-5 / A-3 class).** If you guard
+inside a ``@tool`` run by a ``ToolNode``, mind ``handle_tool_errors``. On the supported
+LangGraph 1.x the **default is safe** — it swallows only ``ToolInvocationError`` (the model
+sent bad args) and re-raises everything else, so a :class:`~sakrit.core.errors.SakritError`
+halt (``DivergentRetry`` / ``AmbiguousOutcome``) propagates out of the graph to your app
+(conformance-gated). But ``handle_tool_errors=True`` (the old 0.x default, pervasive in
+tutorials) turns the halt into a model-visible *"Error: … Please fix your mistakes."* — the
+app never sees it and the model can mint a fresh tool call past the halt. So: **if you set
+``handle_tool_errors``, exclude ``SakritError``** — either
+``handle_tool_errors=(YourExpectedError, …)`` (a tuple that omits Sakrit's), or the callable
+:func:`sakrit_handle_tool_errors`, which re-raises a ``SakritError`` and stringifies the rest.
+
+Framework import lives here, never in ``sakrit.core``. Requires the ``langgraph``
+extra (``pip install sakrit[langgraph]``); import this module explicitly so plain
+``import sakrit`` stays framework-free.
+"""
+
+from __future__ import annotations
+
+from langgraph.config import get_config
+
+from sakrit.core.coordinate import Capabilities, Coordinate, Stability
+from sakrit.core.errors import SakritError
+
+# The LangGraph versions this adapter's call-site derivation is conformance-tested
+# against (research/repro/conformance.py). Outside this range, run the conformance
+# test before trusting positional keys — an ns-derivation change strands them.
+SUPPORTED_LANGGRAPH = (">=1.0", "<2.0")
+
+
+def sakrit_handle_tool_errors(exc: Exception) -> str:
+    """A ``ToolNode(handle_tool_errors=…)`` handler that lets Sakrit's loud refusals through.
+
+    LangGraph 1.x's *default* handler already re-raises a
+    :class:`~sakrit.core.errors.SakritError` (only ``ToolInvocationError`` is stringified), so
+    you need this only if you *also* want custom error text for ordinary tool errors while
+    keeping the halt loud (Fable C-5). It re-raises a ``SakritError`` — so ``DivergentRetry`` /
+    ``AmbiguousOutcome`` reaches the app instead of the model — and returns a model-visible
+    string for any other exception (the message a capable model may reasonably retry)."""
+    if isinstance(exc, SakritError):
+        raise exc
+    return f"Error: {exc}\n Please fix your mistakes."
+
+
+class LangGraphAdapter:
+    """A :class:`~sakrit.core.adapter.RuntimeAdapter` over LangGraph's checkpoints."""
+
+    def current_coordinate(self) -> Coordinate | None:
+        try:
+            conf = get_config().get("configurable", {})
+        except RuntimeError:
+            # Not inside a runnable context → fall to the coordinate ladder.
+            return None
+        ns = conf.get("checkpoint_ns")
+        thread = conf.get("thread_id")
+        if ns is None or thread is None:
+            return None
+        # A blank checkpoint_ns (or thread_id) cannot carry positional identity: an empty
+        # call_site is not unique per step, so *every* guarded call in the thread would
+        # collide onto one coordinate (scope + b"") — a silent swallow or DivergentRetry
+        # distinguished only by tool name (P4-3). Refuse it and fall to the ladder (an
+        # explicit key=, or a loud NoCoordinateError) rather than manufacture a colliding
+        # coordinate. No supported LangGraph (>=1.0,<2.0) emits "" inside a node — it is
+        # always "<node>:<uuid>", conformance-gated — but the guard is fail-safe if a version
+        # ever changes that (the signal to re-run the conformance suite before adopting it).
+        if not str(ns).strip() or not str(thread).strip():
+            return None
+        return Coordinate(scope=str(thread), call_site=str(ns).encode("utf-8"))
+
+    # --- ReservedAdapter (P5-4: semantics unfixed, not yet consumed). on_recovery was
+    # removed — the engine owns recovery (Sakrit.guard runs it once before the first claim),
+    # so "the adapter decides when recovery runs" was already false.
+    def stability_domain(self) -> Stability:
+        # Resume replays the recorded path; a fresh invocation that re-plans is R3
+        # (epochs, deferred). Within-run resume/retry is REPLAY|RETRY.
+        return Stability.REPLAY | Stability.RETRY
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities.NONE
+
+    def scope_terminal(self, scope: str) -> bool:
+        return False

sakrit/adapters/openai_agents.py

@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The OpenAI Agents SDK adapter — ``call_site = tool_call_id``, ``scope`` explicit.
+
+**Identity source (conformance-probed at openai-agents 0.18):** the model records each
+tool call with a ``tool_call_id`` *before* it executes; the SDK's durable interruption/
+resume regime (``RunState.to_string``/``from_string``, the HITL approval flow) re-dispatches
+the **recorded** call — same ``tool_call_id`` — on every resume of a saved state. Re-resuming
+a stale state (crash after resume, double approval) therefore re-executes the step at the
+*same* ``call_site``, which is what positional dedup needs. Distinct calls get distinct
+model-issued ids, so call sites are unique per step; a deliberate model repeat is a *new*
+call id, so it never collides.
+
+**Scope is explicit — and must be (Fable A-1/A-2).** The ``call_site`` is state-carried, but
+the SDK exposes **no state-carried retry domain at tool time**: ``ToolContext`` carries the
+call id, ``run_config`` and the user context — not the ``RunState``'s serialized trace or
+conversation id. The earlier build sourced scope from the *ambient* ``get_current_trace()``,
+which is controlled by the re-execution environment, not the recorded state: an app that
+resumes inside ``with trace(...)`` (the SDK's own recommended grouping) mints a fresh trace id
+per resume → a fresh scope → **zero dedup while looking guarded**. That is the "identity from
+ambient, not from state" category error the whole design forbids. So this adapter refuses to
+fabricate a scope: you pass a **stable run identity** you already persist alongside the
+``RunState`` string::
+
+    @function_tool(failure_error_function=None)          # see "Loud refusals" below
+    async def send_email(ctx: ToolContext, to: str) -> str:
+        with tool_boundary(ctx, scope=run_id):           # run_id: your stable, persisted id
+            return sk.guard(SEND_DECL, _send, kwargs={"to": to})
+
+Without a ``scope`` the adapter yields **no coordinate** (falls to the ladder) — so a guarded
+call must then carry an explicit business ``key=`` or it refuses loudly; it never silently
+dedups on a fabricated scope. ``call_site`` (the recorded call id) is only used *together*
+with an explicit scope.
+
+**Loud refusals must reach the app, not the model (Fable A-3).** ``function_tool``'s default
+error handler catches a raised exception and returns *"An error occurred… try again"* as the
+tool's output **to the model** — which would turn Sakrit's ``DivergentRetry`` /
+``AmbiguousOutcome`` halts into a suggestion an LLM can retry around. Guarded tools MUST let a
+:class:`~sakrit.core.errors.SakritError` propagate: set ``failure_error_function=None``
+(re-raise everything) or ``failure_error_function=`` :func:`sakrit_failure_error_function`
+(re-raise Sakrit errors, stringify ordinary ones).
+
+**Limit (same shape as LangGraph's plan-epoch gap):** a run *re-run from scratch* (no saved
+state) re-asks the model, minting new call ids — a re-plan (R3), outside positional identity
+by design. Use a business ``key=`` for effects that must dedup across re-planning.
+
+Framework import lives here, never in ``sakrit.core``. Requires the ``openai-agents`` extra;
+import this module explicitly so plain ``import sakrit`` stays framework-free.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+
+from agents.tool_context import ToolContext
+
+from sakrit.core.coordinate import Capabilities, Coordinate, Stability
+from sakrit.core.errors import SakritError
+
+# The SDK versions this adapter's identity derivation is conformance-tested against
+# (tests/integration/test_openai_agents_conformance.py). The SDK is pre-1.0 and minors
+# can break: outside the tested range, run the conformance suite before trusting
+# positional keys — a call-id or RunState change strands them.
+SUPPORTED_OPENAI_AGENTS = (">=0.18", "<1.0")
+
+# The active (tool context, explicit scope) bridged from the tool body. Per-task via a
+# contextvar so concurrent tool executions don't clobber each other.
+_tool_ctx: ContextVar[tuple[ToolContext, str | None] | None] = ContextVar(
+    "sakrit_oa_tool_ctx", default=None
+)
+
+
+@contextmanager
+def tool_boundary(ctx: ToolContext, *, scope: str | None = None) -> Iterator[None]:
+    """Make ``ctx`` the coordinate source for guarded calls in this block.
+
+    Call it first thing in the tool body, passing the tool's ``ToolContext`` argument and a
+    **stable per-run identity** as ``scope`` — an id you persist alongside the ``RunState``
+    string (a workflow/run id), so it is byte-identical on every resume. The adapter
+    deliberately does not derive scope from the ambient trace (Fable A-1): that is controlled
+    by the resume *environment*, not the recorded state, and varies across a ``with trace(...)``
+    wrapper or a tracing-config change.
+
+    **The scope must be no coarser than the provider's call-id-uniqueness domain (Fable B-2).**
+    ``call_site`` is the model's ``tool_call_id``; OpenAI Responses ids are globally unique, but
+    a chat-completions/LiteLLM-backed provider can emit deterministic ids (``call_0``) that
+    repeat *across runs*. A **per-run** scope keeps two runs' ``call_0`` distinct; a
+    *conversation*-wide scope would let them collide — so scope per run, not per conversation.
+
+    ``scope`` is **stripped**, and an explicitly-passed but blank-after-strip scope is refused
+    loudly (Fable B-1): a whitespace-only run identity would pool every run into one scope (a
+    silent duplicate — the blank-``checkpoint_ns`` analog), and an unstripped ``" run-1"`` vs
+    ``"run-1"`` (e.g. a run id read from a file with a trailing newline) would re-key every
+    resume. Omitting ``scope`` entirely is allowed and yields no coordinate — the guard must
+    then supply an explicit ``key=`` — never a fabricated scope. Also refuses a context with no
+    usable ``tool_call_id``.
+    """
+    call_id = str(getattr(ctx, "tool_call_id", "") or "").strip()
+    if not call_id:
+        raise SakritError(
+            "tool_boundary needs a ToolContext with a tool_call_id — got none. Pass the "
+            "tool's ToolContext argument (declare it as the first parameter of the tool)."
+        )
+    if scope is not None:
+        scope = scope.strip()  # normalize a trailing-newline run id so resumes don't re-key
+        if not scope:
+            raise SakritError(
+                "tool_boundary got a blank scope= (whitespace only). A blank run identity would "
+                "pool every run into one scope — a silent duplicate. Pass a real, stable per-run "
+                "id, or omit scope= to fall to the ladder (an explicit key=)."
+            )
+    token = _tool_ctx.set((ctx, scope))
+    try:
+        yield
+    finally:
+        _tool_ctx.reset(token)
+
+
+def sakrit_failure_error_function(ctx: object, error: Exception) -> str:
+    """A ``function_tool(failure_error_function=...)`` that lets Sakrit's loud refusals through.
+
+    ``function_tool`` otherwise converts a raised tool exception into model-visible text, which
+    would silence a :class:`~sakrit.core.errors.SakritError` halt (Fable A-3). This re-raises a
+    ``SakritError`` (so the halt reaches the app) while stringifying an ordinary tool error the
+    model may reasonably retry. (Pass ``failure_error_function=None`` instead to re-raise
+    *every* tool error.)
+
+    **How the halt surfaces:** the SDK wraps a re-raised non-``AgentsException`` tool error in
+    ``agents.exceptions.UserError`` with the original as ``__cause__``. So the app catches an
+    ``AgentsException`` (a ``UserError``) whose ``__cause__`` is the ``SakritError`` — loud,
+    operator-visible, and never fed back to the model. Catch ``UserError`` and inspect
+    ``__cause__`` (or walk the cause chain) to recover the ``DivergentRetry`` /
+    ``AmbiguousOutcome``.
+    """
+    if isinstance(error, SakritError):
+        raise error
+    return f"An error occurred while running the tool: {error}"
+
+
+class OpenAIAgentsAdapter:
+    """A :class:`~sakrit.core.adapter.RuntimeAdapter` over the Agents SDK's recorded tool calls
+    (see the module docstring for the conformance basis and the explicit-scope contract)."""
+
+    def current_coordinate(self) -> Coordinate | None:
+        bound = _tool_ctx.get()
+        if bound is None:
+            return None  # not inside a tool_boundary → fall to the coordinate ladder
+        ctx, scope = bound
+        call_id = str(ctx.tool_call_id).strip()
+        if not call_id:
+            return None  # belt — tool_boundary already refuses this loudly
+        if not scope:
+            # No state-carried retry domain and no explicit one → do NOT fabricate from the
+            # ambient trace (A-1). Fall to the ladder: the guard must carry an explicit key=.
+            return None
+        return Coordinate(scope=scope, call_site=call_id.encode("utf-8"))
+
+    # --- ReservedAdapter (P5-4: semantics unfixed, not yet consumed) ------------------
+    def stability_domain(self) -> Stability:
+        # Resuming a saved RunState re-dispatches the recorded calls; a from-scratch re-run
+        # re-plans (R3, epochs — deferred). Within the saved-state regime the call id survives
+        # resume and retry; scope is app-supplied and equally stable by contract.
+        return Stability.REPLAY | Stability.RETRY
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities.NONE
+
+    def scope_terminal(self, scope: str) -> bool:
+        return False