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

piphi_runtime_kit_python/__init__.py

@@ -1,3 +1,19 @@
+from .automations import (
+    AutomationActionDefinition,
+    AutomationActionRequest,
+    AutomationActionResult,
+    AutomationClient,
+    AutomationContractReport,
+    AutomationEventDefinition,
+    AutomationIdempotencyStore,
+    AutomationIdempotencyClaimStore,
+    AutomationRegistry,
+    InMemoryAutomationIdempotencyStore,
+    SQLiteAutomationIdempotencyStore,
+    assert_behaviors_contract,
+    audit_behaviors_contract,
+    build_mock_automation_event,
+)
 from .runtime.auth import (
     RUNTIME_CONTAINER_ID_HEADER_NAME,
     RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
@@ -139,6 +155,17 @@ from .schemas import (
 )
 
 __all__ = [
+    "AutomationActionDefinition",
+    "AutomationActionRequest",
+    "AutomationActionResult",
+    "AutomationClient",
+    "AutomationContractReport",
+    "AutomationEventDefinition",
+    "AutomationIdempotencyStore",
+    "AutomationIdempotencyClaimStore",
+    "AutomationRegistry",
+    "InMemoryAutomationIdempotencyStore",
+    "SQLiteAutomationIdempotencyStore",
     "BackgroundTaskLimitError",
     "ConfigSyncCoordinator",
     "CoreAuthError",
@@ -193,6 +220,7 @@ __all__ = [
     "IntegrationEventIngestResponse",
     "IntegrationEventListResponse",
     "build_runtime_config_snapshot_from_core_rows",
+    "build_mock_automation_event",
     "build_discovery_response",
     "classify_core_delivery_error",
     "build_core_event_payload",
@@ -241,6 +269,8 @@ __all__ = [
     "resolve_device_id",
     "validate_typed_config",
     "validate_typed_configs",
+    "assert_behaviors_contract",
+    "audit_behaviors_contract",
     "DEFAULT_SOURCE_TOPIC_PREFIX",
     "build_source_errors_topic",
     "build_source_model_packets_topic",

piphi_runtime_kit_python/adapters/fastapi.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any, Mapping
 
+from ..automations import AutomationActionResult, AutomationRegistry
 from ..runtime.auth import RuntimeAuthHeaders
 from ..runtime.context import RuntimeContext
 
@@ -11,6 +12,31 @@ if TYPE_CHECKING:
     from fastapi import Request
 
 
+async def dispatch_automation_action_from_fastapi(
+    registry: AutomationRegistry,
+    request: "Request",
+    payload: object | Mapping[str, Any],
+) -> AutomationActionResult:
+    """Dispatch a Core command while preserving its stable idempotency key.
+
+    The key is accepted from the canonical header first and then from the JSON
+    payload for compatibility with runtimes that proxy requests internally.
+    """
+    payload_data = (
+        dict(payload)
+        if isinstance(payload, Mapping)
+        else payload.model_dump(mode="python")
+        if hasattr(payload, "model_dump")
+        else dict(vars(payload))
+    )
+    header_key = str(request.headers.get("X-PiPhi-Idempotency-Key") or "").strip()
+    payload_key = str(payload_data.get("idempotency_key") or "").strip()
+    return await registry.dispatch(
+        payload_data,
+        idempotency_key=header_key or payload_key or None,
+    )
+
+
 def get_payload_container_id(
     payload: object | Mapping[str, Any] | None,
     *,

piphi_runtime_kit_python/automations.py

@@ -0,0 +1,554 @@
+"""Typed automation helpers for PiPhi integration runtimes.
+
+``behaviors.json`` remains the declarative catalog consumed by Core and the
+builders.  This module implements the runtime half of that contract: emitting
+declared events, dispatching declared actions, preserving idempotency keys, and
+checking that runtime handlers match the published behavior schema.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Mapping
+from contextlib import closing
+from dataclasses import dataclass
+from pathlib import Path
+import sqlite3
+from typing import Any, Literal, Protocol, TypeAlias, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .runtime.auth import RuntimeAuthContext
+from .runtime.events import EventClient, build_core_event_payload
+from .runtime.identity import RuntimeDeviceRef
+from .schemas import CoreEventPayload, EventSeverity
+
+class AutomationActionRequest(BaseModel):
+    """Normalized action request received from PiPhi Core."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    command: str = Field(min_length=1)
+    args: dict[str, Any] = Field(default_factory=dict)
+    idempotency_key: str | None = None
+    command_id: str | None = None
+    correlation_id: str | None = None
+    integration_id: str | None = None
+    config_id: str | None = None
+    container_id: str | None = None
+    device_id: str | None = None
+    entity_id: str | None = None
+    capability_id: str | None = None
+    run_id: str | None = None
+    node_id: str | None = None
+
+
+class AutomationActionResult(BaseModel):
+    """Structured result returned by an automation action handler."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: Literal["success", "failed"]
+    result: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    retryable: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    replayed: bool = False
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "success"
+
+    @classmethod
+    def success(
+        cls,
+        result: Mapping[str, Any] | None = None,
+        **values: Any,
+    ) -> "AutomationActionResult":
+        payload = dict(result or {})
+        payload.update(values)
+        return cls(status="success", result=payload)
+
+    @classmethod
+    def failure(
+        cls,
+        error: str,
+        *,
+        retryable: bool = False,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> "AutomationActionResult":
+        return cls(
+            status="failed",
+            error=str(error),
+            retryable=retryable,
+            metadata=dict(metadata or {}),
+        )
+
+
+AutomationHandlerValue: TypeAlias = (
+    AutomationActionResult | Mapping[str, Any] | None
+)
+AutomationActionHandler: TypeAlias = Callable[
+    [AutomationActionRequest],
+    AutomationHandlerValue | Awaitable[AutomationHandlerValue],
+]
+
+
+class AutomationIdempotencyStore(Protocol):
+    """Persistence contract for action results keyed by Core idempotency key."""
+
+    async def get(self, key: str) -> AutomationActionResult | None: ...
+
+    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.
+
+    Production runtimes should provide a durable implementation when an action
+    changes external state. Core supplies a stable key, but the runtime owns the
+    device-side effect and therefore must persist the final outcome.
+    """
+
+    def __init__(self) -> None:
+        self._results: dict[str, AutomationActionResult] = {}
+
+    async def get(self, key: str) -> AutomationActionResult | None:
+        result = self._results.get(key)
+        return result.model_copy(deep=True) if result else None
+
+    async def put(self, key: str, result: AutomationActionResult) -> None:
+        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
+    label: str
+    parameter_schema: Mapping[str, Any]
+    result_schema: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AutomationEventDefinition:
+    event_type: str
+    label: str
+    data_schema: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class AutomationContractReport:
+    missing_action_handlers: tuple[str, ...]
+    missing_event_publishers: tuple[str, ...]
+    undeclared_action_handlers: tuple[str, ...]
+    undeclared_event_publishers: tuple[str, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not any(
+            (
+                self.missing_action_handlers,
+                self.missing_event_publishers,
+                self.undeclared_action_handlers,
+                self.undeclared_event_publishers,
+            )
+        )
+
+    def messages(self) -> tuple[str, ...]:
+        groups = (
+            ("Missing action handlers", self.missing_action_handlers),
+            ("Missing event publishers", self.missing_event_publishers),
+            ("Handlers absent from behaviors.json", self.undeclared_action_handlers),
+            ("Events absent from behaviors.json", self.undeclared_event_publishers),
+        )
+        return tuple(f"{label}: {', '.join(values)}" for label, values in groups if values)
+
+
+class AutomationRegistry:
+    """Registry for typed runtime action handlers and event definitions."""
+
+    def __init__(
+        self,
+        *,
+        idempotency_store: AutomationIdempotencyStore | None = None,
+    ) -> None:
+        self.idempotency_store = idempotency_store
+        self._actions: dict[str, tuple[AutomationActionDefinition, AutomationActionHandler]] = {}
+        self._events: dict[str, AutomationEventDefinition] = {}
+        self._key_locks: dict[str, asyncio.Lock] = {}
+
+    @property
+    def action_definitions(self) -> tuple[AutomationActionDefinition, ...]:
+        return tuple(item[0] for item in self._actions.values())
+
+    @property
+    def event_definitions(self) -> tuple[AutomationEventDefinition, ...]:
+        return tuple(self._events.values())
+
+    def action(
+        self,
+        command: str,
+        *,
+        label: str | None = None,
+        parameter_schema: Mapping[str, Any] | None = None,
+        result_schema: Mapping[str, Any] | None = None,
+    ) -> Callable[[AutomationActionHandler], AutomationActionHandler]:
+        """Register an action handler while preserving its builder schemas."""
+        normalized = str(command or "").strip()
+        if not normalized:
+            raise ValueError("Automation action command cannot be empty")
+
+        def decorator(handler: AutomationActionHandler) -> AutomationActionHandler:
+            if normalized in self._actions:
+                raise ValueError(f"Automation action '{normalized}' is already registered")
+            definition = AutomationActionDefinition(
+                command=normalized,
+                label=str(label or normalized).strip(),
+                parameter_schema=dict(parameter_schema or {}),
+                result_schema=dict(result_schema or {}),
+            )
+            self._actions[normalized] = (definition, handler)
+            return handler
+
+        return decorator
+
+    def event(
+        self,
+        event_type: str,
+        *,
+        label: str | None = None,
+        data_schema: Mapping[str, Any] | None = None,
+    ) -> AutomationEventDefinition:
+        """Declare an event the integration may publish."""
+        normalized = str(event_type or "").strip()
+        if not normalized:
+            raise ValueError("Automation event type cannot be empty")
+        if normalized in self._events:
+            raise ValueError(f"Automation event '{normalized}' is already registered")
+        definition = AutomationEventDefinition(
+            event_type=normalized,
+            label=str(label or normalized).strip(),
+            data_schema=dict(data_schema or {}),
+        )
+        self._events[normalized] = definition
+        return definition
+
+    async def dispatch(
+        self,
+        request: AutomationActionRequest | Mapping[str, Any],
+        *,
+        idempotency_key: str | None = None,
+    ) -> AutomationActionResult:
+        """Validate and dispatch an action, replaying durable terminal outcomes."""
+        action_request = (
+            request
+            if isinstance(request, AutomationActionRequest)
+            else AutomationActionRequest.model_validate(request)
+        )
+        if idempotency_key:
+            action_request = action_request.model_copy(
+                update={"idempotency_key": str(idempotency_key).strip() or None}
+            )
+        registered = self._actions.get(action_request.command)
+        if registered is None:
+            return AutomationActionResult.failure(
+                f"Unknown automation action '{action_request.command}'",
+                retryable=False,
+            )
+
+        scoped_key = (
+            f"{action_request.command}:{action_request.idempotency_key}"
+            if action_request.idempotency_key
+            else ""
+        )
+        if scoped_key and self.idempotency_store is not None:
+            lock = self._key_locks.setdefault(scoped_key, asyncio.Lock())
+            async with lock:
+                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)
+
+    async def _invoke(
+        self,
+        handler: AutomationActionHandler,
+        request: AutomationActionRequest,
+    ) -> AutomationActionResult:
+        try:
+            candidate = handler(request)
+            value = await candidate if isinstance(candidate, Awaitable) else candidate
+            if isinstance(value, AutomationActionResult):
+                return value
+            if value is None:
+                return AutomationActionResult.success()
+            if isinstance(value, Mapping):
+                return AutomationActionResult.success(value)
+            return AutomationActionResult.failure(
+                "Automation handler returned an unsupported result type"
+            )
+        except Exception as exc:
+            return AutomationActionResult.failure(str(exc), retryable=False)
+
+    def contract_snapshot(self) -> dict[str, Any]:
+        """Return stable JSON data for conformance snapshots and tooling."""
+        return {
+            "actions": [
+                {
+                    "command": item.command,
+                    "label": item.label,
+                    "parameter_schema": dict(item.parameter_schema),
+                    "result_schema": dict(item.result_schema),
+                }
+                for item in self.action_definitions
+            ],
+            "events": [
+                {
+                    "event_type": item.event_type,
+                    "label": item.label,
+                    "data_schema": dict(item.data_schema),
+                }
+                for item in self.event_definitions
+            ],
+        }
+
+
+@dataclass(slots=True)
+class AutomationClient:
+    """High-level automation event publisher backed by the existing EventClient."""
+
+    event_client: EventClient
+    auth_context: RuntimeAuthContext
+    registry: AutomationRegistry | None = None
+
+    async def emit(
+        self,
+        event_type: str,
+        *,
+        device: RuntimeDeviceRef | Mapping[str, Any],
+        data: Mapping[str, Any] | None = None,
+        source: str | None = None,
+        severity: EventSeverity | str = EventSeverity.info,
+        event_id: str | None = None,
+    ) -> bool:
+        if self.registry is not None and event_type not in {
+            item.event_type for item in self.registry.event_definitions
+        }:
+            raise ValueError(f"Automation event '{event_type}' is not registered")
+        return await self.event_client.send_device_event(
+            device=device,
+            event_type=event_type,
+            auth_context=self.auth_context,
+            payload=data,
+            source=source,
+            severity=severity,
+            event_id=event_id,
+        )
+
+
+def build_mock_automation_event(
+    event_type: str,
+    *,
+    data: Mapping[str, Any] | None = None,
+    integration_id: str = "mock-integration",
+    config_id: str = "mock-config",
+    container_id: str = "mock-container",
+    device_id: str = "mock-device",
+    event_id: str | None = None,
+) -> CoreEventPayload:
+    """Create a canonical, non-dispatched event fixture for automated tests."""
+    return build_core_event_payload(
+        event_type=event_type,
+        integration_id=integration_id,
+        config_id=config_id,
+        container_id=container_id,
+        device_id=device_id,
+        payload=data,
+        source="automation-sdk-mock",
+        event_id=event_id,
+    )
+
+
+def audit_behaviors_contract(
+    behaviors: Mapping[str, Any],
+    registry: AutomationRegistry,
+) -> AutomationContractReport:
+    """Compare runtime registrations with commands/events in ``behaviors.json``."""
+    declared_actions: set[str] = set()
+    declared_events: set[str] = set()
+    devices = behaviors.get("devices", [])
+    if not isinstance(devices, list):
+        devices = []
+    for device in devices:
+        if not isinstance(device, Mapping):
+            continue
+        actions = device.get("actions", [])
+        triggers = device.get("triggers", [])
+        for action in actions if isinstance(actions, list) else []:
+            if not isinstance(action, Mapping):
+                continue
+            runtime = action.get("runtime")
+            if isinstance(runtime, Mapping) and runtime.get("command"):
+                declared_actions.add(str(runtime["command"]).strip())
+        for trigger in triggers if isinstance(triggers, list) else []:
+            if not isinstance(trigger, Mapping):
+                continue
+            runtime = trigger.get("runtime")
+            if isinstance(runtime, Mapping) and runtime.get("event"):
+                declared_events.add(str(runtime["event"]).strip())
+
+    registered_actions = {item.command for item in registry.action_definitions}
+    registered_events = {item.event_type for item in registry.event_definitions}
+    return AutomationContractReport(
+        missing_action_handlers=tuple(sorted(declared_actions - registered_actions)),
+        missing_event_publishers=tuple(sorted(declared_events - registered_events)),
+        undeclared_action_handlers=tuple(sorted(registered_actions - declared_actions)),
+        undeclared_event_publishers=tuple(sorted(registered_events - declared_events)),
+    )
+
+
+def assert_behaviors_contract(
+    behaviors: Mapping[str, Any],
+    registry: AutomationRegistry,
+) -> None:
+    report = audit_behaviors_contract(behaviors, registry)
+    if not report.ok:
+        raise ValueError("; ".join(report.messages()))

piphi_runtime_kit_python/fastapi.py

@@ -1,12 +1,14 @@
 """Convenience re-exports for the optional FastAPI adapter layer."""
 
 from .adapters.fastapi import (
+    dispatch_automation_action_from_fastapi,
     get_payload_container_id,
     sync_runtime_auth_from_fastapi_payload,
     sync_runtime_auth_from_fastapi_request,
 )
 
 __all__ = [
+    "dispatch_automation_action_from_fastapi",
     "get_payload_container_id",
     "sync_runtime_auth_from_fastapi_payload",
     "sync_runtime_auth_from_fastapi_request",

piphi_runtime_kit_python/schemas.py

@@ -114,11 +114,21 @@ class IntegrationDiscoveryResponse(BaseModel):
 class IntegrationCommandRequest(BaseModel):
     """Standard command payload forwarded from PiPhi Core to a runtime."""
 
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
     command: str
     capability_id: str | None = None
     device_id: str | None = None
     entity_id: str | None = None
     args: dict[str, Any] = Field(default_factory=dict)
+    idempotency_key: str | None = None
+    command_id: str | None = None
+    correlation_id: str | None = None
+    integration_id: str | None = None
+    config_id: str | None = None
+    container_id: str | None = None
+    run_id: str | None = None
+    node_id: str | None = None
 
 
 class RuntimeEntityDashboardResponse(BaseModel):

{piphi_runtime_kit_python-0.6.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.6.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.6.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.
 
@@ -95,6 +95,8 @@ The SDK is meant to own the shared PiPhi runtime plumbing:
 - discovery normalization and response helpers
 - lifecycle bootstrap helpers
 - runtime health and diagnostics helpers
+- typed automation actions and event publishers
+- automation idempotency propagation and contract auditing
 - in-memory runtime registry for active entries, state, and recent events
 - clearer PiPhi-specific delivery errors
 
@@ -167,6 +169,51 @@ The SDK remains intentionally thin: it validates and sends the data, while
 PiPhi Core owns state-change derivation, persistence policy, and automation
 semantics.
 
+## Automation SDK
+
+`behaviors.json` and the Automation SDK solve two different halves of the same
+integration contract:
+
+- `behaviors.json` is the declarative catalog. It tells Core and the builders
+  which triggers and actions exist, how they are labeled, and which fields the
+  user can configure.
+- the Automation SDK is executable runtime code. It publishes declared events,
+  receives action commands, validates their context, invokes the correct
+  handler, and preserves Core's idempotency key.
+
+Declare the user-facing card in `behaviors.json`, then implement its runtime
+command with `AutomationRegistry`:
+
+```python
+from piphi_runtime_kit_python import (
+    AutomationActionRequest,
+    AutomationRegistry,
+    SQLiteAutomationIdempotencyStore,
+)
+
+automations = AutomationRegistry(
+    idempotency_store=SQLiteAutomationIdempotencyStore(
+        "/data/piphi/automation-actions.sqlite3"
+    ),
+)
+
+@automations.action("set_fan_speed", label="Set fan speed")
+async def set_fan_speed(request: AutomationActionRequest) -> dict[str, int]:
+    speed = int(request.args["speed"])
+    await vendor_client.set_speed(request.device_id, speed)
+    return {"speed": speed}
+```
+
+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 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)
+and run the [automation runtime example](examples/automation_runtime/app.py).
+
 ## Install
 
 The package currently supports Python `>=3.11`.

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

@@ -1,11 +1,12 @@
-piphi_runtime_kit_python-0.6.0.dist-info/METADATA,sha256=pIgtdp6nS2WlVavrZ8OAAqSkEtrpMWhR-EsUqv3ArUY,34631
-piphi_runtime_kit_python-0.6.0.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
-piphi_runtime_kit_python-0.6.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-piphi_runtime_kit_python-0.6.0.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
-piphi_runtime_kit_python/__init__.py,sha256=GpYxQ9cCRjLa8tZ6fxAfn407M0-R-Xbt5oHk4WqnBQ8,7247
+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=hpTWnWKYWsNuCzXm-NGdqO8IwARrcQkp6cTuwOyE6O4,2098
-piphi_runtime_kit_python/fastapi.py,sha256=OZ-ds2-g32kB4YkF90D5bM4vVVjpOWPtrNC-WdhDNyo,361
+piphi_runtime_kit_python/adapters/fastapi.py,sha256=6sAEqJLKM_p4CYt3WB5VLsylXlyhe4v3GxBQawO4rps,3078
+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
 piphi_runtime_kit_python/runtime/auth.py,sha256=qKKkAK4RB-WFPyjQAoXp3t8sQuLDEPb-DR5TTe_OSnA,4702
@@ -25,5 +26,5 @@ piphi_runtime_kit_python/runtime/starter.py,sha256=D_mCuwiQl6xLLKQHjf963tKB2EUdm
 piphi_runtime_kit_python/runtime/state.py,sha256=OIwVxAzX2ErsZ2XdrWlIP5r3GHHub5y9PDtoqNDlwkQ,952
 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=p1GsExPvhIbXWb8GET0n6WhXa91ujEhASDwwII07n-I,10110
-piphi_runtime_kit_python-0.6.0.dist-info/RECORD,,
+piphi_runtime_kit_python/schemas.py,sha256=Dq6PVJxA2rOIt9rEKopHlmRfZujpnVfZIWYzW1uc3iw,10458
+piphi_runtime_kit_python-0.7.1.dist-info/RECORD,,