vention-state-machine 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

state_machine/utils.py

@@ -1,4 +1,6 @@
-from typing import Any, Callable, Union
+from datetime import datetime
+from typing import Any, Callable, Optional, Union
+from pydantic import BaseModel
 from state_machine.defs import StateGroup
 
 
@@ -54,3 +56,27 @@ def is_state_container(state_source: object) -> bool:
         )
     except TypeError:
         return False
+
+
+# Shared schema definitions for REST and RPC endpoints
+# (camelCase aliases applied automatically by registry)
+class StateResponse(BaseModel):
+    state: str
+    last_state: Optional[str] = None
+
+
+class HistoryEntry(BaseModel):
+    timestamp: datetime
+    state: str
+    duration_ms: Optional[int] = None
+
+
+class HistoryResponse(BaseModel):
+    history: list[HistoryEntry]
+    buffer_size: int
+
+
+class TriggerResponse(BaseModel):
+    result: str
+    previous_state: str
+    new_state: str

state_machine/vention_communication.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+import inspect
+from datetime import datetime
+from typing import Any, Callable, Coroutine, Optional, Sequence
+
+from communication.entries import RpcBundle, ActionEntry
+from communication.errors import ConnectError
+from state_machine.core import StateMachine
+from state_machine.utils import (
+    StateResponse,
+    HistoryResponse,
+    HistoryEntry,
+    TriggerResponse,
+)
+
+
+__all__ = ["build_state_machine_rpc_bundle"]
+
+
+def build_state_machine_rpc_bundle(
+    state_machine: StateMachine,
+    *,
+    include_state_actions: bool = True,
+    include_history_action: bool = True,
+    triggers: Optional[Sequence[str]] = None,
+) -> RpcBundle:
+    """
+    Build and return an RpcBundle exposing a StateMachine instance.
+
+    Provides unary RPCs:
+
+      - GetState
+      - GetHistory
+      - Trigger_<TriggerName> (one per trigger)
+
+    For integration via app.extend_bundle(bundle).
+    """
+    bundle = RpcBundle()
+
+    # ======================================================
+    # GetState
+    # ======================================================
+    if include_state_actions:
+
+        async def get_state() -> StateResponse:
+            last = getattr(state_machine, "get_last_state", lambda: None)()
+            return StateResponse(state=state_machine.state, last_state=last)
+
+        bundle.actions.append(
+            ActionEntry(
+                name="GetState",
+                func=get_state,
+                input_type=None,
+                output_type=StateResponse,
+            )
+        )
+
+    # ======================================================
+    # GetHistory
+    # ======================================================
+    if include_history_action:
+
+        async def get_history() -> HistoryResponse:
+            raw = getattr(state_machine, "history", [])
+            out = []
+
+            for item in raw:
+                if isinstance(item, dict):
+                    state_str = str(item.get("state", ""))
+                    duration_ms: Optional[int] = item.get("duration_ms")
+                    if duration_ms is not None and not isinstance(duration_ms, int):
+                        duration_ms = None
+                    timestamp: datetime
+                    if "timestamp" in item and isinstance(item["timestamp"], datetime):
+                        timestamp = item["timestamp"]
+                    else:
+                        timestamp = datetime.now()
+                    out.append(
+                        HistoryEntry(
+                            state=state_str,
+                            timestamp=timestamp,
+                            duration_ms=duration_ms,
+                        )
+                    )
+                else:
+                    out.append(HistoryEntry(state=str(item), timestamp=datetime.now()))
+
+            return HistoryResponse(history=out, buffer_size=len(raw))
+
+        bundle.actions.append(
+            ActionEntry(
+                name="GetHistory",
+                func=get_history,
+                input_type=None,
+                output_type=HistoryResponse,
+            )
+        )
+
+    # ======================================================
+    # Triggers
+    # ======================================================
+    # Source of truth: transitions registered on state machine
+    all_triggers = sorted(state_machine.events.keys())
+    selected = all_triggers if triggers is None else list(triggers)
+
+    # ---------- factory function (fixes closure bug) ----------
+    def make_trigger_handler(
+        trigger_name: str,
+    ) -> Callable[[], Coroutine[Any, Any, TriggerResponse]]:
+        async def trigger_call() -> TriggerResponse:
+            current = state_machine.state
+            allowed = state_machine.get_triggers(current)
+
+            # Precondition error if invalid in current state
+            if trigger_name not in allowed:
+                raise ConnectError(
+                    code="failed_precondition",
+                    message=(
+                        f"Trigger '{trigger_name}' cannot run from '{current}'. "
+                        f"Allowed: {sorted(allowed)}"
+                    ),
+                )
+
+            # Fetch bound trigger method
+            try:
+                method = getattr(state_machine, trigger_name)
+            except AttributeError as e:
+                raise ConnectError(
+                    code="internal",
+                    message=f"StateMachine missing trigger '{trigger_name}'",
+                ) from e
+
+            # Execute trigger (sync or async)
+            try:
+                result = method()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as e:
+                raise ConnectError(
+                    code="internal",
+                    message=f"Trigger '{trigger_name}' failed: {e}",
+                ) from e
+
+            return TriggerResponse(
+                result=trigger_name,
+                previous_state=current,
+                new_state=state_machine.state,
+            )
+
+        return trigger_call
+
+    # ---------- register each trigger ----------
+    for trig in selected:
+        rpc_name = f"Trigger_{trig[0].upper()}{trig[1:]}"  # PascalCase RPC names
+        handler = make_trigger_handler(trig)
+
+        bundle.actions.append(
+            ActionEntry(
+                name=rpc_name,
+                func=handler,
+                input_type=None,
+                output_type=TriggerResponse,
+            )
+        )
+
+    return bundle

{vention_state_machine-0.3.1.dist-info → vention_state_machine-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: vention-state-machine
-Version: 0.3.1
+Version: 0.4.0
 Summary: Declarative state machine framework for machine apps
 License: Proprietary
 Author: VentionCo
@@ -10,11 +10,10 @@ Classifier: Programming Language :: Python :: 3
 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.121.1)
 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)
+Requires-Dist: vention-communication (>=0.2.2,<0.3.0)
 Description-Content-Type: text/markdown
 
 # vention-state-machine
@@ -41,7 +40,7 @@ A lightweight wrapper around `transitions` for building async-safe, recoverable
 - Transition history recording with timestamps + durations
 - Guard conditions for blocking transitions
 - Global state change callbacks for logging/MQTT
-- Optional FastAPI router for HTTP access and visualization
+- Optional RPC bundle for exposing state machine via Connect RPCs
 
 ## 🧠 Concepts & Overview
 
@@ -94,20 +93,20 @@ pip install vention-state-machine
 
 **Optional dependencies:**
 - Graphviz (required for diagram generation)
-- FastAPI (for HTTP exposure of state machine)
+- vention-communication (for RPC bundle integration)
 
 **Install optional tools:**
 
 MacOS:
 ```bash
 brew install graphviz
-pip install fastapi
+pip install vention-communication
 ```
 
 Linux (Debian/Ubuntu)
 ```bash
 sudo apt-get install graphviz
-pip install fastapi
+pip install vention-communication
 ```
 
 
@@ -191,25 +190,37 @@ state_machine.start()
 
 ## 🛠 How-to Guides
 
-### Expose Over HTTP with FastAPI
+### Expose Over RPC with VentionApp
 
 ```python
-from fastapi import FastAPI
-from state_machine.router import build_router
+from communication.app import VentionApp
+from state_machine.vention_communication import build_state_machine_bundle
 from state_machine.core import StateMachine
 
 state_machine = StateMachine(...)
 state_machine.start()
 
-app = FastAPI()
-app.include_router(build_router(state_machine))
+app = VentionApp(name="MyApp")
+bundle = build_state_machine_bundle(state_machine)
+app.register_rpc_plugin(bundle)
+app.finalize()
 ```
 
-**Endpoints:**
-- `GET /state` → Current state
-- `GET /history` → Transition history
-- `POST /<trigger>` → Trigger a transition
-- `GET /diagram.svg` → Graphviz diagram
+**RPC Actions:**
+- `GetState` → Returns current state and last known state
+- `GetHistory` → Returns transition history with timestamps
+- `Trigger_<TriggerName>` → Triggers a state transition (e.g., `Trigger_Start`, `Trigger_Activate`)
+
+**Options:**
+```python
+# Customize which actions are included
+bundle = build_state_machine_bundle(
+    state_machine,
+    include_state_actions=True,  # Include GetState
+    include_history_action=True,  # Include GetHistory
+    triggers=["start", "activate"],  # Only include specific triggers
+)
+```
 
 ### Timeout Example
 
@@ -369,24 +380,28 @@ Guard transition; blocks if function returns False.
 **`@on_state_change`**
 Global callback `(old_state, new_state, trigger)` fired after each transition.
 
-### Router
+### RPC Bundle
 
 ```python
-def build_router(
-    machine: StateMachine,
-    triggers: Optional[list[Trigger]] = None
-) -> fastapi.APIRouter
+def build_state_machine_bundle(
+    sm: StateMachine,
+    *,
+    include_state_actions: bool = True,
+    include_history_action: bool = True,
+    triggers: Optional[Sequence[str]] = None,
+) -> RpcBundle
 ```
 
-Exposes endpoints:
-- `GET /state`
-- `GET /history`
-- `POST /<trigger>`
-- `GET /diagram.svg`
+Builds an RPC bundle exposing the state machine via Connect-style RPCs:
+- `GetState` - Returns current and last known state
+- `GetHistory` - Returns transition history
+- `Trigger_<TriggerName>` - One RPC per trigger (PascalCase naming)
+
+The bundle can be registered with a `VentionApp` using `app.register_rpc_plugin(bundle)`.
 
 ## 🔍 Troubleshooting & FAQ
 
-- **Diagram endpoint returns 503** → Graphviz not installed.
 - **Transitions blocked unexpectedly** → Check guard conditions.
 - **Callbacks not firing** → Only successful transitions trigger them.
 - **State not restored after restart** → Ensure `enable_last_state_recovery=True`.
+- **RPC actions not available** → Ensure `app.finalize()` is called after registering bundles.

{vention_state_machine-0.3.1.dist-info → vention_state_machine-0.4.0.dist-info}/RECORD

@@ -5,8 +5,8 @@ state_machine/decorator_protocols.py,sha256=E6_xflTPxxTqDBa4Dj4p3OdPvR_EW0jA3PAj
 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.3.1.dist-info/METADATA,sha256=EVMmxDmwb67RVbY6N_Ohig5hDLQCCSnOL2M7tSf12DU,10812
-vention_state_machine-0.3.1.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
-vention_state_machine-0.3.1.dist-info/RECORD,,
+state_machine/utils.py,sha256=3eWL63_RAk_Jijh0ZIArBsUF3A7f0vQmwTjDRwRvpIs,2395
+state_machine/vention_communication.py,sha256=BZjHC1SsXFqLiSpX0ChCEGfhkEeitpXmLClZCQIgOrA,5530
+vention_state_machine-0.4.0.dist-info/METADATA,sha256=UlROQZDnqaO5j0AbfJJ2KofpSrrr_woWR8xPWbJY35c,11671
+vention_state_machine-0.4.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+vention_state_machine-0.4.0.dist-info/RECORD,,

{vention_state_machine-0.3.1.dist-info → vention_state_machine-0.4.0.dist-info}/WHEEL

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

state_machine/router.py

@@ -1,181 +0,0 @@
-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,
-    )