piphi-runtime-kit-python 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

piphi_runtime_kit_python/__init__.py

@@ -6,8 +6,10 @@ from .automations import (
     AutomationContractReport,
     AutomationEventDefinition,
     AutomationIdempotencyStore,
+    AutomationIdempotencyClaimStore,
     AutomationRegistry,
     InMemoryAutomationIdempotencyStore,
+    SQLiteAutomationIdempotencyStore,
     assert_behaviors_contract,
     audit_behaviors_contract,
     build_mock_automation_event,
@@ -160,8 +162,10 @@ __all__ = [
     "AutomationContractReport",
     "AutomationEventDefinition",
     "AutomationIdempotencyStore",
+    "AutomationIdempotencyClaimStore",
     "AutomationRegistry",
     "InMemoryAutomationIdempotencyStore",
+    "SQLiteAutomationIdempotencyStore",
     "BackgroundTaskLimitError",
     "ConfigSyncCoordinator",
     "CoreAuthError",

piphi_runtime_kit_python/automations.py

@@ -10,8 +10,11 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Awaitable, Callable, Mapping
+from contextlib import closing
 from dataclasses import dataclass
-from typing import Any, Literal, Protocol, TypeAlias
+from pathlib import Path
+import sqlite3
+from typing import Any, Literal, Protocol, TypeAlias, runtime_checkable
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -99,6 +102,15 @@ class AutomationIdempotencyStore(Protocol):
     async def put(self, key: str, result: AutomationActionResult) -> None: ...
 
 
+@runtime_checkable
+class AutomationIdempotencyClaimStore(AutomationIdempotencyStore, Protocol):
+    """Store that atomically claims keys across processes before side effects."""
+
+    async def claim(self, key: str) -> bool: ...
+
+    async def release(self, key: str) -> None: ...
+
+
 class InMemoryAutomationIdempotencyStore:
     """Process-local idempotency store for development and tests.
 
@@ -118,6 +130,111 @@ class InMemoryAutomationIdempotencyStore:
         self._results[key] = result.model_copy(deep=True)
 
 
+class SQLiteAutomationIdempotencyStore:
+    """Durable, process-safe action claim ledger backed by SQLite.
+
+    A key is inserted as ``dispatching`` before the handler runs. A second
+    process cannot claim the same key. Terminal outcomes are replayed, while a
+    surviving ``dispatching`` row is treated as an ambiguous earlier attempt
+    and is never silently executed again.
+    """
+
+    def __init__(self, path: str | Path) -> None:
+        self.path = str(Path(path).expanduser().resolve())
+        Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self.path, timeout=5.0)
+        connection.execute("PRAGMA busy_timeout = 5000")
+        return connection
+
+    def _initialize(self) -> None:
+        with closing(self._connect()) as connection, connection:
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS automation_action_delivery (
+                    action_key TEXT PRIMARY KEY,
+                    status TEXT NOT NULL,
+                    result_json TEXT,
+                    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
+
+    async def claim(self, key: str) -> bool:
+        return await asyncio.to_thread(self._claim_sync, key)
+
+    def _claim_sync(self, key: str) -> bool:
+        with closing(self._connect()) as connection, connection:
+            cursor = connection.execute(
+                """
+                INSERT OR IGNORE INTO automation_action_delivery
+                    (action_key, status)
+                VALUES (?, 'dispatching')
+                """,
+                (key,),
+            )
+            return cursor.rowcount == 1
+
+    async def get(self, key: str) -> AutomationActionResult | None:
+        return await asyncio.to_thread(self._get_sync, key)
+
+    def _get_sync(self, key: str) -> AutomationActionResult | None:
+        with closing(self._connect()) as connection:
+            row = connection.execute(
+                """
+                SELECT status, result_json
+                FROM automation_action_delivery
+                WHERE action_key = ?
+                """,
+                (key,),
+            ).fetchone()
+        if row is None:
+            return None
+        status, result_json = row
+        if status == "dispatching":
+            return AutomationActionResult.failure(
+                "An earlier action attempt may still have reached the device; manual review is required",
+                retryable=False,
+                metadata={"delivery_status": "ambiguous"},
+            )
+        if not result_json:
+            return None
+        return AutomationActionResult.model_validate_json(result_json)
+
+    async def put(self, key: str, result: AutomationActionResult) -> None:
+        await asyncio.to_thread(self._put_sync, key, result)
+
+    def _put_sync(self, key: str, result: AutomationActionResult) -> None:
+        with closing(self._connect()) as connection, connection:
+            connection.execute(
+                """
+                INSERT INTO automation_action_delivery
+                    (action_key, status, result_json, updated_at)
+                VALUES (?, 'terminal', ?, CURRENT_TIMESTAMP)
+                ON CONFLICT(action_key) DO UPDATE SET
+                    status = 'terminal',
+                    result_json = excluded.result_json,
+                    updated_at = CURRENT_TIMESTAMP
+                """,
+                (key, result.model_dump_json()),
+            )
+
+    async def release(self, key: str) -> None:
+        await asyncio.to_thread(self._release_sync, key)
+
+    def _release_sync(self, key: str) -> None:
+        with closing(self._connect()) as connection, connection:
+            connection.execute(
+                """
+                DELETE FROM automation_action_delivery
+                WHERE action_key = ? AND status = 'dispatching'
+                """,
+                (key,),
+            )
+
+
 @dataclass(frozen=True, slots=True)
 class AutomationActionDefinition:
     command: str
@@ -264,9 +381,30 @@ class AutomationRegistry:
                 cached = await self.idempotency_store.get(scoped_key)
                 if cached is not None:
                     return cached.model_copy(update={"replayed": True})
+                claim_store = (
+                    self.idempotency_store
+                    if isinstance(
+                        self.idempotency_store,
+                        AutomationIdempotencyClaimStore,
+                    )
+                    else None
+                )
+                if claim_store is not None and not await claim_store.claim(scoped_key):
+                    claimed_result = await claim_store.get(scoped_key)
+                    return (
+                        claimed_result.model_copy(update={"replayed": True})
+                        if claimed_result is not None
+                        else AutomationActionResult.failure(
+                            "The action idempotency key is already being processed",
+                            retryable=False,
+                            metadata={"delivery_status": "ambiguous"},
+                        )
+                    )
                 result = await self._invoke(registered[1], action_request)
                 if result.ok or not result.retryable:
                     await self.idempotency_store.put(scoped_key, result)
+                elif claim_store is not None:
+                    await claim_store.release(scoped_key)
                 return result
         return await self._invoke(registered[1], action_request)
 

{piphi_runtime_kit_python-0.7.0.dist-info → piphi_runtime_kit_python-0.7.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.7.0
+Version: 0.7.1
 Summary: PiPhi Network runtime integration helpers
 Keywords: piphi,runtime,integration,iot
 Author-Email: KelvinSan <support@piphi.network>
@@ -34,7 +34,7 @@ plumbing without hiding the HTTP contract behind a large framework. The goal
 is to help developers move faster while still understanding what their runtime
 is doing.
 
-Version `0.7.0` is the current documented baseline.
+Version `0.7.1` is the current documented baseline.
 
 > New to PiPhi? Start with [First 15 Minutes](#first-15-minutes), then read [The Golden Path](#the-golden-path), then compare your code to the example app.
 
@@ -188,12 +188,13 @@ command with `AutomationRegistry`:
 from piphi_runtime_kit_python import (
     AutomationActionRequest,
     AutomationRegistry,
-    InMemoryAutomationIdempotencyStore,
+    SQLiteAutomationIdempotencyStore,
 )
 
 automations = AutomationRegistry(
-    # Development/tests only. Use a durable store for production side effects.
-    idempotency_store=InMemoryAutomationIdempotencyStore(),
+    idempotency_store=SQLiteAutomationIdempotencyStore(
+        "/data/piphi/automation-actions.sqlite3"
+    ),
 )
 
 @automations.action("set_fan_speed", label="Set fan speed")
@@ -205,8 +206,9 @@ async def set_fan_speed(request: AutomationActionRequest) -> dict[str, int]:
 
 Core supplies a stable idempotency key for each action. Integrations that
 change a device or external service must persist terminal results in a durable
-`AutomationIdempotencyStore`; the included in-memory store is deliberately for
-tests and local development only.
+`AutomationIdempotencyStore`. The SQLite implementation atomically claims keys
+across local runtime processes; the in-memory store is deliberately for tests
+and local development only.
 
 For the complete FastAPI wiring, event publishing, contract audit, and mock
 event testing patterns, read [Building automation-capable integrations](docs/automations.md)

{piphi_runtime_kit_python-0.7.0.dist-info → piphi_runtime_kit_python-0.7.1.dist-info}/RECORD

@@ -1,11 +1,11 @@
-piphi_runtime_kit_python-0.7.0.dist-info/METADATA,sha256=BwOlIggxC3uZuVxEtfw6eTmbZW29Df_OfBXoG3xyIyg,36458
-piphi_runtime_kit_python-0.7.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
-piphi_runtime_kit_python-0.7.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-piphi_runtime_kit_python-0.7.0.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
-piphi_runtime_kit_python/__init__.py,sha256=9IEH3g4lIeGeJCnCmQqJbfjBuq_EmsFfmK61UwelDDA,8024
+piphi_runtime_kit_python-0.7.1.dist-info/METADATA,sha256=tGubJnlnCSLE74rqkMbf7TL9tVLVrUEvvEDYA1GEXH8,36501
+piphi_runtime_kit_python-0.7.1.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+piphi_runtime_kit_python-0.7.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+piphi_runtime_kit_python-0.7.1.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
+piphi_runtime_kit_python/__init__.py,sha256=c0UP0yoq03cdAvd-o-KzlGjA2CmxruuDGQFZ9fQKScY,8178
 piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
 piphi_runtime_kit_python/adapters/fastapi.py,sha256=6sAEqJLKM_p4CYt3WB5VLsylXlyhe4v3GxBQawO4rps,3078
-piphi_runtime_kit_python/automations.py,sha256=aQN19M3wAH9AH2qw5JOoEmPrTtAX55u8QiKmMno5odI,15053
+piphi_runtime_kit_python/automations.py,sha256=wA5BMG-4Zkv1rjE0MKVcW6tPx4DIhz3vHKoVvmBGMO4,20489
 piphi_runtime_kit_python/fastapi.py,sha256=xvHU19-CVDPKjmXW6nW72mpdbJEOLZzT8Twal7lCCkc,453
 piphi_runtime_kit_python/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 piphi_runtime_kit_python/runtime/__init__.py,sha256=cVJj6eniXw9oM_H795vVhVyI1c_dYrcZ-eYQgbT4LE4,4081
@@ -27,4 +27,4 @@ piphi_runtime_kit_python/runtime/state.py,sha256=OIwVxAzX2ErsZ2XdrWlIP5r3GHHub5y
 piphi_runtime_kit_python/runtime/tasks.py,sha256=E9WoE75NQiJp3buJYexysl3NuP8HJHJ3KfaGVKLdiw0,3238
 piphi_runtime_kit_python/runtime/telemetry.py,sha256=vV8f1SY4zD-YjVNZWGl3UdCAEYYxFzaPiSNJ7iFBDNI,6729
 piphi_runtime_kit_python/schemas.py,sha256=Dq6PVJxA2rOIt9rEKopHlmRfZujpnVfZIWYzW1uc3iw,10458
-piphi_runtime_kit_python-0.7.0.dist-info/RECORD,,
+piphi_runtime_kit_python-0.7.1.dist-info/RECORD,,