piphi-runtime-kit-python 0.4.1__tar.gz → 0.4.3__tar.gz

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.4.1
+Version: 0.4.3
 Summary: PiPhi Network runtime integration helpers
 Keywords: piphi,runtime,integration,iot
 Author-Email: KelvinSan <support@piphi.network>
@@ -362,15 +362,15 @@ async def health():
 async def config(payload: DemoConfig, request: Request):
     sync_runtime_auth_from_fastapi_payload(starter.runtime, request, payload)
     typed_payload = validate_typed_config(payload, DemoConfig)
+    identity = build_runtime_identity(typed_payload)
     starter.registry.set(
         typed_payload.id,
         {
-            "config_id": typed_payload.config_id or typed_payload.id,
-            "device_id": typed_payload.device_id or typed_payload.id,
+            **identity,
             "host": typed_payload.host,
         },
     )
-    return build_config_apply_response(config_id=typed_payload.config_id or typed_payload.id)
+    return build_config_apply_response(config_id=identity["config_id"])
 
 
 @app.post("/telemetry/example")

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/README.md

@@ -336,15 +336,15 @@ async def health():
 async def config(payload: DemoConfig, request: Request):
     sync_runtime_auth_from_fastapi_payload(starter.runtime, request, payload)
     typed_payload = validate_typed_config(payload, DemoConfig)
+    identity = build_runtime_identity(typed_payload)
     starter.registry.set(
         typed_payload.id,
         {
-            "config_id": typed_payload.config_id or typed_payload.id,
-            "device_id": typed_payload.device_id or typed_payload.id,
+            **identity,
             "host": typed_payload.host,
         },
     )
-    return build_config_apply_response(config_id=typed_payload.config_id or typed_payload.id)
+    return build_config_apply_response(config_id=identity["config_id"])
 
 
 @app.post("/telemetry/example")

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "piphi-runtime-kit-python"
-version = "0.4.1"
+version = "0.4.3"
 description = "PiPhi Network runtime integration helpers"
 authors = [
     { name = "KelvinSan", email = "support@piphi.network" },

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/__init__.py

@@ -8,7 +8,18 @@ from .runtime.auth import (
     format_runtime_auth_sync_log,
     mask_token,
 )
-from .runtime.config_sync import ConfigSyncCoordinator, build_sync_response, reconcile_config_ids
+from .runtime.config_sync import (
+    CORE_BASE_URL_ENV_NAME,
+    DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME,
+    DEFAULT_RUNTIME_VOLUME_DIR,
+    RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME,
+    ConfigSyncCoordinator,
+    build_sync_response,
+    load_runtime_config_snapshot,
+    reconcile_config_ids,
+    resolve_core_base_url,
+    resolve_runtime_config_snapshot_path,
+)
 from .runtime.configuration import (
     build_config_apply_response,
     build_config_remove_response,
@@ -49,6 +60,7 @@ from .runtime.events import (
     normalize_event_payload,
 )
 from .runtime.health import build_runtime_diagnostics_response, build_runtime_health_response
+from .runtime.identity import build_runtime_identity, resolve_config_id, resolve_device_id
 from .runtime.lifespan import (
     DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
     DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
@@ -80,6 +92,8 @@ from .schemas import (
     IntegrationCommandRequest,
     IntegrationDiscoveryRequest,
     IntegrationDiscoveryResponse,
+    RuntimeEntityCommandFieldResponse,
+    RuntimeEntityCommandResponse,
     RuntimeEntityDashboardResponse,
     RuntimeEntitiesResponse,
     RuntimeEntityResponse,
@@ -106,6 +120,10 @@ __all__ = [
     "CoreUnavailableError",
     "CoreUnexpectedResponseError",
     "DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS",
+    "CORE_BASE_URL_ENV_NAME",
+    "DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME",
+    "DEFAULT_RUNTIME_VOLUME_DIR",
+    "RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME",
     "DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME",
     "DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME",
     "RUNTIME_CONTAINER_ID_HEADER_NAME",
@@ -113,6 +131,8 @@ __all__ = [
     "IntegrationCommandRequest",
     "IntegrationDiscoveryRequest",
     "IntegrationDiscoveryResponse",
+    "RuntimeEntityCommandFieldResponse",
+    "RuntimeEntityCommandResponse",
     "RuntimeEntityDashboardResponse",
     "RuntimeEntitiesResponse",
     "RuntimeEntityResponse",
@@ -144,6 +164,7 @@ __all__ = [
     "build_event_ingest_response",
     "build_event_list_response",
     "build_local_event_record",
+    "build_runtime_identity",
     "build_core_auth_headers",
     "build_config_apply_response",
     "build_config_remove_response",
@@ -163,6 +184,7 @@ __all__ = [
     "format_discovery_attempt_log",
     "format_event_log",
     "format_runtime_auth_sync_log",
+    "load_runtime_config_snapshot",
     "mask_token",
     "MqttBrokerConfig",
     "MqttJsonClient",
@@ -170,11 +192,15 @@ __all__ = [
     "normalize_event_payload",
     "redact_config_secrets",
     "reconcile_config_ids",
+    "resolve_core_base_url",
+    "resolve_runtime_config_snapshot_path",
     "runtime_lifespan",
     "schedule_event_delivery",
     "schedule_telemetry_delivery",
     "shutdown_background_tasks",
     "track_background_task",
+    "resolve_config_id",
+    "resolve_device_id",
     "validate_typed_config",
     "validate_typed_configs",
     "DEFAULT_SOURCE_TOPIC_PREFIX",

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/runtime/config_sync.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 """Helpers for basic config-sync orchestration and generation tracking."""
 
 from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
 from typing import Awaitable, Callable, TypeVar
 
 from ..schemas import RuntimeConfig, RuntimeConfigSnapshot, RuntimeConfigSyncResponse
@@ -10,6 +13,77 @@ from .state import RuntimeProcessState
 
 TConfig = TypeVar("TConfig", bound=RuntimeConfig)
 
+CORE_BASE_URL_ENV_NAME = "PIPHI_CORE_BASE_URL"
+RUNTIME_CONTAINER_ID_ENV_NAME = "PIPHI_CONTAINER_ID"
+RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME = "PIPHI_CONFIG_SNAPSHOT_PATH"
+DEFAULT_RUNTIME_VOLUME_DIR = "/.piphinetwork"
+DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME = "configs.json"
+
+
+def resolve_core_base_url(default: str | None = None) -> str | None:
+    """Resolve Core's base URL from the managed-runtime environment."""
+    value = (os.getenv(CORE_BASE_URL_ENV_NAME) or "").strip().rstrip("/")
+    if value:
+        return value
+    return default.rstrip("/") if isinstance(default, str) and default.strip() else default
+
+
+def resolve_runtime_config_snapshot_path(
+    *,
+    container_id: str | None = None,
+    volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+) -> Path:
+    """Resolve the local config snapshot path mounted by PiPhi Core."""
+    explicit_path = (os.getenv(RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME) or "").strip()
+    if explicit_path:
+        return Path(explicit_path)
+
+    resolved_container_id = (
+        str(container_id or "").strip()
+        or (os.getenv(RUNTIME_CONTAINER_ID_ENV_NAME) or "").strip()
+    )
+    if resolved_container_id:
+        return Path(volume_dir).joinpath(f"{resolved_container_id}.json")
+    return Path(volume_dir).joinpath(DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME)
+
+
+def load_runtime_config_snapshot(
+    *,
+    path: str | Path | None = None,
+    container_id: str | None = None,
+    volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+) -> RuntimeConfigSnapshot | None:
+    """Load Core's last known config snapshot from the mounted runtime volume.
+
+    Missing, unreadable, or invalid snapshots return ``None`` so integrations can
+    treat snapshot rehydration as a safe startup fallback rather than a crash
+    trigger.
+    """
+    snapshot_path = (
+        Path(path)
+        if path is not None
+        else resolve_runtime_config_snapshot_path(
+            container_id=container_id,
+            volume_dir=volume_dir,
+        )
+    )
+    try:
+        raw_payload = snapshot_path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return None
+
+    try:
+        payload = json.loads(raw_payload)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+
+    try:
+        return RuntimeConfigSnapshot.model_validate(payload)
+    except ValueError:
+        return None
+
 
 def reconcile_config_ids(
     *,

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/runtime/dispatch.py

@@ -2,8 +2,10 @@ from __future__ import annotations
 
 """Helpers for background dispatch of telemetry and event delivery."""
 
+import asyncio
 from typing import Any, Callable, Mapping
 
+from .errors import CoreDeliveryError
 from .events import EventClient
 from .tasks import create_tracked_task
 from .telemetry import TelemetryClient
@@ -14,6 +16,9 @@ EventRecorder = Callable[[dict[str, Any]], Any]
 SkipHandler = Callable[[str, dict[str, Any]], Any]
 ErrorHandler = Callable[[Exception, dict[str, Any]], Any]
 
+DEFAULT_RETRYABLE_DELIVERY_ATTEMPTS = 5
+DEFAULT_RETRYABLE_DELIVERY_INITIAL_DELAY_SECONDS = 0.5
+
 
 def build_local_event_record(
     *,
@@ -36,6 +41,30 @@ def build_local_event_record(
     }
 
 
+async def _run_with_retryable_core_delivery_backoff(
+    delivery: Callable[[], Any],
+    *,
+    max_attempts: int = DEFAULT_RETRYABLE_DELIVERY_ATTEMPTS,
+    initial_delay_seconds: float = DEFAULT_RETRYABLE_DELIVERY_INITIAL_DELAY_SECONDS,
+) -> Any:
+    """Retry transient Core delivery failures with a short exponential backoff."""
+
+    attempt = 1
+    delay_seconds = initial_delay_seconds
+    while True:
+        try:
+            result = delivery()
+            if asyncio.iscoroutine(result):
+                return await result
+            return result
+        except CoreDeliveryError as exc:
+            if not exc.retryable or attempt >= max_attempts:
+                raise
+            await asyncio.sleep(delay_seconds)
+            attempt += 1
+            delay_seconds *= 2
+
+
 async def dispatch_telemetry_delivery(
     *,
     telemetry_client: TelemetryClient,
@@ -59,13 +88,15 @@ async def dispatch_telemetry_delivery(
         return False
 
     try:
-        await telemetry_client.send_metrics(
-            device_id=device_id,
-            metrics=metrics,
-            auth_context=auth_context,
-            container_id=resolved_container_id,
-            units=units,
-            timestamp=timestamp,
+        await _run_with_retryable_core_delivery_backoff(
+            lambda: telemetry_client.send_metrics(
+                device_id=device_id,
+                metrics=metrics,
+                auth_context=auth_context,
+                container_id=resolved_container_id,
+                units=units,
+                timestamp=timestamp,
+            )
         )
         return True
     except Exception as exc:
@@ -119,16 +150,18 @@ async def dispatch_event_delivery(
 ) -> bool:
     """Send one event to Core and return whether delivery succeeded."""
     try:
-        event_sent = await event_client.send_event(
-            event_type=event_type,
-            integration_id=device.get("integration_id"),
-            config_id=device.get("config_id") or device.get("device_id"),
-            auth_context=auth_context,
-            container_id=device.get("container_id"),
-            device_id=device.get("device_id"),
-            payload=payload,
-            source=source,
-            severity=severity,
+        event_sent = await _run_with_retryable_core_delivery_backoff(
+            lambda: event_client.send_event(
+                event_type=event_type,
+                integration_id=device.get("integration_id"),
+                config_id=device.get("config_id"),
+                auth_context=auth_context,
+                container_id=device.get("container_id"),
+                device_id=device.get("device_id"),
+                payload=payload,
+                source=source,
+                severity=severity,
+            )
         )
         if not event_sent and on_skipped is not None:
             on_skipped(

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/runtime/health.py

@@ -15,6 +15,7 @@ def _build_runtime_snapshot(runtime_context: RuntimeContext) -> dict[str, Any]:
         "core_auth_present": bool(runtime_context.auth.internal_token),
         "core_http_client_bound": process_state.core_http_client is not None,
         "current_generation": process_state.current_generation,
+        "config_generation": process_state.current_generation,
         "pending_task_count": len(
             [task for task in process_state.background_tasks if not task.done()]
         ),

piphi_runtime_kit_python-0.4.3/src/piphi_runtime_kit_python/runtime/identity.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+"""Helpers for keeping runtime config and device identity explicit."""
+
+from typing import Any, Mapping
+
+
+def _coerce_optional_string(value: Any) -> str | None:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _first_present(payload: Mapping[str, Any], *keys: str) -> str | None:
+    for key in keys:
+        resolved = _coerce_optional_string(payload.get(key))
+        if resolved:
+            return resolved
+    return None
+
+
+def resolve_config_id(payload: Mapping[str, Any] | Any) -> str:
+    """Resolve the Core-owned config id from a config-like payload."""
+
+    if isinstance(payload, Mapping):
+        return _first_present(payload, "config_id", "configId", "id") or "missing"
+    return (
+        _coerce_optional_string(getattr(payload, "config_id", None))
+        or _coerce_optional_string(getattr(payload, "configId", None))
+        or _coerce_optional_string(getattr(payload, "id", None))
+        or "missing"
+    )
+
+
+def resolve_device_id(payload: Mapping[str, Any] | Any) -> str:
+    """Resolve the integration-owned device id from a config-like payload."""
+
+    if isinstance(payload, Mapping):
+        return _first_present(payload, "device_id", "deviceId", "id") or "missing"
+    return (
+        _coerce_optional_string(getattr(payload, "device_id", None))
+        or _coerce_optional_string(getattr(payload, "deviceId", None))
+        or _coerce_optional_string(getattr(payload, "id", None))
+        or "missing"
+    )
+
+
+def build_runtime_identity(
+    payload: Mapping[str, Any] | Any,
+    *,
+    container_id: str | None = None,
+    integration_id: str | None = None,
+) -> dict[str, Any]:
+    """Build a canonical runtime identity record for one config-backed device."""
+
+    resolved = {
+        "config_id": resolve_config_id(payload),
+        "device_id": resolve_device_id(payload),
+    }
+    payload_container_id = (
+        _first_present(payload, "container_id", "containerId")
+        if isinstance(payload, Mapping)
+        else (
+            _coerce_optional_string(getattr(payload, "container_id", None))
+            or _coerce_optional_string(getattr(payload, "containerId", None))
+        )
+    )
+    payload_integration_id = (
+        _first_present(payload, "integration_id", "integrationId")
+        if isinstance(payload, Mapping)
+        else (
+            _coerce_optional_string(getattr(payload, "integration_id", None))
+            or _coerce_optional_string(getattr(payload, "integrationId", None))
+        )
+    )
+
+    resolved["container_id"] = _coerce_optional_string(container_id) or payload_container_id
+    resolved["integration_id"] = _coerce_optional_string(integration_id) or payload_integration_id
+    return resolved

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/runtime/registry.py

@@ -50,18 +50,30 @@ class RuntimeRegistry(Generic[TEntry, TState, TEvent]):
         first_entry_id = next(iter(self.entries))
         return self.entries[first_entry_id]
 
-    def update_state(self, entry_id: str, state: dict[str, Any]) -> dict[str, Any]:
+    def update_state(
+        self,
+        entry_id: str,
+        state: dict[str, Any],
+        *,
+        device_id: str | None = None,
+    ) -> dict[str, Any]:
         """Store the latest state snapshot and mirror it onto the active entry."""
         timestamp = dt.datetime.now(dt.timezone.utc).isoformat()
+        entry = self.entries.get(entry_id)
+        resolved_device_id = (
+            device_id
+            or (str(entry.get("device_id")) if entry and entry.get("device_id") else None)
+            or entry_id
+        )
         latest_state = {
-            "device_id": entry_id,
+            "device_id": resolved_device_id,
             "state": state,
             "last_updated": timestamp,
         }
         self.state_snapshots[entry_id] = latest_state
-        if entry_id in self.entries:
-            self.entries[entry_id]["latest_state"] = state
-            self.entries[entry_id]["last_updated"] = timestamp
+        if entry is not None:
+            entry["latest_state"] = state
+            entry["last_updated"] = timestamp
         return latest_state
 
     def append_event(self, event: TEvent) -> TEvent:

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/src/piphi_runtime_kit_python/schemas.py

@@ -11,18 +11,58 @@ from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 class RuntimeConfig(BaseModel):
     """Base runtime config model with a required config id and extensible fields."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
     id: str
-    model_config = ConfigDict(extra="allow")
+    config_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("config_id", "configId"),
+    )
+    container_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("container_id", "containerId"),
+    )
+    integration_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("integration_id", "integrationId"),
+    )
+    device_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("device_id", "deviceId"),
+    )
 
 
 class RuntimeConfigSnapshot(BaseModel):
     """Snapshot payload sent from PiPhi Core to an integration runtime."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    schema_version: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("schema_version", "schemaVersion"),
+    )
     container_id: str
     integration_id: str | None = None
     driver_pid: int | None = None
     reason: str | None = None
     generation: int | None = None
+    updated_at: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("updated_at", "updatedAt"),
+    )
     configs: list[RuntimeConfig] = Field(default_factory=list)
+    deleted_config_ids: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("deleted_config_ids", "deletedConfigIds"),
+    )
+    config_hash: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("config_hash", "configHash"),
+    )
+    internal_token: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("internal_token", "internalToken"),
+    )
 
 
 class RuntimeConfigSyncResponse(BaseModel):
@@ -94,6 +134,44 @@ class RuntimeEntityDashboardResponse(BaseModel):
     metadata: dict[str, Any] = Field(default_factory=dict)
 
 
+class RuntimeEntityCommandFieldResponse(BaseModel):
+    """Optional per-command argument metadata returned by a runtime entity."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    type: str
+    label: str | None = None
+    description: str | None = None
+    required: bool = False
+    default: Any | None = None
+    minimum: float | None = Field(
+        default=None,
+        validation_alias=AliasChoices("minimum", "min"),
+    )
+    maximum: float | None = Field(
+        default=None,
+        validation_alias=AliasChoices("maximum", "max"),
+    )
+    step: float | None = None
+    unit: str | None = None
+    options: list[Any] = Field(default_factory=list)
+
+
+class RuntimeEntityCommandResponse(BaseModel):
+    """One device-scoped command exposed by a runtime entity."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: str
+    label: str | None = None
+    description: str | None = None
+    kind: str | None = None
+    args_schema: dict[str, RuntimeEntityCommandFieldResponse] = Field(
+        default_factory=dict,
+        validation_alias=AliasChoices("args_schema", "argsSchema"),
+    )
+
+
 class RuntimeEntityResponse(BaseModel):
     """One live runtime entity tied to a configured device/account."""
 
@@ -122,6 +200,15 @@ class RuntimeEntityResponse(BaseModel):
         default=None,
         validation_alias=AliasChoices("entity_type", "entityType"),
     )
+    available_commands: list[RuntimeEntityCommandResponse | str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices(
+            "available_commands",
+            "availableCommands",
+            "supported_commands",
+            "supportedCommands",
+        ),
+    )
     dashboard: RuntimeEntityDashboardResponse | None = None
     metadata: dict[str, Any] = Field(default_factory=dict)
 

piphi_runtime_kit_python-0.4.3/tests/test_config_sync.py

@@ -0,0 +1,138 @@
+import pytest
+
+from piphi_runtime_kit_python import (
+    ConfigSyncCoordinator,
+    RuntimeConfig,
+    RuntimeConfigSnapshot,
+    RuntimeProcessState,
+    load_runtime_config_snapshot,
+    reconcile_config_ids,
+    resolve_core_base_url,
+    resolve_runtime_config_snapshot_path,
+)
+
+
+def test_reconcile_config_ids_returns_removed_and_unchanged_ids() -> None:
+    removed_ids, unchanged_ids = reconcile_config_ids(
+        active_ids=["a", "b", "c"],
+        incoming_ids=["b", "c", "d"],
+    )
+
+    assert removed_ids == ["a"]
+    assert unchanged_ids == ["b", "c"]
+
+
+def test_config_sync_coordinator_detects_stale_snapshot() -> None:
+    state = RuntimeProcessState(current_generation=10)
+    coordinator = ConfigSyncCoordinator(process_state=state)
+    snapshot = RuntimeConfigSnapshot(
+        container_id="container-1",
+        generation=9,
+        configs=[RuntimeConfig(id="device-1")],
+    )
+
+    assert coordinator.is_stale(snapshot) is True
+
+
+def test_config_sync_coordinator_updates_generation() -> None:
+    state = RuntimeProcessState()
+    coordinator = ConfigSyncCoordinator(process_state=state)
+
+    assert coordinator.mark_generation(42) == 42
+    assert state.current_generation == 42
+
+
+def test_resolve_core_base_url_uses_managed_runtime_env(monkeypatch) -> None:
+    monkeypatch.setenv("PIPHI_CORE_BASE_URL", "http://127.0.0.1:31419/")
+
+    assert resolve_core_base_url() == "http://127.0.0.1:31419"
+
+
+def test_resolve_runtime_config_snapshot_path_uses_container_id(monkeypatch, tmp_path) -> None:
+    monkeypatch.delenv("PIPHI_CONFIG_SNAPSHOT_PATH", raising=False)
+    monkeypatch.setenv("PIPHI_CONTAINER_ID", "container-1")
+
+    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == tmp_path / "container-1.json"
+
+
+def test_resolve_runtime_config_snapshot_path_prefers_explicit_path(monkeypatch, tmp_path) -> None:
+    explicit_path = tmp_path / "custom.json"
+    monkeypatch.setenv("PIPHI_CONFIG_SNAPSHOT_PATH", str(explicit_path))
+
+    assert resolve_runtime_config_snapshot_path(volume_dir=tmp_path) == explicit_path
+
+
+def test_load_runtime_config_snapshot_reads_core_volume_contract(tmp_path) -> None:
+    snapshot_path = tmp_path / "container-1.json"
+    snapshot_path.write_text(
+        """
+        {
+          "schema_version": 1,
+          "container_id": "container-1",
+          "integration_id": "integration-1",
+          "reason": "startup",
+          "generation": 42,
+          "updated_at": "2026-04-27T12:00:00+00:00",
+          "configs": [{"id": "device-1", "serial": "abc123"}],
+          "deleted_config_ids": ["device-2"],
+          "config_hash": "sha256:abc",
+          "internal_token": "runtime-token"
+        }
+        """,
+        encoding="utf-8",
+    )
+
+    snapshot = load_runtime_config_snapshot(path=snapshot_path)
+
+    assert snapshot is not None
+    assert snapshot.schema_version == 1
+    assert snapshot.container_id == "container-1"
+    assert snapshot.generation == 42
+    assert snapshot.configs[0].id == "device-1"
+    assert snapshot.deleted_config_ids == ["device-2"]
+    assert snapshot.config_hash == "sha256:abc"
+    assert snapshot.internal_token == "runtime-token"
+
+
+def test_load_runtime_config_snapshot_returns_none_for_missing_or_invalid_snapshot(tmp_path) -> None:
+    assert load_runtime_config_snapshot(path=tmp_path / "missing.json") is None
+
+    invalid_path = tmp_path / "invalid.json"
+    invalid_path.write_text("not-json", encoding="utf-8")
+
+    assert load_runtime_config_snapshot(path=invalid_path) is None
+
+
+@pytest.mark.asyncio
+async def test_config_sync_coordinator_apply_snapshot_orchestrates_callbacks() -> None:
+    state = RuntimeProcessState(current_generation=1)
+    coordinator = ConfigSyncCoordinator(process_state=state)
+    snapshot = RuntimeConfigSnapshot(
+        container_id="container-1",
+        generation=2,
+        configs=[RuntimeConfig(id="device-2"), RuntimeConfig(id="device-3")],
+    )
+    active_ids = ["device-1", "device-2"]
+    applied: list[str] = []
+    removed: list[str] = []
+
+    async def apply_config(config: RuntimeConfig) -> None:
+        applied.append(config.id)
+
+    async def remove_config(config_id: str) -> bool:
+        removed.append(config_id)
+        return True
+
+    response = await coordinator.apply_snapshot(
+        snapshot=snapshot,
+        active_config_ids=active_ids,
+        apply_config=apply_config,
+        remove_config=remove_config,
+        get_active_config_ids=lambda: ["device-2", "device-3"],
+    )
+
+    assert applied == ["device-2", "device-3"]
+    assert removed == ["device-1"]
+    assert response.status == "synced"
+    assert response.generation == 2
+    assert response.active_config_ids == ["device-2", "device-3"]

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/tests/test_runtime_dispatch_matrix.py

@@ -2,6 +2,7 @@ import httpx
 import pytest
 
 from piphi_runtime_kit_python import EventClient, RuntimeAuthContext, RuntimeProcessState, TelemetryClient
+from piphi_runtime_kit_python.runtime.errors import CoreUnavailableError
 from piphi_runtime_kit_python.runtime.dispatch import (
     build_local_event_record,
     dispatch_event_delivery,
@@ -48,6 +49,39 @@ async def test_dispatch_telemetry_delivery_returns_true_on_success(
     assert called == [("device-1", "container-1")]
 
 
+@pytest.mark.asyncio
+async def test_dispatch_telemetry_delivery_retries_retryable_core_errors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    process_state = RuntimeProcessState()
+    client = TelemetryClient(process_state=process_state, core_base_url="http://core.test")
+    auth_context = RuntimeAuthContext(container_id="container-retry", internal_token="token-retry")
+    attempts: list[int] = []
+
+    async def fake_send_metrics(self, **kwargs) -> None:  # noqa: ARG001
+        attempts.append(1)
+        if len(attempts) == 1:
+            raise CoreUnavailableError(
+                operation="telemetry_delivery",
+                url="http://core.test/api/v2/integrations/telemetry",
+                message="PiPhi Core is unreachable",
+                retryable=True,
+                timeout_seconds=3.0,
+            )
+
+    monkeypatch.setattr(TelemetryClient, "send_metrics", fake_send_metrics)
+
+    delivered = await dispatch_telemetry_delivery(
+        telemetry_client=client,
+        auth_context=auth_context,
+        device_id="device-retry",
+        metrics={"is_on": True},
+    )
+
+    assert delivered is True
+    assert len(attempts) == 2
+
+
 @pytest.mark.asyncio
 async def test_dispatch_telemetry_delivery_calls_error_handler_and_returns_false(
     monkeypatch: pytest.MonkeyPatch,
@@ -107,6 +141,46 @@ async def test_dispatch_event_delivery_returns_true_on_success(
     assert called == ["device.updated"]
 
 
+@pytest.mark.asyncio
+async def test_dispatch_event_delivery_retries_retryable_core_errors(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    process_state = RuntimeProcessState()
+    client = EventClient(process_state=process_state, core_base_url="http://core.test")
+    auth_context = RuntimeAuthContext(container_id="container-event", internal_token="token-event")
+    attempts: list[int] = []
+
+    async def fake_send_event(self, **kwargs) -> bool:  # noqa: ARG001
+        attempts.append(1)
+        if len(attempts) == 1:
+            raise CoreUnavailableError(
+                operation="event_delivery",
+                url="http://core.test/api/v2/events/ingest",
+                message="PiPhi Core is unreachable",
+                retryable=True,
+                timeout_seconds=3.0,
+            )
+        return True
+
+    monkeypatch.setattr(EventClient, "send_event", fake_send_event)
+
+    delivered = await dispatch_event_delivery(
+        event_client=client,
+        auth_context=auth_context,
+        event_type="device.updated",
+        device={
+            "device_id": "device-event",
+            "container_id": "container-event",
+            "integration_id": "integration-event",
+            "config_id": "config-event",
+        },
+        source="runtime-event",
+    )
+
+    assert delivered is True
+    assert len(attempts) == 2
+
+
 @pytest.mark.asyncio
 async def test_dispatch_event_delivery_calls_skip_handler_when_client_returns_false(
     monkeypatch: pytest.MonkeyPatch,

piphi_runtime_kit_python-0.4.3/tests/test_runtime_identity.py

@@ -0,0 +1,29 @@
+from piphi_runtime_kit_python import RuntimeConfig, build_runtime_identity, resolve_config_id, resolve_device_id
+
+
+def test_runtime_identity_helpers_prefer_explicit_config_and_device_ids() -> None:
+    payload = RuntimeConfig.model_validate(
+        {
+            "id": "core-config-uuid",
+            "config_id": "core-config-uuid",
+            "device_id": "vendor-device-42",
+            "container_id": "container-1",
+            "integration_id": "demo-runtime",
+        }
+    )
+
+    assert resolve_config_id(payload) == "core-config-uuid"
+    assert resolve_device_id(payload) == "vendor-device-42"
+    assert build_runtime_identity(payload) == {
+        "config_id": "core-config-uuid",
+        "device_id": "vendor-device-42",
+        "container_id": "container-1",
+        "integration_id": "demo-runtime",
+    }
+
+
+def test_runtime_identity_helpers_fall_back_to_id() -> None:
+    payload = {"id": "core-config-uuid"}
+
+    assert resolve_config_id(payload) == "core-config-uuid"
+    assert resolve_device_id(payload) == "core-config-uuid"

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/tests/test_runtime_registry.py

@@ -21,6 +21,16 @@ def test_runtime_registry_update_state_mirrors_latest_state_to_entry() -> None:
     assert registry.entries["device-1"]["latest_state"] == {"is_on": True}
 
 
+def test_runtime_registry_update_state_uses_entry_device_id_when_present() -> None:
+    registry = RuntimeRegistry()
+    registry.set("cfg-1", {"device_id": "sensor-1"})
+
+    latest_state = registry.update_state("cfg-1", {"temperature_c": 21.5})
+
+    assert latest_state["device_id"] == "sensor-1"
+    assert registry.state_snapshots["cfg-1"]["device_id"] == "sensor-1"
+
+
 def test_runtime_registry_append_event_bounds_recent_event_window() -> None:
     registry = RuntimeRegistry(max_recent_events=2)
 

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/tests/test_runtime_starter.py

@@ -40,6 +40,10 @@ def test_runtime_starter_entities_response_wraps_runtime_entities() -> None:
                 "config_id": "cfg-1",
                 "device_id": "office-plug",
                 "device_class": "plug",
+                "available_commands": [
+                    {"id": "toggle", "label": "Toggle", "kind": "primary"},
+                    {"id": "refresh", "label": "Refresh", "kind": "secondary"},
+                ],
             }
         ],
         capabilities={"switch": {"kind": "action"}},
@@ -49,5 +53,6 @@ def test_runtime_starter_entities_response_wraps_runtime_entities() -> None:
     assert isinstance(response, RuntimeEntitiesResponse)
     assert response.entities[0].name == "Office Plug"
     assert response.entities[0].device_class == "plug"
+    assert response.entities[0].available_commands[0].id == "toggle"
     assert response.capabilities == {"switch": {"kind": "action"}}
     assert response.commands == {"turn_on": {"description": "Turn on"}}

{piphi_runtime_kit_python-0.4.1 → piphi_runtime_kit_python-0.4.3}/tests/test_schemas_matrix.py

@@ -17,6 +17,7 @@ from piphi_runtime_kit_python import (
     RuntimeConfigSyncResponse,
     RuntimeDiagnosticsResponse,
     RuntimeEntitiesResponse,
+    RuntimeEntityCommandResponse,
     RuntimeEntityDashboardResponse,
     RuntimeEntityResponse,
     RuntimeHealthResponse,
@@ -85,6 +86,20 @@ def test_runtime_entity_models_support_aliases_and_defaults() -> None:
             "deviceId": "office-plug",
             "deviceClass": "plug",
             "entityType": "switch",
+            "availableCommands": [
+                {
+                    "id": "toggle",
+                    "label": "Toggle",
+                    "kind": "primary",
+                },
+                {
+                    "id": "set_brightness",
+                    "label": "Set Brightness",
+                    "argsSchema": {
+                        "brightness": {"type": "number", "min": 0, "max": 100, "unit": "%"}
+                    },
+                },
+            ],
             "dashboard": {
                 "allowedWidgets": ["tile", "stat"],
                 "defaultWidget": "tile",
@@ -97,6 +112,10 @@ def test_runtime_entity_models_support_aliases_and_defaults() -> None:
     assert entity.device_id == "office-plug"
     assert entity.device_class == "plug"
     assert entity.entity_type == "switch"
+    assert len(entity.available_commands) == 2
+    assert isinstance(entity.available_commands[0], RuntimeEntityCommandResponse)
+    assert entity.available_commands[0].id == "toggle"
+    assert entity.available_commands[1].args_schema["brightness"].minimum == 0
     assert entity.dashboard is not None
     assert entity.dashboard.allowed_widgets == ["tile", "stat"]
     assert entity.dashboard.default_widget == "tile"

piphi_runtime_kit_python-0.4.1/tests/test_config_sync.py

@@ -1,74 +0,0 @@
-import pytest
-
-from piphi_runtime_kit_python import (
-    ConfigSyncCoordinator,
-    RuntimeConfig,
-    RuntimeConfigSnapshot,
-    RuntimeProcessState,
-    reconcile_config_ids,
-)
-
-
-def test_reconcile_config_ids_returns_removed_and_unchanged_ids() -> None:
-    removed_ids, unchanged_ids = reconcile_config_ids(
-        active_ids=["a", "b", "c"],
-        incoming_ids=["b", "c", "d"],
-    )
-
-    assert removed_ids == ["a"]
-    assert unchanged_ids == ["b", "c"]
-
-
-def test_config_sync_coordinator_detects_stale_snapshot() -> None:
-    state = RuntimeProcessState(current_generation=10)
-    coordinator = ConfigSyncCoordinator(process_state=state)
-    snapshot = RuntimeConfigSnapshot(
-        container_id="container-1",
-        generation=9,
-        configs=[RuntimeConfig(id="device-1")],
-    )
-
-    assert coordinator.is_stale(snapshot) is True
-
-
-def test_config_sync_coordinator_updates_generation() -> None:
-    state = RuntimeProcessState()
-    coordinator = ConfigSyncCoordinator(process_state=state)
-
-    assert coordinator.mark_generation(42) == 42
-    assert state.current_generation == 42
-
-
-@pytest.mark.asyncio
-async def test_config_sync_coordinator_apply_snapshot_orchestrates_callbacks() -> None:
-    state = RuntimeProcessState(current_generation=1)
-    coordinator = ConfigSyncCoordinator(process_state=state)
-    snapshot = RuntimeConfigSnapshot(
-        container_id="container-1",
-        generation=2,
-        configs=[RuntimeConfig(id="device-2"), RuntimeConfig(id="device-3")],
-    )
-    active_ids = ["device-1", "device-2"]
-    applied: list[str] = []
-    removed: list[str] = []
-
-    async def apply_config(config: RuntimeConfig) -> None:
-        applied.append(config.id)
-
-    async def remove_config(config_id: str) -> bool:
-        removed.append(config_id)
-        return True
-
-    response = await coordinator.apply_snapshot(
-        snapshot=snapshot,
-        active_config_ids=active_ids,
-        apply_config=apply_config,
-        remove_config=remove_config,
-        get_active_config_ids=lambda: ["device-2", "device-3"],
-    )
-
-    assert applied == ["device-2", "device-3"]
-    assert removed == ["device-1"]
-    assert response.status == "synced"
-    assert response.generation == 2
-    assert response.active_config_ids == ["device-2", "device-3"]