vention-state-machine 0.2.1__tar.gz → 0.4__tar.gz

{vention_state_machine-0.2.1 → vention_state_machine-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: vention-state-machine
-Version: 0.2.1
+Version: 0.4
 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.2.1 → vention_state_machine-0.4}/README.md

@@ -22,7 +22,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
 
@@ -75,20 +75,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
 ```
 
 
@@ -172,25 +172,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
 
@@ -350,24 +362,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`.
+- **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.2.1 → vention_state_machine-0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vention-state-machine"
-version = "0.2.1"
+version = "0.4"
 description = "Declarative state machine framework for machine apps"
 authors = [ "VentionCo" ]
 readme = "README.md"
@@ -10,17 +10,12 @@ packages = [{ include = "state_machine", from = "src" }]
 [tool.poetry.dependencies]
 asyncio = "^3.4.3"
 python = ">=3.10,<3.11"
-fastapi = "0.121.1"
 uvicorn = "^0.35.0"
 transitions = "^0.9.3"
 graphviz = "^0.21"
 coverage = "^7.10.1"
-httpx = "^0.28.1"
+vention-communication = "^0.2.2"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.4"
-ruff = "^0.8.0"
-
-[build-system]
-requires = [ "poetry-core>=1.0.0,<2.0.0" ]
-build-backend = "poetry.core.masonry.api"
+ruff = "^0.8.0"

{vention_state_machine-0.2.1 → vention_state_machine-0.4}/src/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

vention_state_machine-0.4/src/state_machine/vention_communication.py

@@ -0,0 +1,170 @@
+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_bundle"]
+
+
+def build_state_machine_bundle(
+    sm: 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(sm, "get_last_state", lambda: None)()
+            return StateResponse(state=sm.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(sm, "history", [])
+            out = []
+
+            for item in raw:
+                if isinstance(item, dict):
+                    # Handle dict items from history
+                    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
+                    # Add timestamp if present, otherwise use current time
+                    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:
+                    # Handle simple state strings
+                    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 SM
+    all_triggers = sorted(sm.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 = sm.state
+            allowed = sm.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(sm, 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=sm.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.2.1/src/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,
-    )