vention-state-machine 0.1.0__py3-none-any.whl

state_machine/core.py

@@ -0,0 +1,303 @@
+# mypy: disable-error-code=misc
+
+import asyncio
+from collections import deque
+from collections.abc import Coroutine
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional, Union, List
+from transitions.extensions import HierarchicalGraphMachine
+from transitions.core import State, Condition
+from state_machine.defs import StateGroup
+from enum import Enum
+from state_machine.decorator_manager import DecoratorManager
+from state_machine.utils import is_state_container
+
+
+class BaseStates(str, Enum):
+    """Base states that all state machines include."""
+
+    READY = "ready"
+    FAULT = "fault"
+
+
+class BaseTriggers(str, Enum):
+    """Base triggers that all state machines include."""
+
+    START = "start"
+    RESET = "reset"
+    TO_FAULT = "to_fault"
+
+
+StateDict = dict[str, object]
+
+
+class StateMachine(HierarchicalGraphMachine):
+    """
+    State Machine wrapping `HierarchicalGraphMachine` with:
+      - Default states: 'ready', 'fault'
+      - Global transitions: 'to_fault', 'reset'
+      - Async task tracking (spawn/cancel)
+      - Auto-timeout support via decorator
+      - Recoverable last-state functionality
+      - Transition history recording
+      - Decorator-based entry/exit hooks
+      - Guard conditions for transitions
+      - Global state change callbacks
+    """
+
+    DEFAULT_HISTORY_SIZE: int = 1000
+
+    def __init__(
+        self,
+        states: Union[object, list[StateDict], None] = None,
+        *,
+        transitions: Optional[list[dict[str, str]]] = None,
+        history_size: Optional[int] = None,
+        enable_last_state_recovery: bool = True,
+        **kw: Any,
+    ) -> None:
+        # Normalize state definitions
+        if is_state_container(states):
+            state_groups = [
+                value
+                for value in vars(states).values()
+                if isinstance(value, StateGroup)
+            ]
+            resolved_states = [group.to_state_list()[0] for group in state_groups]
+        elif isinstance(states, list):
+            resolved_states = states
+        else:
+            raise TypeError(
+                f"`states` must be either a StateGroup container or a list of state dicts. "
+                f"Got: {type(states).__name__}"
+            )
+
+        self._declared_states: list[dict[str, Any]] = resolved_states
+
+        self._decorator_manager = DecoratorManager(self)
+        self._decorator_manager.discover_decorated_handlers(self.__class__)
+
+        # Initialize base machine
+        combined_states = self._declared_states + [
+            BaseStates.READY.value,
+            BaseStates.FAULT.value,
+        ]
+        super().__init__(
+            states=combined_states,
+            transitions=transitions or [],
+            initial="ready",
+            send_event=True,
+            **kw,
+        )
+
+        # Internal tracking
+        self._tasks: set[asyncio.Task[Any]] = set()
+        self._timeouts: dict[str, asyncio.Task[Any]] = {}
+        self._last_state: Optional[str] = None
+        self._enable_recovery: bool = enable_last_state_recovery
+        self._history: deque[dict[str, Any]] = deque(
+            maxlen=history_size or self.DEFAULT_HISTORY_SIZE
+        )
+        self._current_start: Optional[datetime] = None
+        self._guard_conditions: dict[str, List[Callable[[], bool]]] = {}
+        self._state_change_callbacks: List[Callable[[str, str, str], None]] = []
+
+        self._decorator_manager.bind_decorated_handlers(self)
+        self._add_recovery_transitions()
+        self.add_transition(
+            BaseTriggers.TO_FAULT.value,
+            "*",
+            BaseStates.FAULT.value,
+            before="cancel_tasks",
+        )
+        self.add_transition(
+            BaseTriggers.RESET.value, BaseStates.FAULT.value, BaseStates.READY.value
+        )
+        self._attach_after_hooks()
+        self._add_guard_conditions_to_transitions()
+
+    def spawn(self, coro: Coroutine[Any, Any, Any]) -> asyncio.Task[Any]:
+        """
+        Start an async background task and track it for potential cancellation.
+        """
+        task: asyncio.Task[Any] = asyncio.create_task(coro)
+        self._tasks.add(task)
+        task.add_done_callback(lambda _: self._tasks.discard(task))
+        return task
+
+    async def cancel_tasks(self, *_: Any) -> None:
+        """
+        Cancel all tracked background tasks and clear any timeouts.
+        """
+        self._clear_all_timeouts()
+        for task in list(self._tasks):
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+    def set_timeout(
+        self, state_name: str, seconds: float, trigger_fn: Callable[[], str]
+    ) -> None:
+        """
+        Schedule a timeout: if `state_name` remains active after `seconds`, fire `trigger_fn()`.
+        """
+        self._clear_timeout(state_name)
+
+        async def _timeout_task() -> None:
+            await asyncio.sleep(seconds)
+            if self.state == state_name:
+                self.trigger(trigger_fn())
+
+        self._timeouts[state_name] = self.spawn(_timeout_task())
+
+    def _clear_timeout(self, state_name: str) -> None:
+        """Cancel a pending timeout for the given state."""
+        task = self._timeouts.pop(state_name, None)
+        if task:
+            task.cancel()
+
+    def _clear_all_timeouts(self) -> None:
+        """Cancel all pending state timeouts."""
+        for timeout in self._timeouts.values():
+            timeout.cancel()
+        self._timeouts.clear()
+
+    def record_last_state(self) -> None:
+        """Manually record the current state for later recovery."""
+        self._last_state = self.state
+
+    def get_last_state(self) -> Optional[str]:
+        """Get the most recently recorded recoverable state."""
+        return self._last_state
+
+    def start(self) -> None:
+        """
+        Enter the machine: if recovery is enabled and a state was recorded, fire the
+        corresponding recover__ transition; otherwise fire 'start'.
+        """
+        if self._enable_recovery and self._last_state:
+            self.trigger(f"recover__{self._last_state}")
+        else:
+            self.trigger(BaseTriggers.START.value)
+
+    @property
+    def history(self) -> list[dict[str, Any]]:
+        """Get the full transition history with timestamps and durations."""
+        return list(self._history)
+
+    def get_last_history_entries(self, n: int = 10) -> list[dict[str, Any]]:
+        """Get the last `n` history entries."""
+        return list(self._history)[-n:] if n > 0 else []
+
+    def add_transition_condition(
+        self, trigger_name: str, condition_fn: Callable[[], bool]
+    ) -> None:
+        """
+        Add a guard condition to a transition trigger.
+        Multiple conditions can be added for the same trigger - ALL must pass for the transition to be allowed.
+        """
+        if trigger_name not in self._guard_conditions:
+            self._guard_conditions[trigger_name] = []
+        self._guard_conditions[trigger_name].append(condition_fn)
+
+    def add_state_change_callback(
+        self, callback: Callable[[str, str, str], None]
+    ) -> None:
+        """
+        Add a callback that fires on any state change.
+
+        Args:
+            callback: Function that takes (old_state, new_state, trigger_name) as arguments
+        """
+        self._state_change_callbacks.append(callback)
+
+    # -- Private helpers --
+    def _run_enter_callbacks(self, state_name: str) -> None:
+        state_obj = self.get_state(state_name)
+        for callback in getattr(state_obj, "enter", []):
+            callback(None)
+
+    def on_enter_ready(self, _: Any) -> None:
+        if not self._enable_recovery:
+            self._last_state = None
+
+    def _is_leaf(self, state: Union[State, str]) -> bool:
+        state_data = self.get_state(state) if isinstance(state, str) else state
+        return not getattr(state_data, "children", [])
+
+    def _record_history_event(self, event: Any) -> None:
+        now = datetime.now(timezone.utc)
+        dest = event.transition.dest
+        if self._history and self._current_start is not None:
+            elapsed = (now - self._current_start).total_seconds() * 1000
+            self._history[-1]["duration_ms"] = int(elapsed)
+        self._history.append({"timestamp": now, "state": dest})
+        self._current_start = now
+        if self._is_leaf(dest) and dest not in {
+            BaseStates.READY.value,
+            BaseStates.FAULT.value,
+        }:
+            self._last_state = dest
+
+    def _attach_after_hooks(self) -> None:
+        # Attach after hooks to all transitions in all events
+        for _, event in self.events.items():
+            # Loop over all transitions for this event
+            for transitions_for_source in event.transitions.values():
+                # Add our custom callbacks to each transition
+                for transition in transitions_for_source:
+                    transition.add_callback("after", self._record_history_event)
+                    transition.add_callback("after", self._attach_exit_timeout_clear)
+                    transition.add_callback("after", self._notify_state_change_callback)
+
+    def _attach_exit_timeout_clear(self, event: Any) -> None:
+        self._clear_timeout(event.transition.source)
+
+    def _add_recovery_transitions(self) -> None:
+        for state_spec in self._declared_states:
+            parent_name = state_spec["name"]
+            for child_spec in state_spec.get("children", []):
+                full_state_name = f"{parent_name}_{child_spec['name']}"
+                self.add_transition(
+                    f"recover__{full_state_name}",
+                    BaseStates.READY.value,
+                    full_state_name,
+                )
+
+    def _add_guard_conditions_to_transitions(self) -> None:
+        """Add guard conditions to transitions using the transitions library's condition system."""
+        for trigger_name, guard_fns in self._guard_conditions.items():
+            if trigger_name not in self.events:
+                continue
+
+            event = self.events[trigger_name]
+            condition = self._create_guard_condition(guard_fns)
+
+            for transitions_for_source in event.transitions.values():
+                for transition in transitions_for_source:
+                    transition.conditions.append(condition)
+
+    def _create_guard_condition(self, guard_fns: List[Callable[[], bool]]) -> Condition:
+        """Create a condition function for the transitions library."""
+
+        def condition(_: Any) -> bool:
+            for guard_fn in guard_fns:
+                if not guard_fn():
+                    return False
+            return True
+
+        return Condition(condition)
+
+    def _notify_state_change_callback(self, event: Any) -> None:
+        """Notify state change callbacks after successful transition."""
+        trigger_name = event.event.name
+        old_state = event.transition.source
+        new_state = event.transition.dest
+
+        for callback in self._state_change_callbacks:
+            try:
+                callback(old_state, new_state, trigger_name)
+            except Exception as e:
+                print(f"Error in state change callback: {e}")

state_machine/decorator_manager.py

@@ -0,0 +1,102 @@
+from typing import Any, Callable, cast
+from state_machine.utils import wrap_with_timeout
+from state_machine.machine_protocols import (
+    StateMachineProtocol,
+)
+from typing_extensions import TypeAlias
+
+StateCallbackBinding: TypeAlias = tuple[str, str, Any]
+GuardBinding: TypeAlias = tuple[str, Callable[[], bool]]
+StateChangeCallback: TypeAlias = Callable[[str, str, str], None]
+
+
+class DecoratorManager:
+    """
+    Manages discovery and binding of decorator-based lifecycle hooks
+    (`on_enter_state`, `on_exit_state`, `auto_timeout`, `guard`, and `on_state_change`) to a state machine instance.
+    """
+
+    def __init__(self, machine: StateMachineProtocol) -> None:
+        self.machine = machine
+        self._decorator_bindings: list[StateCallbackBinding] = []
+        self._exit_decorator_bindings: list[StateCallbackBinding] = []
+        self._guard_bindings: list[GuardBinding] = []
+        self._state_change_callbacks: list[StateChangeCallback] = []
+
+    def discover_decorated_handlers(self, target_class: type) -> None:
+        """
+        Collect decorated methods from a class definition.
+        You must call this on the class object before instantiating.
+        """
+        for attr in dir(target_class):
+            callback_fn = getattr(target_class, attr, None)
+            if callable(callback_fn):
+                self._discover_state_callbacks(callback_fn)
+                self._discover_guard_conditions(callback_fn)
+                self._discover_state_change_callbacks(callback_fn)
+
+    def _discover_state_callbacks(self, callback_fn: Any) -> None:
+        """Discover on_enter_state and on_exit_state decorators."""
+        if hasattr(callback_fn, "_on_enter_state"):
+            self._decorator_bindings.append(
+                (callback_fn._on_enter_state, "enter", callback_fn)
+            )
+
+        if hasattr(callback_fn, "_on_exit_state"):
+            self._exit_decorator_bindings.append(
+                (callback_fn._on_exit_state, "exit", callback_fn)
+            )
+
+    def _discover_guard_conditions(self, callback_fn: Any) -> None:
+        """Discover guard decorators."""
+        if hasattr(callback_fn, "_guard_conditions"):
+            for trigger_name, guard_fn in callback_fn._guard_conditions.items():
+                self._guard_bindings.append((trigger_name, guard_fn))
+
+    def _discover_state_change_callbacks(self, callback_fn: Any) -> None:
+        """Discover on_state_change decorators."""
+        if hasattr(callback_fn, "_state_change_callback"):
+            state_change_callback = cast(StateChangeCallback, callback_fn)
+            self._state_change_callbacks.append(state_change_callback)
+
+    def bind_decorated_handlers(self, instance: Any) -> None:
+        """
+        After instantiating your class, call this with the instance.
+        Hooks will be registered onto the state machine, and timeouts applied if needed.
+        """
+        self._bind_state_callbacks(instance)
+        self._bind_guard_conditions(instance)
+        self._bind_state_change_callbacks(instance)
+
+    def _bind_state_callbacks(self, instance: Any) -> None:
+        """Bind state entry/exit callbacks."""
+        for state_name, hook_type, callback_fn in (
+            self._decorator_bindings + self._exit_decorator_bindings
+        ):
+            bound_fn = callback_fn.__get__(instance)
+
+            if hook_type == "enter" and hasattr(callback_fn, "_timeout_config"):
+                handler = wrap_with_timeout(
+                    bound_fn,
+                    state_name,
+                    callback_fn._timeout_config,
+                    self.machine.set_timeout,
+                )
+            else:
+                handler = bound_fn
+
+            state_obj = self.machine.get_state(state_name)
+            if state_obj:
+                state_obj.add_callback(hook_type, handler)
+
+    def _bind_guard_conditions(self, instance: Any) -> None:
+        """Bind guard conditions."""
+        for trigger_name, guard_fn in self._guard_bindings:
+            bound_guard = guard_fn.__get__(instance)
+            self.machine.add_transition_condition(trigger_name, bound_guard)
+
+    def _bind_state_change_callbacks(self, instance: Any) -> None:
+        """Bind state change callbacks."""
+        for callback_fn in self._state_change_callbacks:
+            bound_callback = callback_fn.__get__(instance)
+            self.machine.add_state_change_callback(bound_callback)

state_machine/decorator_protocols.py

@@ -0,0 +1,23 @@
+from typing import Protocol, Callable, Any, Union
+
+CallableType = Callable[..., Any]
+
+
+class SupportsGuardConditions(Protocol):
+    _guard_conditions: dict[str, CallableType]
+
+
+class SupportsStateChangeCallback(Protocol):
+    _state_change_callback: bool
+
+
+class SupportsEnterState(Protocol):
+    _on_enter_state: str
+
+
+class SupportsExitState(Protocol):
+    _on_exit_state: str
+
+
+class SupportsTimeoutConfig(Protocol):
+    _timeout_config: tuple[float, Union[str, Callable[[], str]]]

state_machine/decorators.py

@@ -0,0 +1,116 @@
+from typing import Union, Callable, cast
+from .defs import State, Trigger
+from .decorator_protocols import (
+    SupportsGuardConditions,
+    SupportsStateChangeCallback,
+    SupportsEnterState,
+    SupportsExitState,
+    SupportsTimeoutConfig,
+    CallableType,
+)
+
+
+def on_enter_state(
+    state_node: Union[str, State],
+) -> Callable[[CallableType], CallableType]:
+    """
+    Decorator to bind a function to the on-enter hook for a state.
+    Accepts a str or a State descriptor.
+    """
+    if hasattr(state_node, "name"):
+        state_name = state_node.name
+    elif isinstance(state_node, str):
+        state_name = state_node
+    else:
+        raise TypeError(f"Expected a State or str, got {type(state_node)}")
+
+    def decorator(fn: CallableType) -> CallableType:
+        enter_fn: SupportsEnterState = cast(SupportsEnterState, fn)
+        enter_fn._on_enter_state = state_name
+        return fn
+
+    return decorator
+
+
+def on_exit_state(
+    state_node: Union[str, State],
+) -> Callable[[CallableType], CallableType]:
+    """
+    Decorator to bind a function to the on-exit hook for a state.
+    Accepts a str or a State descriptor.
+    """
+    if hasattr(state_node, "name"):
+        state_name = state_node.name
+    elif isinstance(state_node, str):
+        state_name = state_node
+    else:
+        raise TypeError(f"Expected a State or str, got {type(state_node)}")
+
+    def decorator(fn: CallableType) -> CallableType:
+        exit_fn: SupportsExitState = cast(SupportsExitState, fn)
+        exit_fn._on_exit_state = state_name
+        return fn
+
+    return decorator
+
+
+def auto_timeout(
+    seconds: float, trigger: Union[str, Callable[[], str]] = "to_fault"
+) -> Callable[[CallableType], CallableType]:
+    """
+    Decorator that applies an auto-timeout configuration to a state entry handler.
+    """
+
+    def decorator(fn: CallableType) -> CallableType:
+        timeout_fn: SupportsTimeoutConfig = cast(SupportsTimeoutConfig, fn)
+        timeout_fn._timeout_config = (seconds, trigger)
+        return fn
+
+    return decorator
+
+
+def guard(
+    *triggers: Union[str, Trigger],
+) -> Callable[[CallableType], CallableType]:
+    """
+    Decorator to add a guard condition to one or more transition triggers.
+    The decorated function should return a boolean indicating whether the transition is allowed.
+    Accepts multiple str or Trigger descriptors.
+
+    Examples:
+        @guard(Triggers.reset)  # Single trigger
+        @guard(Triggers.reset, Triggers.start)  # Multiple triggers
+        @guard("reset", "start")  # Multiple string triggers
+    """
+
+    def decorator(fn: CallableType) -> CallableType:
+        guard_fn: SupportsGuardConditions = cast(SupportsGuardConditions, fn)
+
+        if not hasattr(guard_fn, "_guard_conditions"):
+            guard_fn._guard_conditions = {}
+
+        for trigger in triggers:
+            trigger_name = (
+                getattr(trigger, "name", trigger)
+                if hasattr(trigger, "name")
+                else trigger
+            )
+            if not isinstance(trigger_name, str):
+                raise TypeError(f"Expected a Trigger or str, got {type(trigger)}")
+
+            guard_fn._guard_conditions[trigger_name] = fn
+
+        return fn
+
+    return decorator
+
+
+def on_state_change(fn: CallableType) -> CallableType:
+    """
+    Decorator to register a global state change callback.
+    The decorated function will be called whenever any state transition occurs.
+    The callback receives (old_state, new_state, trigger_name) as arguments.
+    """
+    callback_fn: SupportsStateChangeCallback = cast(SupportsStateChangeCallback, fn)
+    callback_fn._state_change_callback = True
+    return fn

state_machine/defs.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Union
+
+
+class State:
+    """
+    Descriptor for a single leaf state in a hierarchical state machine.
+
+    On class definition it captures its fully-qualified name, as well as
+    the owning group and member names separately.
+    """
+
+    __slots__ = ("name", "group_name", "member_name")
+
+    def __init__(self) -> None:
+        self.name: str = ""
+        self.group_name: str = ""
+        self.member_name: str = ""
+
+    def __set_name__(self, owner: type, attr_name: str) -> None:
+        self.group_name = owner.__name__
+        self.member_name = attr_name
+        self.name = f"{self.group_name}_{self.member_name}"
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name!r})"
+
+
+class StateGroup:
+    """
+    Base class for grouping related State descriptors.
+
+    Subclass this, declare State fields, and `to_state_list()`
+    will emit exactly the structure transitions needs.
+    """
+
+    def to_state_list(self) -> List[Dict[str, Any]]:
+        """
+        Build a single‐element list of a dict:
+
+          {
+            "name": "<GroupName>",
+            "children": [{"name":"member"}...],
+            "initial": "<member>"
+          }
+
+        transitions will register:
+          <GroupName>_<member>
+        as the leaf states.
+        """
+        children: List[Dict[str, str]] = []
+        for _, descriptor in vars(self.__class__).items():
+            if isinstance(descriptor, State):
+                children.append({"name": descriptor.member_name})
+
+        if not children:
+            raise ValueError(f"{self.__class__.__name__} has no State members")
+
+        initial = children[0]["name"]
+        return [
+            {
+                "name": self.__class__.__name__,
+                "children": children,
+                "initial": initial,
+            }
+        ]
+
+
+class Trigger:
+    """
+    Represents a state machine trigger/event.
+
+    You give it exactly one name; `.transition(...)` then builds
+    the dict transitions wants.
+    """
+
+    __slots__ = ("name",)
+
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.name!r})"
+
+    def __call__(self) -> str:
+        return self.name
+
+    def transition(
+        self, source: Union[str, State], dest: Union[str, State]
+    ) -> Dict[str, str]:
+        """
+        Build {"trigger": self.name, "source": <src>, "dest": <dst>}.
+        `source` / `dest` may be raw strings or StateKey instances.
+        """
+        src = source if isinstance(source, str) else str(source)
+        dst = dest if isinstance(dest, str) else str(dest)
+        return {"trigger": self.name, "source": src, "dest": dst}

state_machine/machine_protocols.py

@@ -0,0 +1,33 @@
+from typing import Protocol, Callable, Any
+
+
+class SupportsTimeout(Protocol):
+    def set_timeout(
+        self, state_name: str, seconds: float, trigger_fn: Callable[[], str]
+    ) -> None: ...
+
+
+class SupportsStateCallbacks(Protocol):
+    def get_state(self, state_name: str) -> Any: ...
+
+
+class SupportsGuardConditions(Protocol):
+    def add_transition_condition(
+        self, trigger_name: str, condition_fn: Callable[[], bool]
+    ) -> None: ...
+
+
+class SupportsStateChangeCallbacks(Protocol):
+    def add_state_change_callback(
+        self, callback: Callable[[str, str, str], None]
+    ) -> None: ...
+
+
+class StateMachineProtocol(
+    SupportsTimeout,
+    SupportsStateCallbacks,
+    SupportsGuardConditions,
+    SupportsStateChangeCallbacks,
+    Protocol,
+):
+    """Combined protocol for state machine interface."""

state_machine/router.py

@@ -0,0 +1,181 @@
+import asyncio
+from datetime import datetime
+from typing import Optional, Sequence, Union, cast
+from fastapi import APIRouter, HTTPException, Response, status
+from typing_extensions import TypedDict, NotRequired
+from state_machine.core import StateMachine
+from state_machine.defs import Trigger
+
+
+# ----------- TypedDict response models -----------
+
+
+class StateResponse(TypedDict):
+    state: str
+    last_state: Optional[str]
+
+
+class HistoryEntry(TypedDict):
+    timestamp: datetime
+    state: str
+    duration_ms: NotRequired[int]
+
+
+class HistoryResponse(TypedDict):
+    history: list[HistoryEntry]
+    buffer_size: int
+
+
+class TriggerResponse(TypedDict):
+    result: str
+    previous_state: str
+    new_state: str
+
+
+# ----------- Router setup -----------
+
+
+def build_router(
+    state_machine: StateMachine,
+    triggers: Optional[Sequence[Union[str, Trigger]]] = None,
+) -> APIRouter:
+    """
+    Create an APIRouter for a given state_machine instance.
+
+    Routes:
+    - GET /state → current state and last known state
+    - GET /history → transition history
+    - POST /<trigger> → trigger transition (e.g., /start)
+    """
+    router = APIRouter()
+
+    _register_basic_routes(router, state_machine)
+    resolved_triggers = _resolve_triggers(state_machine, triggers)
+    for trigger in resolved_triggers:
+        _add_trigger_route(router, state_machine, trigger)
+
+    return router
+
+
+# ----------- Basic routes -----------
+
+
+def _register_basic_routes(router: APIRouter, state_machine: StateMachine) -> None:
+    @router.get("/state", response_model=StateResponse)
+    def get_state() -> StateResponse:
+        """Return current and last known state."""
+        return {
+            "state": state_machine.state,
+            "last_state": state_machine.get_last_state(),
+        }
+
+    @router.get("/history", response_model=HistoryResponse)
+    def get_history(last_n_entries: Optional[int] = None) -> HistoryResponse:
+        """
+        Return transition history. If `last_n_entries` is provided and non-negative,
+        returns only the most recent N entries. Otherwise returns the full buffer.
+        """
+        if last_n_entries is not None and last_n_entries < 0:
+            data = []
+        else:
+            data = (
+                state_machine.get_last_history_entries(last_n_entries)
+                if last_n_entries is not None
+                else state_machine.history
+            )
+        return {
+            "history": cast(list[HistoryEntry], data),
+            "buffer_size": len(state_machine.history),
+        }
+
+    @router.get("/diagram.svg", response_class=Response)
+    def get_svg() -> Response:
+        try:
+            graph = state_machine.get_graph()
+            svg_bytes = graph.pipe(format="svg")
+            return Response(content=svg_bytes, media_type="image/svg+xml")
+        except Exception as e:
+            msg = str(e).lower()
+            if "executable" in msg or "dot not found" in msg or "graphviz" in msg:
+                raise HTTPException(
+                    status_code=503,
+                    detail=(
+                        "Graphviz is required to render the diagram. "
+                        "Install the system package via brew or apt) "
+                    ),
+                )
+            raise
+
+
+# ----------- Trigger resolution -----------
+
+
+def _resolve_triggers(
+    state_machine: StateMachine,
+    triggers: Optional[Sequence[Union[str, Trigger]]],
+) -> list[str]:
+    """Resolve and validate trigger names."""
+    if triggers is None:
+        return sorted(state_machine.events.keys())
+
+    resolved = []
+    for trigger in triggers:
+        trigger_name = trigger.name if isinstance(trigger, Trigger) else trigger
+        if trigger_name not in state_machine.events:
+            raise ValueError(f"Unknown trigger: '{trigger_name}'")
+        resolved.append(trigger_name)
+
+    return resolved
+
+
+# ----------- Trigger route generation -----------
+
+
+def _add_trigger_route(
+    router: APIRouter,
+    state_machine: StateMachine,
+    trigger: str,
+) -> None:
+    """Add a single trigger route to the router."""
+
+    async def trigger_handler() -> TriggerResponse:
+        previous_state = state_machine.state
+
+        available_triggers = state_machine.get_triggers(previous_state)
+        if trigger not in available_triggers:
+            raise HTTPException(
+                status_code=status.HTTP_409_CONFLICT,
+                detail=f"Trigger '{trigger}' not allowed from state '{previous_state}'. "
+                f"Available triggers: {sorted(available_triggers)}",
+            )
+
+        try:
+            method = getattr(state_machine, trigger)
+            result = method()
+            if asyncio.iscoroutine(result):
+                await result
+
+            return {
+                "result": trigger,
+                "previous_state": previous_state,
+                "new_state": state_machine.state,
+            }
+
+        except AttributeError:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Trigger method '{trigger}' not found on state machine",
+            )
+        except Exception as e:
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail=f"Error executing trigger '{trigger}': {str(e)}",
+            )
+
+    router.add_api_route(
+        path=f"/{trigger}",
+        endpoint=trigger_handler,
+        methods=["POST"],
+        name=f"{trigger}_trigger",
+        response_model=TriggerResponse,
+    )

state_machine/utils.py

@@ -0,0 +1,56 @@
+from typing import Any, Callable, Union
+from state_machine.defs import StateGroup
+
+
+def wrap_with_timeout(
+    handler: Callable[[Any], Any],
+    state_name: str,
+    timeout: tuple[float, Union[str, Callable[[], str]]],
+    set_timeout_fn: Callable[[str, float, Callable[[], str]], None],
+) -> Callable[[Any], Any]:
+    """
+    Wraps a state entry handler with timeout behavior.
+
+    Args:
+        handler: The original state entry function to wrap.
+        state_name: The name of the state for which the timeout applies.
+        timeout: A tuple containing (seconds, trigger), where:
+            - seconds: Timeout duration in seconds.
+            - trigger: A string (trigger name) or a function returning a trigger name.
+        set_timeout_fn: A function used to register the timeout with the FSM. Signature:
+            (state_name: str, seconds: float, trigger_fn: () -> str) -> None
+
+    Returns:
+        A new function that sets the timeout and then invokes the original handler.
+    """
+    seconds, trig = timeout
+
+    if isinstance(trig, str):
+
+        def trigger_fn() -> str:
+            return trig
+    elif callable(trig):
+        trigger_fn = trig
+    else:
+        raise TypeError(f"Unsupported trigger type: {type(trig).__name__}")
+
+    def wrapped(event: Any) -> Any:
+        set_timeout_fn(state_name, seconds, trigger_fn)
+        return handler(event)
+
+    return wrapped
+
+
+def is_state_container(state_source: object) -> bool:
+    """
+    Return True if `obj` is an instance or class that contains StateGroup(s).
+    """
+    try:
+        return any(
+            isinstance(value, StateGroup) for value in vars(state_source).values()
+        ) or any(
+            isinstance(value, StateGroup)
+            for value in vars(state_source.__class__).values()
+        )
+    except TypeError:
+        return False

vention_state_machine-0.1.0.dist-info/METADATA

@@ -0,0 +1,295 @@
+Metadata-Version: 2.1
+Name: vention-state-machine
+Version: 0.1.0
+Summary: Declarative state machine framework for machine apps
+License: Proprietary
+Author: VentionCo
+Requires-Python: >=3.9,<3.11
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: asyncio (>=3.4.3,<4.0.0)
+Requires-Dist: coverage (>=7.10.1,<8.0.0)
+Requires-Dist: fastapi (>=0.116.1,<0.117.0)
+Requires-Dist: graphviz (>=0.21,<0.22)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: transitions (>=0.9.3,<0.10.0)
+Requires-Dist: uvicorn (>=0.35.0,<0.36.0)
+Description-Content-Type: text/markdown
+
+# vention-state-machine
+
+A lightweight wrapper around `transitions` for building async-safe, recoverable hierarchical state machines with minimal boilerplate.
+
+## ✨ Features
+
+- Built-in `ready` / `fault` states
+- Global transitions: `to_fault`, `reset`
+- Optional state recovery (`recover__state`)
+- Async task spawning and cancellation
+- Timeouts and auto-fault handling
+- Transition history recording with timestamps + durations
+- Guard conditions for blocking transitions
+- Global state change callbacks for logging/MQTT
+
+## 🧠 Domain-Specific Language
+
+This library uses a **declarative domain-specific language (DSL)** to define state machines in a readable and structured way. The key building blocks are:
+
+- **`State`**: Represents a single leaf node in the state machine. Declared as a class attribute.
+    
+- **`StateGroup`**: A container for related states. It generates a hierarchical namespace for its child states (e.g. `MyGroup.my_state` becomes `"MyGroup_my_state"`).
+    
+- **`Trigger`**: Defines a named event that can cause state transitions. It is both callable (returns its name as a string) and composable (can generate transition dictionaries via `.transition(...)`).
+    
+This structure allows you to define states and transitions with strong typing and full IDE support — without strings scattered across your codebase.
+
+For Example: 
+```python
+class MyStates(StateGroup):
+    idle: State = State()
+    working: State = State()
+
+class Triggers:
+    begin = Trigger("begin")
+    finish = Trigger("finish")
+```
+You can then define transitions declaratively:
+```python
+TRANSITIONS = [
+    Triggers.finish.transition(MyStates.working, MyStates.idle),
+]
+```
+
+## 🧱 Base States and Triggers
+
+Every machine comes with built-in:
+
+- **States**:
+  - `ready`: initial state
+  - `fault`: global error state
+- **Triggers**:
+  - `start`: transition into the first defined state
+  - `to_fault`: jump to fault from any state
+  - `reset`: recover from fault back to ready
+
+You can reference these via:
+
+```python
+from state_machine.core import BaseStates, BaseTriggers
+
+state_machine.trigger(BaseTriggers.RESET.value)
+assert state_machine.state == BaseStates.READY.value
+```
+
+## 🚀 Quick Start
+### 1. Define Your States and Triggers
+
+```python
+from state_machine.defs import StateGroup, State, Trigger
+
+class Running(StateGroup):
+	picking: State = State()
+	placing: State = State()
+	homing: State = State()
+
+class States:
+	running = Running()
+
+class Triggers:
+	start = Trigger("start")
+	finished_picking = Trigger("finished_picking")
+	finished_placing = Trigger("finished_placing")
+	finished_homing = Trigger("finished_homing")
+	to_fault = Trigger("to_fault")
+	reset = Trigger("reset")
+```
+
+### 2. Define Transitions
+```python
+TRANSITIONS  = [
+	Triggers.start.transition("ready", States.running.picking),
+	Triggers.finished_picking.transition(States.running.picking, States.running.placing),
+	Triggers.finished_placing.transition(States.running.placing, States.running.homing),
+	Triggers.finished_homing.transition(States.running.homing, States.running.picking)
+]
+```
+
+### 3. Implement Your State Machine
+
+```python
+from state_machine.core import StateMachine
+
+from state_machine.decorators import on_enter_state, auto_timeout, guard, on_state_change
+
+class CustomMachine(StateMachine):
+
+def __init__(self):
+	super().__init__(states=States, transitions=TRANSITIONS)
+
+	# Automatically trigger to_fault after 5s if no progress
+	@on_enter_state(States.running.picking)
+	@auto_timeout(5.0, Triggers.to_fault)
+	def enter_picking(self, _):
+		print("🔹 Entering picking")
+
+	@on_enter_state(States.running.placing)
+	def enter_placing(self, _):
+		print("🔸 Entering placing")
+		
+	@on_enter_state(States.running.homing)
+	def enter_homing(self, _):
+		print("🔺 Entering homing")
+
+	# Guard condition - only allow reset when safety conditions are met
+	@guard(Triggers.reset)
+	def check_safety_conditions(self) -> bool:
+		"""Only allow reset when estop is not pressed."""
+		return not self.estop_pressed
+
+	# Global state change callback for MQTT publishing
+	@on_state_change
+	def publish_state_to_mqtt(self, old_state: str, new_state: str, trigger: str):
+		"""Publish state changes to MQTT."""
+		mqtt_client.publish("machine/state", {
+		    "old_state": old_state,
+		    "new_state": new_state,
+		    "trigger": trigger
+		})
+```
+
+### 4. Start It
+```python
+state_machine = StateMachine()
+state_machine.start() # Enters last recorded state (if recovery enabled), else first state
+```
+
+## 🌐 Optional FastAPI Router
+This library provides a FastAPI-compatible router that automatically exposes your state machine over HTTP. This is useful for:
+
+- Triggering transitions via HTTP POST
+- Inspecting current state and state history
+ #### Example
+ ```python
+from fastapi import FastAPI
+from state_machine.router import build_router
+from state_machine.core import StateMachine
+
+state_machine = StateMachine(...)
+state_machine.start()
+
+app = FastAPI()
+app.include_router(build_router(state_machine))
+```
+
+### Available Routes
+* `GET /state`: Returns current and last known state
+* `GET /history`: Returns list of recent state transitions
+* `POST /<trigger_name>`: Triggers a transition by name
+
+You can expose only a subset of triggers by passing them explicitly:
+```python
+from state_machine.defs import Trigger
+# Only create endpoints for 'start' and 'reset'
+router = build_router(state_machine, triggers=[Trigger("start"), Trigger("reset")])
+```
+
+## Diagram Visualization
+
+- `GET /diagram.svg`: Returns a Graphviz-generated SVG of the state machine.
+- Current state is highlighted in red.
+- Previous state and the transition taken are highlighted in blue.
+- Requires Graphviz installed on the system. If Graphviz is missing, the endpoint returns 503 Service Unavailable.
+
+Example usage:
+```bash
+curl http://localhost:8000/diagram.svg > machine.svg
+open machine.svg
+```
+
+## 🧪 Testing & History
+-  `state_machine.history`: List of all transitions with timestamps and durations
+-  `state_machine.last(n)`: Last `n` transitions
+-  `state_machine.record_last_state()`: Manually record current state for later recovery
+-  `state_machine.get_last_state()`: Retrieve recorded state
+  
+## ⏲ Timeout Example
+Any `on_enter_state` method can be wrapped with `@auto_timeout(seconds, trigger_fn)`, e.g.:
+
+```python
+@auto_timeout(5.0, Triggers.to_fault)
+```
+This automatically triggers `to_fault()` if the state remains active after 5 seconds.
+
+## 🔁 Recovery Example
+Enable `enable_last_state_recovery=True` and use:
+```python
+state_machine.start()
+```
+If a last state was recorded, it will trigger `recover__{last_state}` instead of `start`.
+
+## 🧩 How Decorators Work
+
+Decorators attach metadata to your methods:
+
+- `@on_enter_state(state)` binds to the state's entry callback
+- `@on_exit_state(state)` binds to the state's exit callback
+- `@auto_timeout(seconds, trigger)` schedules a timeout once the state is entered
+- `@guard(trigger)` adds a condition that must be true for the transition to proceed
+- `@on_state_change` registers a global callback that fires on every state transition
+
+The library automatically discovers and wires these up when your machine is initialized.
+
+## 🛡️ Guard Conditions
+
+Guard conditions allow you to block transitions based on runtime conditions. They can be applied to single or multiple triggers:
+
+```python
+# Single trigger
+@guard(Triggers.reset)
+def check_safety_conditions(self) -> bool:
+    """Only allow reset when estop is not pressed."""
+    return not self.estop_pressed
+
+# Multiple triggers - same guard applies to both
+@guard(Triggers.reset, Triggers.start)
+def check_safety_conditions(self) -> bool:
+    """Check safety conditions for both reset and start."""
+    return not self.estop_pressed and self.safety_system_ok
+
+# Multiple guard functions for the same trigger - ALL must pass
+@guard(Triggers.reset)
+def check_estop(self) -> bool:
+    return not self.estop_pressed
+
+@guard(Triggers.reset)
+def check_safety_system(self) -> bool:
+    return self.safety_system_ok
+```
+
+If any guard function returns `False`, the transition is blocked and the state machine remains in its current state. When multiple guard functions are applied to the same trigger, **ALL conditions must pass** for the transition to be allowed.
+
+## 📡 State Change Callbacks
+
+Global state change callbacks are perfect for logging, MQTT publishing, or other side effects. They fire after every successful state transition:
+
+```python
+@on_state_change
+def publish_to_mqtt(self, old_state: str, new_state: str, trigger: str) -> None:
+    """Publish state changes to MQTT."""
+    mqtt_client.publish("machine/state", {
+        "old_state": old_state,
+        "new_state": new_state,
+        "trigger": trigger,
+        "timestamp": datetime.now().isoformat()
+    })
+
+@on_state_change
+def log_transitions(self, old_state: str, new_state: str, trigger: str) -> None:
+    """Log all state transitions."""
+    print(f"State change: {old_state} -> {new_state} (trigger: {trigger})")
+```
+
+Multiple state change callbacks can be registered and they will all be called in the order they were defined. Callbacks only fire on **successful transitions** - blocked transitions (due to guard conditions) do not trigger callbacks.
+```

vention_state_machine-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+state_machine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+state_machine/core.py,sha256=lAiGGPtWCiYQPCh1iz3P26YFrz8VvveIGlL5k2AFvKs,11201
+state_machine/decorator_manager.py,sha256=uHhbtR1vS7idcn4kJsaNtJ1Z_7kiHf9YVa_cxkb-WNk,4420
+state_machine/decorator_protocols.py,sha256=E6_xflTPxxTqDBa4Dj4p3OdPvR_EW0jA3PAjHTDlG8c,485
+state_machine/decorators.py,sha256=V-KBJ6fSvINi7JHN_VmrQLTnOxGPy5iRV5QzXLKwWDw,3668
+state_machine/defs.py,sha256=eYtkTqRMm89ZHFKs3p7H3HyGNZbrOnoCzAJbSeMxSDg,2836
+state_machine/machine_protocols.py,sha256=Yxs4aw2-NJ1RluygbthsquVKn35-xMYae7PB7xlqQmE,826
+state_machine/router.py,sha256=tRJyigrGpQo99_dWGdZ-ZirN50s0CbQF_v4kjAXlpWk,5560
+state_machine/utils.py,sha256=z58CBQCsFWwJzPn8ZhoB2y1K2BH8UP7OZ8XaUx9etN8,1833
+vention_state_machine-0.1.0.dist-info/METADATA,sha256=S4sUnTNdkmoY9CmOu4CinhzcTa8Pw6UuELzcO1Sr-oY,9972
+vention_state_machine-0.1.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+vention_state_machine-0.1.0.dist-info/RECORD,,

vention_state_machine-0.1.0.dist-info/WHEEL

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