specunode 0.1.0__py3-none-any.whl

specunode/__init__.py

@@ -0,0 +1,94 @@
+"""SpecuNode -- agents that take real actions, and never take one twice.
+
+A runtime for AI agents whose tools change the world. Every write is held until the model's
+decision behind it is durable, claimed in a journal under a deterministic key before it is sent,
+and never sent twice -- a crash is resumed onto the same keys, and a reply lost in a crash is
+either asked about (``reconcile``) or handed to a human, never guessed at. Every run replays.
+
+The public API is exposed lazily, so ``import specunode`` stays cheap and does not pull in the
+optional integrations (LangGraph, MCP, Anthropic) until they are used::
+
+    import specunode
+
+    @specunode.tool(effect="write")
+    async def charge_card(customer_id: str, amount: float) -> dict: ...
+
+    runtime = specunode.Runtime(specunode.graph(nodes, route), tools=[charge_card])
+    result = await runtime.run(inputs)
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.1.0"
+
+#: Public name -> (module, attribute). Imported on first use.
+_EXPORTS: dict[str, tuple[str, str]] = {
+    "tool": ("specunode.integrations.plain", "tool"),
+    "node": ("specunode.integrations.plain", "node"),
+    "graph": ("specunode.api", "graph"),
+    "Runtime": ("specunode.api", "Runtime"),
+    "current_idempotency_key": ("specunode.api", "current_idempotency_key"),
+    "agent_loop": ("specunode.core.loop", "agent_loop"),
+    "RunSession": ("specunode.core.graph", "RunSession"),
+    "Decision": ("specunode.core.decision", "Decision"),
+    "FreeText": ("specunode.core.decision", "FreeText"),
+    "ToolCall": ("specunode.core.decision", "ToolCall"),
+    "EffectClass": ("specunode.core.effects", "EffectClass"),
+    "Policy": ("specunode.core.policy", "Policy"),
+    "RunResult": ("specunode.core.scheduler", "RunResult"),
+    "ToolDispatchError": ("specunode.buffer.dispatcher", "ToolDispatchError"),
+    "ModelError": ("specunode.core.model", "ModelError"),
+    "TurnAbandoned": ("specunode.core.model", "TurnAbandoned"),
+    "AnthropicModel": ("specunode.integrations.anthropic", "AnthropicModel"),
+}
+
+__all__ = [
+    "AnthropicModel",
+    "Decision",
+    "EffectClass",
+    "FreeText",
+    "ModelError",
+    "Policy",
+    "RunResult",
+    "RunSession",
+    "Runtime",
+    "ToolCall",
+    "ToolDispatchError",
+    "TurnAbandoned",
+    "__version__",
+    "agent_loop",
+    "current_idempotency_key",
+    "graph",
+    "node",
+    "tool",
+]
+
+if TYPE_CHECKING:  # the same names, for type checkers and editors
+    from specunode.api import Runtime, current_idempotency_key, graph
+    from specunode.buffer.dispatcher import ToolDispatchError
+    from specunode.core.decision import Decision, FreeText, ToolCall
+    from specunode.core.effects import EffectClass
+    from specunode.core.graph import RunSession
+    from specunode.core.loop import agent_loop
+    from specunode.core.model import ModelError, TurnAbandoned
+    from specunode.core.policy import Policy
+    from specunode.core.scheduler import RunResult
+    from specunode.integrations.anthropic import AnthropicModel
+    from specunode.integrations.plain import node, tool
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        module, attribute = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module 'specunode' has no attribute {name!r}") from None
+    value = getattr(importlib.import_module(module), attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_EXPORTS})

specunode/api.py

@@ -0,0 +1,170 @@
+"""The front door: declare tools and nodes, build a graph, run it, resume it.
+
+Every piece here exists elsewhere in the package. What this module adds is the wiring every
+first run needs and nobody should have to write -- a journal, a store buffer, a dispatcher and a
+scheduler, assembled with every safety check left on -- so that a run is::
+
+    import specunode
+
+    @specunode.tool(effect="write")
+    async def charge_card(customer_id: str, amount: float) -> dict: ...
+
+    @specunode.node()
+    async def bill(session: specunode.RunSession) -> specunode.Decision: ...
+
+    runtime = specunode.Runtime(specunode.graph([bill], route), tools=[charge_card])
+    result = await runtime.run({"customer_id": "cus-1"})
+    # killed half way?  await runtime.resume(result.run_id)
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from specunode.buffer.dispatcher import Dispatcher
+from specunode.buffer.store_buffer import StoreBuffer
+from specunode.canonical import JsonValue
+from specunode.core.effects import ToolRegistry
+from specunode.core.graph import GraphAdapter
+from specunode.core.model import (
+    JournaledModel,
+    ModelClient,
+    ModelError,
+    ModelResponse,
+    RequestEnvelope,
+    StreamEvent,
+    call_scope,
+)
+from specunode.core.policy import Policy
+from specunode.core.scheduler import RunResult, Scheduler
+from specunode.ids import new_ulid
+from specunode.integrations.plain import PlainAdapter, registry_of
+from specunode.journal.journal import Journal, is_postgres_dsn
+
+__all__ = ["Runtime", "current_idempotency_key", "graph"]
+
+#: Where a run's journal lives unless told otherwise: beside the code that runs it.
+DEFAULT_JOURNAL = Path(".specunode") / "journal.db"
+
+
+def graph(
+    nodes: Iterable[Callable[..., Any]],
+    route: Callable[[Mapping[str, JsonValue]], str | Sequence[str] | None],
+) -> PlainAdapter:
+    """A graph from decorated node functions and a router.
+
+    The router is handed the committed state and returns the next node's name, a list of names
+    to run side by side and retire in that order, or ``None`` to end the run.
+    """
+    return PlainAdapter.of(nodes, route)
+
+
+def current_idempotency_key() -> str:
+    """The key the runtime is dispatching this call under. Pass it to the upstream.
+
+    Deterministic: the same call at the same point of the same run derives the same key on a
+    resume or a replay, which is what lets an upstream that honours idempotency keys -- and a
+    tool's ``reconcile`` -- recognise a request it has already seen. Only defined inside a tool
+    while the runtime is dispatching it.
+    """
+    scope = call_scope.get()
+    key = scope.effect_key if scope is not None else ""
+    if not key:
+        raise RuntimeError(
+            "current_idempotency_key() is only defined inside a tool the runtime is "
+            "dispatching; a read, or a call made outside a run, has no key"
+        )
+    return key
+
+
+@dataclass
+class _NoModel:
+    """The target of a runtime built without a model: fine until something asks it."""
+
+    def _refuse(self) -> ModelError:
+        return ModelError(
+            "this Runtime was built without a model, and a node asked one; pass model=..."
+        )
+
+    async def complete(self, envelope: RequestEnvelope) -> ModelResponse:
+        raise self._refuse()
+
+    async def stream(self, envelope: RequestEnvelope) -> AsyncIterator[StreamEvent]:
+        raise self._refuse()
+        yield  # type: ignore[unreachable]  # pragma: no cover - makes this an async generator
+
+
+@dataclass
+class Runtime:
+    """A graph, its tools and a journal: everything a run and its resume need.
+
+    ``tools`` is a list of functions decorated with ``@specunode.tool``, or a registry.
+    ``model`` is the model the graph's nodes ask; a graph whose nodes never ask one needs none.
+    ``journal`` is a path to a SQLite file (created if absent) or a ``Journal``.
+    """
+
+    graph: GraphAdapter
+    tools: ToolRegistry | Sequence[Callable[..., Any]] = ()
+    model: ModelClient | None = None
+    journal: Journal | str | Path = DEFAULT_JOURNAL
+    #: Guessing is off: it needs a drafter, and without one it only adds bookkeeping to every
+    #: receipt. Issuing a read the moment its block parses is not guessing, and stays on.
+    policy: Policy = field(default_factory=lambda: Policy(speculation=False))
+    reducers: Mapping[str, str] = field(default_factory=dict)
+    #: Attempts per effect before it is dead-lettered, and the first backoff between them.
+    max_attempts: int = 3
+    base_delay_ms: float = 50.0
+
+    def _journal(self) -> Journal:
+        if isinstance(self.journal, Journal):
+            return self.journal
+        if is_postgres_dsn(self.journal):
+            # Not through ``Path``, which folds the DSN's ``//`` into ``/`` and made a SQLite
+            # file of it -- in a folder named ``postgresql:``.
+            return Journal(str(self.journal))
+        path = Path(self.journal)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return Journal(path)
+
+    def _registry(self) -> ToolRegistry:
+        if isinstance(self.tools, ToolRegistry):
+            return self.tools
+        return registry_of(self.tools)
+
+    def scheduler(self) -> Scheduler:
+        """A scheduler wired to this runtime's journal -- one per run or resume."""
+        journal = self._journal()
+        registry = self._registry()
+        return Scheduler(
+            graph=self.graph,
+            registry=registry,
+            journal=journal,
+            buffer=StoreBuffer(journal=journal, run_id=""),
+            dispatcher=Dispatcher(
+                registry=registry,
+                max_attempts=self.max_attempts,
+                base_delay_ms=self.base_delay_ms,
+            ),
+            target=JournaledModel(self.model or _NoModel(), journal),
+            policy=self.policy,
+            reducers=dict(self.reducers),
+        )
+
+    async def run(
+        self, inputs: Mapping[str, JsonValue] | None = None, *, run_id: str | None = None
+    ) -> RunResult:
+        """Run the graph to the end. ``result.run_id`` is what :meth:`resume` takes."""
+        return await self.scheduler().run(run_id or new_ulid(), dict(inputs or {}))
+
+    async def resume(self, run_id: str, *, ask_abandoned: bool = False) -> RunResult:
+        """Continue a run a crash interrupted, without sending again what already went out.
+
+        ``ask_abandoned``: where a node keeps waiting on a turn the crashed run had stopped
+        waiting for, the model is asked again, live, at the point the node would be stopped
+        with ``TurnAbandoned`` -- that turn only, and not one the node stops waiting for again
+        as the crashed run did. Its answer may differ from what was acted on.
+        """
+        return await self.scheduler().resume(run_id, ask_abandoned=ask_abandoned)

specunode/buffer/dispatcher.py

@@ -0,0 +1,171 @@
+"""Dispatch: at-least-once, with deterministic idempotency keys.
+
+The docs say "at-least-once dispatch with deterministic idempotency keys" and never claim
+"exactly-once", because the only thing that makes a repeated delivery harmless is the *tool*
+honouring its key -- and whether it does is the developer's word, measured in attack 7.4
+rather than assumed. The vocabulary test fails the build on an unqualified claim to the
+contrary, including one made here.
+
+Backoff is exponential and **unjittered by default**. Jitter is the usual advice and it is
+wrong here: the chaos matrix has to reproduce a failure it found, and a random delay makes a
+leak that appeared once unreproducible.
+
+Every failure reports whether the request *left the process*. That single bit is what keeps
+the ambiguous crash window narrow: a connection refused before any bytes went out is safe to
+retry, while a timeout after the request was sent is the two-generals boundary and is treated
+as such.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Literal
+
+from specunode.canonical import JsonValue
+from specunode.core.effects import ToolRegistry, UnknownTool
+from specunode.core.model import CallScope, call_scope
+
+__all__ = ["DispatchOutcome", "Dispatcher", "ToolDispatchError"]
+
+Sent = Literal["no", "maybe"]
+
+
+class ToolDispatchError(RuntimeError):
+    """A dispatch attempt failed.
+
+    ``sent`` is the load-bearing field. ``"no"`` means nothing left this process, so a retry
+    cannot duplicate anything. ``"maybe"`` -- the default, because it is the safe assumption --
+    means the upstream may already have acted.
+    """
+
+    def __init__(self, message: str, *, sent: Sent = "maybe", retriable: bool = True) -> None:
+        super().__init__(message)
+        self.sent: Sent = sent
+        self.retriable = retriable
+
+
+@dataclass(frozen=True, slots=True)
+class DispatchOutcome:
+    ok: bool
+    ack: JsonValue = None
+    attempts: int = 0
+    error: str | None = None
+    sent: Sent = "no"
+    #: True when the dispatcher was asked not to call the tool. Carried through to the journal
+    #: and the ledger, because a row that reads DISPATCHED for an effect that never left is
+    #: exactly the kind of untrue record this project exists to make impossible.
+    dry_run: bool = False
+
+
+@dataclass
+class Dispatcher:
+    """Sends a staged effect to the world, with bounded retries."""
+
+    registry: ToolRegistry
+    max_attempts: int = 5
+    base_delay_ms: float = 50.0
+    cap_delay_ms: float = 5000.0
+    #: Off by default so a chaos run can reproduce what it found. Turn it on in production,
+    #: where a thundering herd matters more than reproducibility.
+    jitter: bool = False
+    #: Never call the tool; report the effect as it would have been sent.
+    #:
+    #: This exists for ``specunode replay``. Replaying a run against its journal re-drives the
+    #: graph, and a graph that re-drives dispatches -- so a replay of a run that charged a card
+    #: would charge it again, from a command whose whole purpose is to answer a question about
+    #: the past. The default there is therefore to dispatch nothing, and sending for real is
+    #: behind a flag that names what it is for.
+    dry_run: bool = False
+
+    def _delay_ms(self, attempt: int) -> float:
+        return float(min(self.base_delay_ms * (2.0 ** (attempt - 1)), self.cap_delay_ms))
+
+    async def dispatch(
+        self,
+        tool: str,
+        args: dict[str, JsonValue],
+        *,
+        idempotency_key: str,
+        branch_id: str,
+        before_attempt: Callable[[], Awaitable[None]] | None = None,
+    ) -> DispatchOutcome:
+        """Call ``tool``, retrying until it acks or the attempts run out.
+
+        A retry is only ever safe for one of two reasons: the attempt that failed demonstrably
+        sent nothing (``sent="no"``), or the tool declared a repeat harmless (``idempotent``).
+        After a failure that may have taken effect, a tool that did not declare it is not
+        called again -- the outcome is reported as ``sent="maybe"``, and the store buffer asks
+        the upstream (the tool's ``reconcile``) or dead-letters it. Retrying anyway charged a
+        card twice whenever a gateway took the charge and timed out on the reply, with the
+        default settings and no crash at all.
+
+        ``sent`` on a failed outcome is ``"maybe"`` if *any* attempt may have taken effect, not
+        whatever the last one said: an attempt that landed followed by one that was refused is
+        still an effect that may be out.
+
+        The call runs under a :class:`CallScope` carrying the branch and the key, which is how
+        the fake world attributes every mutation -- and therefore how the leak test can state
+        its invariant as a set comparison.
+
+        ``before_attempt`` runs before every attempt, and stops the dispatch by raising: the
+        store buffer checks there that this process still holds the run.
+        """
+        spec = self.registry.get(tool)
+        if self.dry_run:
+            # Resolved above, so an unknown tool is still an error here rather than something
+            # a dry run silently reports as fine and a real one then fails on.
+            return DispatchOutcome(
+                ok=True, ack={"dry_run": True}, attempts=0, sent="no", dry_run=True
+            )
+        last_error: str | None = None
+        maybe_sent = False
+
+        for attempt in range(1, self.max_attempts + 1):
+            if before_attempt is not None:
+                await before_attempt()
+            scope = CallScope(branch_id=branch_id, effect_key=idempotency_key, speculative=False)
+            token = call_scope.set(scope)
+            retriable = True
+            try:
+                ack = await spec.fn(**args)
+                return DispatchOutcome(ok=True, ack=ack, attempts=attempt, sent="maybe")
+            except UnknownTool as exc:
+                # Not retriable and not ambiguous: there was nothing to call.
+                return DispatchOutcome(
+                    ok=False,
+                    attempts=attempt,
+                    error=str(exc),
+                    sent="maybe" if maybe_sent else "no",
+                )
+            except ToolDispatchError as exc:
+                last_error, retriable = str(exc), exc.retriable
+                # Anything but a plain "no" may have landed -- fail safe on a value the tool
+                # got wrong, rather than retrying a write because it did not say "maybe".
+                maybe_sent = maybe_sent or exc.sent != "no"
+            except asyncio.CancelledError:
+                # A drain is never speculative, so a cancellation here is the process going
+                # away rather than a squash. Do not swallow it.
+                raise
+            except Exception as exc:  # an adapter that raised something of its own
+                last_error, maybe_sent = f"{type(exc).__name__}: {exc}", True
+            finally:
+                call_scope.reset(token)
+
+            if not retriable or (maybe_sent and not spec.idempotent):
+                return DispatchOutcome(
+                    ok=False,
+                    attempts=attempt,
+                    error=last_error,
+                    sent="maybe" if maybe_sent else "no",
+                )
+            if attempt < self.max_attempts:
+                await asyncio.sleep(self._delay_ms(attempt) / 1000.0)
+
+        return DispatchOutcome(
+            ok=False,
+            attempts=self.max_attempts,
+            error=last_error,
+            sent="maybe" if maybe_sent else "no",
+        )

specunode/buffer/idempotency.py

@@ -0,0 +1,160 @@
+"""Idempotency keys: one preimage, three derivations (Hard Rule 8).
+
+    key = blake2b(run_id | branch_lineage | node_id | step_index | tool_name | canonical(args))
+
+The spec's formula, with the framing made explicit: the preimage is a canonical JSON *object*,
+never a concatenation, because ``("ab", "c")`` and ``("a", "bc")`` concatenate to the same
+bytes and two different effects must never share a key.
+
+Three values come out of that one preimage, and confusing them is the subtle failure this
+module exists to prevent:
+
+``key`` -- lineage-bearing, internal
+    Indexes the store buffer, names a :class:`StagedEffect`, and appears in the journal and the
+    ledger. The lineage is what keeps two siblings' staged rows apart *before* resolution:
+    they occupy the same ``step_index`` and the same ``node_id`` by construction, so without it
+    their entries alias and discarding the loser would drop the winner's row.
+
+``nkey`` -- lineage-free, run-scoped
+    The dedupe table's primary key, and the idempotency token handed to the tool adapter. It
+    must be lineage-free because the same logical effect legitimately arrives down different
+    paths: a stalled branch's effect is discarded and re-staged by the sequential re-execution
+    under a new branch id, and a resume re-mints branch ids entirely. Keyed on ``key``, every
+    one of those would re-dispatch -- a second charge on the same card.
+
+``ekey`` -- lineage-free *and* run-free, comparison only
+    Used by :func:`~specunode.verify.equivalence.normalise_for_equivalence` and nowhere else.
+    It carries a different domain prefix so that it cannot be mistaken for a dispatch key even
+    if it were passed somewhere one was expected.
+
+Lineage contributes no uniqueness among *dispatched* effects, because at most one branch per
+program position ever retires. That is exactly why stripping it is sound for dedupe and for
+equivalence, and exactly why it must stay in ``key``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from hashlib import blake2b
+from typing import NewType
+
+from specunode.canonical import JsonValue, canonical
+
+__all__ = [
+    "EQUIV_DOMAIN",
+    "KEY_DOMAIN",
+    "DedupeKey",
+    "EquivalenceKey",
+    "IdempotencyKey",
+    "dedupe_key",
+    "equivalence_key",
+    "idempotency_key",
+    "key_preimage",
+]
+
+#: Domain separators, so a key can never collide with a journal entry hash or a ledger
+#: signature preimage even when the same bytes are fed to all three.
+KEY_DOMAIN = b"specunode/idempotency/v1\x00"
+EQUIV_DOMAIN = b"specunode/equiv-key/v1\x00"
+
+IdempotencyKey = NewType("IdempotencyKey", str)
+DedupeKey = NewType("DedupeKey", str)
+EquivalenceKey = NewType("EquivalenceKey", str)
+
+
+def key_preimage(
+    *,
+    run_id: str,
+    lineage: Sequence[str],
+    node_id: str,
+    step_index: int,
+    tool_name: str,
+    args: Mapping[str, JsonValue],
+) -> bytes:
+    """The canonical bytes every key derivation hashes.
+
+    Public, because the property tests and ``docs/replay.md`` assert on these exact bytes: a
+    key nobody can reproduce by hand is a key nobody can audit.
+    """
+    return canonical(
+        {
+            "run_id": run_id,
+            "lineage": list(lineage),
+            "node_id": node_id,
+            "step_index": step_index,
+            "tool": tool_name,
+            "args": args,
+        }
+    )
+
+
+def _digest(domain: bytes, preimage: bytes) -> str:
+    return blake2b(domain + preimage, digest_size=32).hexdigest()
+
+
+def idempotency_key(
+    *,
+    run_id: str,
+    lineage: Sequence[str],
+    node_id: str,
+    step_index: int,
+    tool_name: str,
+    args: Mapping[str, JsonValue],
+) -> IdempotencyKey:
+    """Hard Rule 8's key, verbatim. Internal: indexes the store buffer, never leaves."""
+    return IdempotencyKey(
+        _digest(
+            KEY_DOMAIN,
+            key_preimage(
+                run_id=run_id,
+                lineage=lineage,
+                node_id=node_id,
+                step_index=step_index,
+                tool_name=tool_name,
+                args=args,
+            ),
+        )
+    )
+
+
+def dedupe_key(
+    *,
+    run_id: str,
+    node_id: str,
+    step_index: int,
+    tool_name: str,
+    args: Mapping[str, JsonValue],
+) -> DedupeKey:
+    """The value the dedupe table and the tool adapter see. Lineage-free by construction."""
+    return DedupeKey(
+        _digest(
+            KEY_DOMAIN,
+            key_preimage(
+                run_id=run_id,
+                lineage=(),
+                node_id=node_id,
+                step_index=step_index,
+                tool_name=tool_name,
+                args=args,
+            ),
+        )
+    )
+
+
+def equivalence_key(
+    *, node_id: str, step_index: int, tool_name: str, args: Mapping[str, JsonValue]
+) -> EquivalenceKey:
+    """Comparison only (Hard Rule 9). Run-free, lineage-free, and never dispatchable."""
+    return EquivalenceKey(
+        _digest(
+            EQUIV_DOMAIN,
+            key_preimage(
+                run_id="",
+                lineage=(),
+                node_id=node_id,
+                step_index=step_index,
+                tool_name=tool_name,
+                args=args,
+            ),
+        )
+    )