statepilot 0.1.0__py3-none-any.whl

statepilot/__about__.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the package version."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"

statepilot/__init__.py

@@ -0,0 +1,64 @@
+"""statepilot — deterministic state-machine guards for AI-agent workflows.
+
+Define a state machine, then enforce at *runtime* which tools an agent may call,
+in which order, with loop detection, a cost budget, and a hard step cap.
+
+Quickstart::
+
+    from statepilot import StateMachine, Pilot, guarded
+
+    machine = (
+        StateMachine.builder()
+        .initial("research")
+        .transition("research", "research", tool="search")   # loop allowed...
+        .transition("research", "draft", tool="write_draft")
+        .transition("draft", "review", tool="review")
+        .transition("review", "published", tool="publish")
+        .terminal("published")
+        .build()
+    )
+
+    pilot = Pilot(machine, budget=5.0, max_state_visits=3)
+
+    @guarded(pilot, cost=1.0)
+    def search(q: str) -> str:
+        ...
+
+    search("agents")          # allowed, charges 1.0
+    pilot.step("write_draft") # advance to draft
+"""
+
+from __future__ import annotations
+
+from .__about__ import __version__
+from .decorator import guarded
+from .exceptions import (
+    BudgetExceeded,
+    GuardViolation,
+    LoopLimitExceeded,
+    StateMachineError,
+    StatepilotError,
+    StepLimitExceeded,
+    TransitionError,
+)
+from .machine import StateMachine, StateMachineBuilder, Transition
+from .pilot import Pilot, StepRecord
+
+__all__ = [
+    "__version__",
+    # core
+    "Pilot",
+    "StateMachine",
+    "StateMachineBuilder",
+    "StepRecord",
+    "Transition",
+    "guarded",
+    # exceptions
+    "BudgetExceeded",
+    "GuardViolation",
+    "LoopLimitExceeded",
+    "StateMachineError",
+    "StatepilotError",
+    "StepLimitExceeded",
+    "TransitionError",
+]

statepilot/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Optional, weakly-coupled adapters for orchestration frameworks.
+
+Importing :mod:`statepilot.adapters` does **not** import any third-party
+framework. Each adapter is written against the framework's stable *callable
+contract* rather than its internal API, so it keeps working across framework
+versions and needs the framework only at the call site, not at import time.
+"""
+
+from __future__ import annotations
+
+from .langgraph import guard_node
+
+__all__ = ["guard_node"]

statepilot/adapters/langgraph.py

@@ -0,0 +1,81 @@
+"""LangGraph adapter — **experimental**.
+
+LangGraph's public surface (``StateGraph``, ``add_node``, ``ToolNode``) has moved
+across releases, but one contract has been stable since early versions: a *node*
+is a callable that takes the graph state and returns a partial-state ``dict``::
+
+    def my_node(state: dict) -> dict:
+        ...
+        return {"some_key": value}
+
+This adapter hooks into that contract. :func:`guard_node` wraps any node callable
+so that a :class:`statepilot.pilot.Pilot` validates the transition *before* the
+node body runs. Because it targets the callable contract and never imports
+``langgraph``, it does not break when the LangGraph API churns, and it adds no
+import-time dependency.
+
+It is deliberately minimal. For anything beyond "guard this node", drive the
+:class:`~statepilot.pilot.Pilot` yourself inside your node functions — that is the
+fully supported path. Treat this module as a convenience, not a framework
+integration layer.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from statepilot.pilot import Pilot
+
+__all__ = ["guard_node"]
+
+
+def guard_node(
+    pilot: Pilot,
+    node: Callable[[Any], Any],
+    *,
+    tool: str | None = None,
+    cost: float = 0.0,
+) -> Callable[[Any], Any]:
+    """Wrap a LangGraph node callable with a statepilot guard.
+
+    Args:
+        pilot: The :class:`~statepilot.pilot.Pilot` enforcing the rules.
+        node: A LangGraph node — any callable ``state -> partial_state_dict``.
+        tool: Tool name used for the transition. Defaults to the node's
+            ``__name__`` (or ``"node"`` for objects without one).
+        cost: Cost to attribute to entering this node.
+
+    Returns:
+        A callable with the same ``state -> result`` signature as ``node``. It
+        calls :meth:`Pilot.step` before invoking ``node``; a
+        :class:`~statepilot.exceptions.GuardViolation` therefore stops the node
+        from running.
+
+    Example (pseudocode — requires ``langgraph`` installed at call time)::
+
+        from langgraph.graph import StateGraph
+        from statepilot import StateMachine, Pilot
+        from statepilot.adapters import guard_node
+
+        pilot = Pilot(machine, budget=5.0)
+        graph = StateGraph(MyState)
+        graph.add_node("research", guard_node(pilot, research_node, cost=1.0))
+        graph.add_node("draft", guard_node(pilot, draft_node))
+
+    .. warning::
+        Experimental. The contract it relies on (node = callable returning a
+        partial-state dict) is stable, but conditional edges, ``Send`` fan-out
+        and checkpoint/resume are out of scope and untested here.
+    """
+    tool_name = tool if tool is not None else getattr(node, "__name__", "node")
+
+    @functools.wraps(node)
+    def wrapped(state: Any) -> Any:
+        pilot.step(tool_name, cost=cost)
+        return node(state)
+
+    return wrapped

statepilot/decorator.py

@@ -0,0 +1,63 @@
+"""The :func:`guarded` decorator.
+
+Wrap a tool function so that a :class:`statepilot.pilot.Pilot` validates the call
+*before* the wrapped function runs. If the pilot rejects the call, the function
+body never executes and the guard exception propagates.
+"""
+
+from __future__ import annotations
+
+import functools
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from .pilot import Pilot
+
+__all__ = ["guarded"]
+
+F = TypeVar("F", bound="Callable[..., Any]")
+
+
+def guarded(
+    pilot: Pilot,
+    *,
+    tool: str | None = None,
+    cost: float = 0.0,
+) -> Callable[[F], F]:
+    """Decorate a tool function with a state-machine guard.
+
+    Args:
+        pilot: The :class:`~statepilot.pilot.Pilot` that enforces the rules.
+        tool: The tool name used for the transition. Defaults to the wrapped
+            function's ``__name__``.
+        cost: Cost to attribute to the call (counts against the pilot budget).
+
+    The decorated function calls :meth:`Pilot.step` with the resolved tool name
+    and cost *before* executing its body. A
+    :class:`~statepilot.exceptions.GuardViolation` therefore prevents the body
+    from running at all.
+
+    Example::
+
+        pilot = Pilot(machine, budget=5.0)
+
+        @guarded(pilot, cost=1.0)
+        def research(query: str) -> str:
+            return do_research(query)
+
+        research("agents")  # advances the machine, charges 1.0, then runs
+    """
+
+    def decorate(func: F) -> F:
+        tool_name = tool if tool is not None else func.__name__
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            pilot.step(tool_name, cost=cost)
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorate

statepilot/exceptions.py

@@ -0,0 +1,92 @@
+"""Exception hierarchy for statepilot.
+
+All runtime guard violations derive from :class:`GuardViolation`, so callers can
+catch the whole class of "the agent tried to do something the state machine
+forbids" with a single ``except``. Definition-time problems (bad state machine
+spec) raise :class:`StateMachineError` instead.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "BudgetExceeded",
+    "GuardViolation",
+    "LoopLimitExceeded",
+    "StateMachineError",
+    "StatepilotError",
+    "StepLimitExceeded",
+    "TransitionError",
+]
+
+
+class StatepilotError(Exception):
+    """Base class for every error raised by statepilot."""
+
+
+class StateMachineError(StatepilotError):
+    """Raised when a state machine definition is invalid.
+
+    This is a *definition-time* error (unknown state, duplicate transition,
+    missing initial state, …). It is not a guard violation — the machine itself
+    is malformed.
+    """
+
+
+class GuardViolation(StatepilotError):
+    """Base class for all *runtime* guard violations.
+
+    Catch this to treat "the agent broke a rule" uniformly, regardless of
+    whether it was a forbidden transition, a loop, a budget overrun, or too many
+    steps.
+    """
+
+
+class TransitionError(GuardViolation):
+    """Raised when a tool/event is not allowed from the current state."""
+
+    def __init__(self, tool: str, state: str, allowed: tuple[str, ...]) -> None:
+        self.tool = tool
+        self.state = state
+        self.allowed = allowed
+        allowed_str = ", ".join(sorted(allowed)) if allowed else "<none>"
+        super().__init__(
+            f"Tool '{tool}' is not allowed in state '{state}'. "
+            f"Allowed tools here: {allowed_str}."
+        )
+
+
+class LoopLimitExceeded(GuardViolation):
+    """Raised when a state or tool repeats more often than the configured limit."""
+
+    def __init__(self, kind: str, name: str, count: int, limit: int) -> None:
+        self.kind = kind
+        self.name = name
+        self.count = count
+        self.limit = limit
+        super().__init__(
+            f"Loop limit exceeded: {kind} '{name}' would reach {count} "
+            f"occurrences (limit {limit})."
+        )
+
+
+class BudgetExceeded(GuardViolation):
+    """Raised when the cumulative cost would exceed the configured budget."""
+
+    def __init__(self, spent: float, cost: float, budget: float) -> None:
+        self.spent = spent
+        self.cost = cost
+        self.budget = budget
+        super().__init__(
+            f"Budget exceeded: spent {spent} + {cost} would exceed budget {budget}."
+        )
+
+
+class StepLimitExceeded(GuardViolation):
+    """Raised when the total number of steps would exceed ``max_steps``."""
+
+    def __init__(self, steps: int, limit: int) -> None:
+        self.steps = steps
+        self.limit = limit
+        super().__init__(
+            f"Step limit exceeded: step {steps} would exceed max_steps {limit}."
+        )

statepilot/machine.py

@@ -0,0 +1,324 @@
+"""The :class:`StateMachine` definition and its builder.
+
+A :class:`StateMachine` is an immutable, validated description of:
+
+* the set of valid states,
+* the initial state,
+* which states are terminal (no outgoing transitions allowed), and
+* the transitions, each bound to a *tool* (or generic event) name.
+
+It carries no runtime state. Apply it to a :class:`statepilot.pilot.Pilot` to
+enforce it at runtime. Build one with the fluent builder, :meth:`from_dict`, or
+:meth:`from_yaml`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import StateMachineError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from os import PathLike
+
+__all__ = ["StateMachine", "StateMachineBuilder", "Transition"]
+
+
+@dataclass(frozen=True, slots=True)
+class Transition:
+    """A single edge in the state machine.
+
+    Attributes:
+        source: State the transition starts from.
+        dest: State the transition leads to.
+        tool: Name of the tool/event that triggers this transition.
+    """
+
+    source: str
+    dest: str
+    tool: str
+
+
+@dataclass(frozen=True, slots=True)
+class StateMachine:
+    """An immutable, validated state machine definition.
+
+    Prefer the constructors (:meth:`builder`, :meth:`from_dict`,
+    :meth:`from_yaml`) over instantiating this class directly — they validate
+    inputs and produce the internal lookup index.
+    """
+
+    states: frozenset[str]
+    initial: str
+    transitions: tuple[Transition, ...]
+    terminal: frozenset[str] = field(default_factory=frozenset)
+    # Index: (source_state, tool) -> dest_state. Built in __post_init__.
+    _index: dict[tuple[str, str], str] = field(
+        default_factory=dict, compare=False, repr=False
+    )
+
+    def __post_init__(self) -> None:
+        if not self.states:
+            raise StateMachineError("A state machine needs at least one state.")
+        if self.initial not in self.states:
+            raise StateMachineError(
+                f"Initial state '{self.initial}' is not in the set of states."
+            )
+        for bad in self.terminal - self.states:
+            raise StateMachineError(
+                f"Terminal state '{bad}' is not in the set of states."
+            )
+
+        index: dict[tuple[str, str], str] = {}
+        for tr in self.transitions:
+            if tr.source not in self.states:
+                raise StateMachineError(
+                    f"Transition source '{tr.source}' is not a known state."
+                )
+            if tr.dest not in self.states:
+                raise StateMachineError(
+                    f"Transition dest '{tr.dest}' is not a known state."
+                )
+            if tr.source in self.terminal:
+                raise StateMachineError(
+                    f"Terminal state '{tr.source}' cannot have outgoing "
+                    f"transitions (tool '{tr.tool}')."
+                )
+            key = (tr.source, tr.tool)
+            if key in index:
+                raise StateMachineError(
+                    f"Ambiguous transition: tool '{tr.tool}' is defined more "
+                    f"than once for state '{tr.source}'."
+                )
+            index[key] = tr.dest
+        # frozen dataclass: bypass the frozen setter for the cached index.
+        object.__setattr__(self, "_index", index)
+
+    # -- queries ----------------------------------------------------------
+
+    def is_terminal(self, state: str) -> bool:
+        """Return ``True`` if ``state`` is a terminal state."""
+        return state in self.terminal
+
+    def allowed_tools(self, state: str) -> tuple[str, ...]:
+        """Return the tools allowed from ``state``, sorted for determinism."""
+        if state not in self.states:
+            raise StateMachineError(f"Unknown state '{state}'.")
+        return tuple(sorted(tool for (src, tool) in self._index if src == state))
+
+    def resolve(self, state: str, tool: str) -> str | None:
+        """Return the destination state for ``(state, tool)``.
+
+        Returns ``None`` when the transition is not allowed. Does not raise; the
+        :class:`statepilot.pilot.Pilot` decides how to react to ``None``.
+        """
+        return self._index.get((state, tool))
+
+    # -- constructors -----------------------------------------------------
+
+    @classmethod
+    def builder(cls, initial: str | None = None) -> StateMachineBuilder:
+        """Return a fresh fluent :class:`StateMachineBuilder`."""
+        builder = StateMachineBuilder()
+        if initial is not None:
+            builder.initial(initial)
+        return builder
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> StateMachine:
+        """Build a state machine from a plain mapping.
+
+        Expected shape::
+
+            {
+              "initial": "idle",
+              "states": ["idle", "running", "done"],   # optional, inferred otherwise
+              "terminal": ["done"],                      # optional
+              "transitions": [
+                {"from": "idle", "to": "running", "tool": "start"},
+                {"from": "running", "to": "done", "tool": "finish"},
+              ],
+            }
+
+        ``states`` may be omitted; it is then inferred from ``initial`` plus
+        every state mentioned in ``transitions`` and ``terminal``.
+        """
+        if not isinstance(data, dict):
+            raise StateMachineError("State machine definition must be a mapping.")
+
+        initial = data.get("initial")
+        if not isinstance(initial, str) or not initial:
+            raise StateMachineError(
+                "State machine definition needs a non-empty 'initial' state."
+            )
+
+        raw_transitions = data.get("transitions", [])
+        if not isinstance(raw_transitions, list):
+            raise StateMachineError("'transitions' must be a list.")
+
+        transitions: list[Transition] = []
+        mentioned: set[str] = {initial}
+        for i, raw in enumerate(raw_transitions):
+            if not isinstance(raw, dict):
+                raise StateMachineError(f"Transition #{i} must be a mapping.")
+            source = raw.get("from")
+            dest = raw.get("to")
+            tool = raw.get("tool", raw.get("event"))
+            for label, value in (("from", source), ("to", dest), ("tool", tool)):
+                if not isinstance(value, str) or not value:
+                    raise StateMachineError(
+                        f"Transition #{i} is missing a valid '{label}'."
+                    )
+            assert isinstance(source, str)
+            assert isinstance(dest, str)
+            assert isinstance(tool, str)
+            transitions.append(Transition(source=source, dest=dest, tool=tool))
+            mentioned.update((source, dest))
+
+        terminal_raw = data.get("terminal", [])
+        if not isinstance(terminal_raw, list) or not all(
+            isinstance(s, str) for s in terminal_raw
+        ):
+            raise StateMachineError("'terminal' must be a list of strings.")
+        terminal: set[str] = set(terminal_raw)
+        mentioned.update(terminal)
+
+        states_raw = data.get("states")
+        if states_raw is None:
+            states = mentioned
+        else:
+            if not isinstance(states_raw, list) or not all(
+                isinstance(s, str) for s in states_raw
+            ):
+                raise StateMachineError("'states' must be a list of strings.")
+            states = set(states_raw)
+            missing = mentioned - states
+            if missing:
+                raise StateMachineError(
+                    "States referenced but not declared in 'states': "
+                    + ", ".join(sorted(missing))
+                )
+
+        return cls(
+            states=frozenset(states),
+            initial=initial,
+            transitions=tuple(transitions),
+            terminal=frozenset(terminal),
+        )
+
+    @classmethod
+    def from_yaml(cls, text: str) -> StateMachine:
+        """Build a state machine from an inline YAML **string**.
+
+        Requires the optional ``pyyaml`` dependency — install with
+        ``pip install statepilot[yaml]``. This method never touches the
+        filesystem, so an inline string is never accidentally interpreted as a
+        path; to load a file use :meth:`from_yaml_file`.
+        """
+        try:
+            import yaml
+        except ModuleNotFoundError as exc:  # pragma: no cover - import guard
+            raise StateMachineError(
+                "from_yaml requires the optional 'pyyaml' dependency. "
+                "Install it with: pip install statepilot[yaml]"
+            ) from exc
+
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            raise StateMachineError(f"Could not parse YAML: {exc}") from exc
+        if not isinstance(data, dict):
+            raise StateMachineError(
+                "Top-level YAML must be a mapping with 'initial' and "
+                "'transitions' keys."
+            )
+        return cls.from_dict(data)
+
+    @classmethod
+    def from_yaml_file(cls, path: str | PathLike[str]) -> StateMachine:
+        """Build a state machine by reading the YAML **file** at ``path``.
+
+        Requires the optional ``pyyaml`` dependency. Use :meth:`from_yaml` for an
+        inline YAML string.
+        """
+        from pathlib import Path
+
+        return cls.from_yaml(Path(path).read_text(encoding="utf-8"))
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise back to a plain dict (round-trips with :meth:`from_dict`)."""
+        return {
+            "initial": self.initial,
+            "states": sorted(self.states),
+            "terminal": sorted(self.terminal),
+            "transitions": [
+                {"from": tr.source, "to": tr.dest, "tool": tr.tool}
+                for tr in self.transitions
+            ],
+        }
+
+
+class StateMachineBuilder:
+    """Fluent builder for :class:`StateMachine`.
+
+    Example::
+
+        sm = (
+            StateMachine.builder()
+            .initial("idle")
+            .transition("idle", "running", tool="start")
+            .transition("running", "done", tool="finish")
+            .terminal("done")
+            .build()
+        )
+
+    Every mutating method returns ``self`` so calls can be chained.
+    """
+
+    def __init__(self) -> None:
+        self._initial: str | None = None
+        self._states: set[str] = set()
+        self._terminal: set[str] = set()
+        self._transitions: list[Transition] = []
+
+    def initial(self, state: str) -> StateMachineBuilder:
+        """Set the initial state (also registers it as a known state)."""
+        self._initial = state
+        self._states.add(state)
+        return self
+
+    def state(self, *states: str) -> StateMachineBuilder:
+        """Explicitly register one or more states (usually optional)."""
+        self._states.update(states)
+        return self
+
+    def transition(self, source: str, dest: str, *, tool: str) -> StateMachineBuilder:
+        """Add a transition ``source --tool--> dest``.
+
+        States are auto-registered. The keyword-only ``tool`` argument makes the
+        binding explicit at the call site.
+        """
+        self._states.update((source, dest))
+        self._transitions.append(Transition(source=source, dest=dest, tool=tool))
+        return self
+
+    def terminal(self, *states: str) -> StateMachineBuilder:
+        """Mark one or more states as terminal."""
+        self._states.update(states)
+        self._terminal.update(states)
+        return self
+
+    def build(self) -> StateMachine:
+        """Validate and return the immutable :class:`StateMachine`."""
+        if self._initial is None:
+            raise StateMachineError(
+                "No initial state set. Call .initial(state) before .build()."
+            )
+        return StateMachine(
+            states=frozenset(self._states),
+            initial=self._initial,
+            transitions=tuple(self._transitions),
+            terminal=frozenset(self._terminal),
+        )

statepilot/pilot.py

@@ -0,0 +1,297 @@
+"""The runtime guard: :class:`Pilot`.
+
+A :class:`Pilot` wraps a :class:`statepilot.machine.StateMachine` and holds the
+*live* state of one agent run. Every tool call must go through :meth:`Pilot.step`
+(directly or via the :func:`guarded` decorator). The pilot:
+
+* refuses tool calls that are not allowed from the current state
+  (:class:`~statepilot.exceptions.TransitionError`),
+* refuses to leave a terminal state,
+* enforces a loop limit (per-state visits and consecutive-tool repeats),
+* enforces a cumulative cost budget, and
+* enforces a hard cap on the total number of steps.
+
+It records every accepted step in :attr:`Pilot.history` and can export a trace
+for logging or assertions in tests.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from .exceptions import (
+    BudgetExceeded,
+    LoopLimitExceeded,
+    StepLimitExceeded,
+    TransitionError,
+)
+from .machine import StateMachine
+
+__all__ = ["Pilot", "StepRecord"]
+
+# Budget comparisons are forgiving by one tiny epsilon so that accumulating
+# e.g. 0.1 ten times does not spuriously trip a budget of exactly 1.0.
+_EPSILON = 1e-9
+
+
+@dataclass(frozen=True, slots=True)
+class StepRecord:
+    """One accepted transition in a pilot's history.
+
+    Attributes:
+        index: Zero-based position of this step in the run.
+        tool: The tool/event that triggered the transition.
+        source: State before the transition.
+        dest: State after the transition.
+        cost: Cost attributed to this step.
+        cumulative_cost: Total cost spent up to and including this step.
+        timestamp: ``time.time()`` when the step was accepted.
+    """
+
+    index: int
+    tool: str
+    source: str
+    dest: str
+    cost: float
+    cumulative_cost: float
+    timestamp: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return a JSON-serialisable view of this step."""
+        return {
+            "index": self.index,
+            "tool": self.tool,
+            "source": self.source,
+            "dest": self.dest,
+            "cost": self.cost,
+            "cumulative_cost": self.cumulative_cost,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass(slots=True)
+class Pilot:
+    """Stateful runtime enforcer for a :class:`StateMachine`.
+
+    Args:
+        machine: The state machine to enforce.
+        budget: Optional cumulative cost cap. ``None`` disables the budget guard.
+        max_steps: Optional hard cap on total accepted steps. ``None`` disables it.
+        max_state_visits: Optional cap on how often any single state may be
+            entered (loop guard). ``None`` disables per-state loop detection.
+        max_consecutive_tool: Optional cap on how many times the *same* tool may
+            be invoked back-to-back (loop guard). ``None`` disables it.
+
+    The pilot starts in ``machine.initial``. Use :meth:`step` to advance it.
+    """
+
+    machine: StateMachine
+    budget: float | None = None
+    max_steps: int | None = None
+    max_state_visits: int | None = None
+    max_consecutive_tool: int | None = None
+
+    state: str = field(init=False)
+    cost_spent: float = field(init=False, default=0.0)
+    _history: list[StepRecord] = field(init=False, default_factory=list)
+    _state_visits: dict[str, int] = field(init=False, default_factory=dict)
+    _last_tool: str | None = field(init=False, default=None)
+    _consecutive_tool: int = field(init=False, default=0)
+
+    def __post_init__(self) -> None:
+        if self.budget is not None and self.budget < 0:
+            raise ValueError("budget must be >= 0 or None.")
+        if self.max_steps is not None and self.max_steps < 0:
+            raise ValueError("max_steps must be >= 0 or None.")
+        if self.max_state_visits is not None and self.max_state_visits < 1:
+            raise ValueError("max_state_visits must be >= 1 or None.")
+        if self.max_consecutive_tool is not None and self.max_consecutive_tool < 1:
+            raise ValueError("max_consecutive_tool must be >= 1 or None.")
+        self.state = self.machine.initial
+        # The initial state counts as one visit so loop limits include the start.
+        self._state_visits[self.state] = 1
+
+    # -- introspection ----------------------------------------------------
+
+    @property
+    def steps_taken(self) -> int:
+        """Number of accepted steps so far."""
+        return len(self._history)
+
+    @property
+    def history(self) -> tuple[StepRecord, ...]:
+        """Immutable snapshot of accepted steps (oldest first).
+
+        Returned as a tuple so external code can't desync the run by mutating
+        it — the step-limit guard counts from the pilot's own internal record.
+        """
+        return tuple(self._history)
+
+    @property
+    def done(self) -> bool:
+        """``True`` if the pilot is currently in a terminal state."""
+        return self.machine.is_terminal(self.state)
+
+    def allowed_tools(self) -> tuple[str, ...]:
+        """Tools allowed from the current state (empty when terminal)."""
+        return self.machine.allowed_tools(self.state)
+
+    def can(self, tool: str, *, cost: float = 0.0) -> bool:
+        """Return ``True`` if :meth:`step` would currently accept ``tool``.
+
+        Pure check — never mutates state and never raises for a guard violation.
+        (Like :meth:`step`, a negative ``cost`` is a programming error and raises
+        :class:`ValueError` — that is an invalid argument, not a guard decision.)
+        Useful for letting an agent *plan* before acting.
+        """
+        if cost < 0:
+            raise ValueError("cost must be >= 0.")
+        if self.machine.is_terminal(self.state):
+            return False
+        dest = self.machine.resolve(self.state, tool)
+        if dest is None:
+            return False
+        if self.max_steps is not None and self.steps_taken + 1 > self.max_steps:
+            return False
+        if self.budget is not None and self.cost_spent + cost > self.budget + _EPSILON:
+            return False
+        if (
+            self.max_consecutive_tool is not None
+            and tool == self._last_tool
+            and self._consecutive_tool + 1 > self.max_consecutive_tool
+        ):
+            return False
+        return not (
+            self.max_state_visits is not None
+            and self._state_visits.get(dest, 0) + 1 > self.max_state_visits
+        )
+
+    # -- the one method that matters --------------------------------------
+
+    def step(self, tool: str, *, cost: float = 0.0) -> str:
+        """Validate and apply one tool call. Returns the new state.
+
+        Order of checks (fail fast, most fundamental first):
+
+        1. terminal state -> :class:`TransitionError`
+        2. transition allowed? -> :class:`TransitionError`
+        3. step limit -> :class:`StepLimitExceeded`
+        4. budget -> :class:`BudgetExceeded`
+        5. consecutive-tool loop -> :class:`LoopLimitExceeded`
+        6. per-state loop -> :class:`LoopLimitExceeded`
+
+        On success the state advances, cost and counters update, and a
+        :class:`StepRecord` is appended to :attr:`history`. On any violation the
+        pilot's state is left unchanged.
+        """
+        if cost < 0:
+            raise ValueError("cost must be >= 0.")
+
+        source = self.state
+
+        if self.machine.is_terminal(source):
+            raise TransitionError(tool=tool, state=source, allowed=())
+
+        dest = self.machine.resolve(source, tool)
+        if dest is None:
+            raise TransitionError(
+                tool=tool,
+                state=source,
+                allowed=self.machine.allowed_tools(source),
+            )
+
+        next_step_number = self.steps_taken + 1
+        if self.max_steps is not None and next_step_number > self.max_steps:
+            raise StepLimitExceeded(steps=next_step_number, limit=self.max_steps)
+
+        prospective_cost = self.cost_spent + cost
+        if self.budget is not None and prospective_cost > self.budget + _EPSILON:
+            raise BudgetExceeded(spent=self.cost_spent, cost=cost, budget=self.budget)
+
+        prospective_consecutive = (
+            self._consecutive_tool + 1 if tool == self._last_tool else 1
+        )
+        if (
+            self.max_consecutive_tool is not None
+            and prospective_consecutive > self.max_consecutive_tool
+        ):
+            raise LoopLimitExceeded(
+                kind="tool",
+                name=tool,
+                count=prospective_consecutive,
+                limit=self.max_consecutive_tool,
+            )
+
+        prospective_visits = self._state_visits.get(dest, 0) + 1
+        if (
+            self.max_state_visits is not None
+            and prospective_visits > self.max_state_visits
+        ):
+            raise LoopLimitExceeded(
+                kind="state",
+                name=dest,
+                count=prospective_visits,
+                limit=self.max_state_visits,
+            )
+
+        # All guards passed — commit.
+        self.cost_spent = prospective_cost
+        self._consecutive_tool = prospective_consecutive
+        self._last_tool = tool
+        self._state_visits[dest] = prospective_visits
+        self.state = dest
+        record = StepRecord(
+            index=self.steps_taken,
+            tool=tool,
+            source=source,
+            dest=dest,
+            cost=cost,
+            cumulative_cost=self.cost_spent,
+            timestamp=time.time(),
+        )
+        self._history.append(record)
+        return dest
+
+    # -- trace / reset ----------------------------------------------------
+
+    def to_trace(self) -> dict[str, Any]:
+        """Export a JSON-serialisable trace of the whole run.
+
+        Shape::
+
+            {
+              "initial": "<initial state>",
+              "state": "<current state>",
+              "done": <bool>,
+              "steps_taken": <int>,
+              "cost_spent": <float>,
+              "budget": <float | None>,
+              "limits": {"max_steps", "max_state_visits", "max_consecutive_tool"},
+              "history": [ {<StepRecord.to_dict()>}, ... ],
+            }
+        """
+        return {
+            "initial": self.machine.initial,
+            "state": self.state,
+            "done": self.done,
+            "steps_taken": self.steps_taken,
+            "cost_spent": self.cost_spent,
+            "budget": self.budget,
+            "limits": {
+                "max_steps": self.max_steps,
+                "max_state_visits": self.max_state_visits,
+                "max_consecutive_tool": self.max_consecutive_tool,
+            },
+            "history": [record.to_dict() for record in self._history],
+        }
+
+    def reset(self) -> None:
+        """Reset to the initial state, clearing cost, counters and history."""
+        self.state = self.machine.initial
+        self.cost_spent = 0.0
+        self._history.clear()
+        self._state_visits = {self.state: 1}
+        self._last_tool = None
+        self._consecutive_tool = 0

statepilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,339 @@
+Metadata-Version: 2.4
+Name: statepilot
+Version: 0.1.0
+Summary: Deterministic state-machine guards for AI-agent workflows: enforce which tools an agent may call, in which order, with loop detection, cost budgets and step caps.
+Project-URL: Homepage, https://github.com/studiomeyer-io/statepilot
+Project-URL: Repository, https://github.com/studiomeyer-io/statepilot
+Project-URL: Issues, https://github.com/studiomeyer-io/statepilot/issues
+Project-URL: Changelog, https://github.com/studiomeyer-io/statepilot/blob/main/CHANGELOG.md
+Author-email: StudioMeyer <hello@studiomeyer.io>
+License: MIT
+License-File: LICENSE
+Keywords: agent,determinism,guardrails,langgraph,llm,state-machine,workflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# statepilot
+
+**Deterministic state-machine guards for AI-agent workflows.**
+
+Define a state machine, then enforce — at *runtime* — which tools your agent may
+call, in which order, with loop detection, a cost budget, and a hard step cap.
+The agent only gets to do what the state machine allows. Anything else raises.
+
+Zero runtime dependencies in the core. Fully typed. Python 3.10+.
+
+```bash
+pip install statepilot
+```
+
+## The problem
+
+A recurring theme in 2026 agent tooling is "wrap the non-deterministic LLM in
+deterministic code." A few data points that frame the gap:
+
+- **Statewright** (Rust + MCP) put deterministic state machines for agents on the
+  map — it reached the [Hacker News front page](https://news.ycombinator.com/)
+  and lives at <https://github.com/statewright/statewright>. The framing clearly
+  resonates.
+- **llm-canary** ships *policy gates for agent traces* — tool order, cost
+  budgets, runaway-loop checks — but as a **post-hoc test layer** over recorded
+  traces, not as runtime enforcement.
+- Orchestrators like **LangGraph**, **CrewAI** and the **OpenAI Agents SDK** are
+  excellent at *routing*, but they don't hand you a small, hard rule that says
+  "tool X is illegal in state Y, full stop."
+
+The missing piece is a **Python-native runtime guard**: a thin layer you put in
+front of every tool call that enforces the allowed transitions and trips on
+loops and budget overruns. That is what statepilot is.
+
+It does not orchestrate, plan, or call your LLM. It is the bouncer at the door.
+
+## Quickstart (Python builder)
+
+```python
+from statepilot import StateMachine, Pilot
+
+machine = (
+    StateMachine.builder()
+    .initial("research")
+    .transition("research", "research", tool="search")      # looping allowed...
+    .transition("research", "draft", tool="write_draft")
+    .transition("draft", "review", tool="review")
+    .transition("review", "draft", tool="revise")           # send it back
+    .transition("review", "published", tool="publish")
+    .terminal("published")
+    .build()
+)
+
+pilot = Pilot(machine, budget=5.0, max_state_visits=4, max_steps=20)
+
+pilot.step("search", cost=0.5)        # ok, still in "research"
+pilot.step("write_draft", cost=1.0)   # -> "draft"
+pilot.step("review")                  # -> "review"
+pilot.step("publish")                 # -> "published" (terminal)
+
+pilot.step("review")                  # raises TransitionError: terminal state
+```
+
+Every accepted step is recorded:
+
+```python
+for record in pilot.history:
+    print(record.index, record.source, "--", record.tool, "->", record.dest)
+```
+
+## The `@guarded` decorator
+
+Bind your actual tool functions to the pilot. The guard runs **before** the
+function body, so a violation means the body never executes.
+
+```python
+from statepilot import StateMachine, Pilot, guarded, GuardViolation
+
+machine = (
+    StateMachine.builder()
+    .initial("research")
+    .transition("research", "research", tool="search")
+    .transition("research", "draft", tool="write_draft")
+    .terminal("draft")
+    .build()
+)
+pilot = Pilot(machine, budget=5.0)
+
+@guarded(pilot, cost=1.0)                 # tool name defaults to the function name
+def search(query: str) -> list[str]:
+    return real_search(query)
+
+@guarded(pilot, tool="write_draft")       # or name it explicitly
+def make_draft(notes: list[str]) -> str:
+    return real_draft(notes)
+
+search("agent guardrails")                # advances the machine, charges 1.0
+make_draft(["..."])                       # -> "draft"
+
+try:
+    make_draft(["..."])                   # already terminal
+except GuardViolation as exc:
+    print("blocked:", exc)
+```
+
+## YAML definition
+
+Prefer config over code? Define the machine in YAML and load it. (YAML support is
+an optional extra: `pip install statepilot[yaml]`.)
+
+```yaml
+# pipeline.yaml
+initial: research
+terminal:
+  - published
+transitions:
+  - {from: research, to: research, tool: search}
+  - {from: research, to: draft,    tool: write_draft}
+  - {from: draft,    to: review,   tool: review}
+  - {from: review,   to: published, tool: publish}
+```
+
+```python
+from statepilot import StateMachine, Pilot
+
+machine = StateMachine.from_yaml_file("pipeline.yaml")  # from a file
+# or: StateMachine.from_yaml(yaml_string)               # from an inline string
+pilot = Pilot(machine, budget=5.0)
+```
+
+`states` may be omitted — it is inferred from `initial`, `terminal`, and every
+state named in `transitions`. `StateMachine.from_dict(...)` accepts the same
+shape if you already have a dict.
+
+## A realistic agent example
+
+"Research, then draft, then review, then publish. Never publish before review.
+Allow at most 3 research loops. Stop if cost exceeds \$5."
+
+```python
+from statepilot import StateMachine, Pilot, guarded, GuardViolation
+
+machine = (
+    StateMachine.builder()
+    .initial("research")
+    .transition("research", "research", tool="search")
+    .transition("research", "draft", tool="write_draft")
+    .transition("draft", "review", tool="review")
+    .transition("review", "draft", tool="revise")
+    .transition("review", "published", tool="publish")
+    .terminal("published")
+    .build()
+)
+
+# initial visit counts as 1, so max_state_visits=4 allows 3 extra research loops
+pilot = Pilot(machine, budget=5.0, max_state_visits=4, max_steps=25)
+
+@guarded(pilot, cost=0.8)
+def search(q: str) -> str: ...
+
+@guarded(pilot, cost=1.2)
+def write_draft(notes: str) -> str: ...
+
+@guarded(pilot)
+def review(draft: str) -> bool: ...
+
+@guarded(pilot, cost=0.3)
+def publish(draft: str) -> str: ...
+```
+
+The agent loop calls these as it sees fit. statepilot makes the illegal paths
+impossible:
+
+- calling `publish()` while still in `research` -> `TransitionError`
+- a 4th `search()` loop -> `LoopLimitExceeded`
+- cumulative cost over \$5 -> `BudgetExceeded`
+- more than 25 steps -> `StepLimitExceeded`
+
+A runnable version is in [`examples/research_pipeline.py`](examples/research_pipeline.py).
+
+## Why deterministic guards
+
+LLMs are probabilistic. Most of the time the model follows the plan; occasionally
+it calls `publish` before `review`, gets stuck re-searching the same thing, or
+burns the budget. "Most of the time" is not a guarantee, and prompt-only
+constraints are suggestions, not enforcement.
+
+A state machine turns those soft expectations into a hard contract that lives in
+code, runs on every tool call, and is trivial to unit-test. You get:
+
+- **Safety** — illegal tool sequences cannot happen; they raise instead.
+- **Cost control** — a real budget cap, enforced before the expensive call runs.
+- **Loop protection** — runaway repetition trips a clear, typed exception.
+- **Auditability** — `pilot.history` and `pilot.to_trace()` give you a complete,
+  JSON-serialisable record of what the agent actually did.
+
+It is intentionally small. The whole core is a `StateMachine` plus a `Pilot`, and
+the runtime cost is a dict lookup and a few integer comparisons per step.
+
+## API reference
+
+### `StateMachine`
+
+Immutable, validated machine definition. Carries no runtime state.
+
+- `StateMachine.builder(initial=None) -> StateMachineBuilder` — fluent builder.
+- `StateMachine.from_dict(data) -> StateMachine` — build from a mapping.
+- `StateMachine.from_yaml(text) -> StateMachine` — build from an inline YAML
+  string (needs the `yaml` extra).
+- `StateMachine.from_yaml_file(path) -> StateMachine` — build from a YAML file
+  (needs the `yaml` extra).
+- `.to_dict()` — round-trips with `from_dict`.
+- `.allowed_tools(state) -> tuple[str, ...]`
+- `.resolve(state, tool) -> str | None` — destination, or `None` if disallowed.
+- `.is_terminal(state) -> bool`
+
+### `StateMachineBuilder`
+
+- `.initial(state)`, `.state(*states)`, `.transition(src, dest, *, tool)`,
+  `.terminal(*states)`, `.build()`. Every mutator returns `self`.
+
+### `Pilot`
+
+Stateful runtime enforcer. Construct with the machine and optional limits:
+
+```python
+Pilot(
+    machine,
+    budget=None,              # cumulative cost cap
+    max_steps=None,           # total steps cap
+    max_state_visits=None,    # per-state visit cap (initial state counts as 1)
+    max_consecutive_tool=None # same tool back-to-back cap
+)
+```
+
+- `.step(tool, *, cost=0.0) -> str` — validate + apply; returns the new state.
+  Raises on violation; state is unchanged on failure.
+- `.can(tool, *, cost=0.0) -> bool` — pure check, never mutates, never raises.
+- `.allowed_tools() -> tuple[str, ...]`, `.state`, `.done`, `.steps_taken`,
+  `.cost_spent`, `.history`.
+- `.to_trace() -> dict` — JSON-serialisable run trace.
+- `.reset()` — back to the initial state, clears cost/counters/history.
+
+### `@guarded(pilot, *, tool=None, cost=0.0)`
+
+Decorator that calls `pilot.step(...)` before the function body. `tool` defaults
+to the function name.
+
+### Exceptions
+
+```
+StatepilotError
+├── StateMachineError          # invalid machine definition (definition-time)
+└── GuardViolation             # runtime rule broken — catch this for "agent misbehaved"
+    ├── TransitionError        # tool not allowed in the current state
+    ├── LoopLimitExceeded      # state revisited / tool repeated too often
+    ├── BudgetExceeded         # cumulative cost over budget
+    └── StepLimitExceeded      # too many total steps
+```
+
+## LangGraph adapter (experimental)
+
+If you orchestrate with [LangGraph](https://github.com/langchain-ai/langgraph),
+`statepilot.adapters.guard_node` wraps a node so the pilot guards it:
+
+```python
+from statepilot import StateMachine, Pilot
+from statepilot.adapters import guard_node
+# from langgraph.graph import StateGraph
+
+pilot = Pilot(machine, budget=5.0)
+# graph = StateGraph(MyState)
+# graph.add_node("research", guard_node(pilot, research_node, cost=1.0))
+# graph.add_node("draft",    guard_node(pilot, draft_node))
+```
+
+It targets LangGraph's stable *node contract* (a callable `state -> partial
+state dict`) and **never imports langgraph itself**, so it adds no import-time
+dependency and does not break when the LangGraph API changes. It is deliberately
+minimal and marked experimental — conditional edges, `Send` fan-out, and
+checkpoint/resume are out of scope. For full control, just drive the `Pilot`
+inside your own node functions; that path is fully supported.
+
+The adapter needs no extra dependency — it works with any callable. Install
+LangGraph in your own project if you use it.
+
+## Concurrency
+
+A `Pilot` holds the mutable state of **one** agent run and is **not
+thread-safe** — use one pilot per run, don't share it across threads, and call
+`pilot.reset()` to reuse it. `pilot.history` is an immutable snapshot (a tuple),
+so reading or logging it can never desync the run's guards.
+
+## Status
+
+Beta (`0.1.0`). The core API (`StateMachine`, `Pilot`, `@guarded`) is what we
+intend to keep stable. No benchmarks are claimed — the design goal is
+correctness and a tiny footprint, not throughput. Issues and PRs welcome.
+
+## License
+
+MIT © 2026 StudioMeyer. See [LICENSE](LICENSE).

statepilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+statepilot/__about__.py,sha256=XrsPMtJ9XgUU5vqSZ6rEuOaTXXxRsvnBWSZtSL31lDQ,113
+statepilot/__init__.py,sha256=lv7VNi4U_nrHazo6suL5GP6zipi_reWCbjr3-Pyrolc,1652
+statepilot/decorator.py,sha256=UJ4YAC0XZIgHpwA4m2kSCAqm8uMY24BiIp0-TO6II60,1804
+statepilot/exceptions.py,sha256=n8q_uUD6XmEI17GRjIGrVdpSTym9pvVwDPum_MZyCGk,2908
+statepilot/machine.py,sha256=WN4eXHgBV24a65KPprrgV6buGFTvwic0eEWykQTmdRE,12012
+statepilot/pilot.py,sha256=kFuKfpKTzLn6fpIwMzYz7DZCkeq-wJe_eiD5jaKl2vc,10955
+statepilot/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+statepilot/adapters/__init__.py,sha256=fGGtHGgjFf-Bcl3K0UscJmLoGKUw8L3Y19ATetj0PNQ,471
+statepilot/adapters/langgraph.py,sha256=KWoGGTYhwSP7V7bz7ricX-CY3n9C11jxZjtxwft5VIk,2953
+statepilot-0.1.0.dist-info/METADATA,sha256=1le2IIltYP45PONfjdbyD22ip-fGcRGvGUFm1V0eY70,12749
+statepilot-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+statepilot-0.1.0.dist-info/licenses/LICENSE,sha256=R9PjrkWmJX6bZqDuDj_NJtFiNicHKt1rzPB3G_6Vtic,1068
+statepilot-0.1.0.dist-info/RECORD,,

statepilot-0.1.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

statepilot-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StudioMeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.