piphi-runtime-kit-python 0.3.0__py3-none-any.whl

piphi_runtime_kit_python/runtime/starter.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+"""Opinionated beginner-friendly starter helpers for PiPhi runtimes."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .config_sync import ConfigSyncCoordinator
+from .context import RuntimeContext
+from .events import DEFAULT_CORE_BASE_URL as DEFAULT_EVENTS_CORE_BASE_URL, EventClient
+from .health import build_runtime_diagnostics_response, build_runtime_health_response
+from .registry import RuntimeRegistry
+from .telemetry import DEFAULT_CORE_BASE_URL as DEFAULT_TELEMETRY_CORE_BASE_URL, TelemetryClient
+
+
+@dataclass(slots=True)
+class RuntimeStarter:
+    """Small “golden path” object for beginner-friendly runtime setup.
+
+    This intentionally bundles the runtime context, in-memory registry, config
+    sync coordinator, and Core delivery clients into one obvious object so new
+    integration authors have fewer moving parts to assemble by hand.
+    """
+
+    integration_id: str
+    integration_name: str
+    version: str = "0.1.0"
+    core_base_url: str = DEFAULT_TELEMETRY_CORE_BASE_URL
+    max_recent_events: int = 100
+    runtime: RuntimeContext = field(init=False)
+    registry: RuntimeRegistry[dict[str, Any], dict[str, Any], dict[str, Any]] = field(init=False)
+    telemetry_client: TelemetryClient = field(init=False)
+    event_client: EventClient = field(init=False)
+    config_sync: ConfigSyncCoordinator = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.runtime = RuntimeContext()
+        self.registry = RuntimeRegistry(
+            max_recent_events=self.max_recent_events
+        )
+        self.telemetry_client = TelemetryClient(
+            process_state=self.runtime.process_state,
+            core_base_url=self.core_base_url or DEFAULT_TELEMETRY_CORE_BASE_URL,
+        )
+        self.event_client = EventClient(
+            process_state=self.runtime.process_state,
+            core_base_url=self.core_base_url or DEFAULT_EVENTS_CORE_BASE_URL,
+        )
+        self.config_sync = ConfigSyncCoordinator(process_state=self.runtime.process_state)
+
+    @property
+    def integration_metadata(self) -> dict[str, Any]:
+        """Return the standard integration metadata shape used in responses."""
+        return {
+            "id": self.integration_id,
+            "name": self.integration_name,
+            "version": self.version,
+        }
+
+    def health_response(self, *, metadata: dict[str, Any] | None = None):
+        """Build a health response using the starter's shared runtime state."""
+        return build_runtime_health_response(
+            self.runtime,
+            integration=self.integration_metadata,
+            metadata=metadata or {"active_configs": len(self.registry.ids())},
+        )
+
+    def diagnostics_response(self, *, diagnostics: dict[str, Any] | None = None):
+        """Build a diagnostics response using the starter's shared runtime state."""
+        return build_runtime_diagnostics_response(
+            self.runtime,
+            integration=self.integration_metadata,
+            diagnostics=diagnostics
+            or {
+                "active_config_ids": self.registry.ids(),
+                "recent_event_count": len(self.registry.recent_events),
+            },
+        )
+
+
+def create_runtime_starter(
+    *,
+    integration_id: str,
+    integration_name: str,
+    version: str = "0.1.0",
+    core_base_url: str = DEFAULT_TELEMETRY_CORE_BASE_URL,
+    max_recent_events: int = 100,
+) -> RuntimeStarter:
+    """Return the recommended beginner-friendly runtime starter object."""
+    return RuntimeStarter(
+        integration_id=integration_id,
+        integration_name=integration_name,
+        version=version,
+        core_base_url=core_base_url,
+        max_recent_events=max_recent_events,
+    )

piphi_runtime_kit_python/runtime/state.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+"""Shared mutable runtime state used by the thin PiPhi runtime helpers."""
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+
+@dataclass(slots=True)
+class RuntimeProcessState:
+    """Process-scoped runtime state.
+
+    This keeps non-device-specific runtime concerns in one place:
+    the active Core HTTP client, the latest config generation, and tracked
+    background tasks that should be cleaned up on shutdown.
+    """
+    current_generation: int | None = None
+    core_http_client: httpx.AsyncClient | None = None
+    background_tasks: set[asyncio.Task[Any]] = field(default_factory=set)

piphi_runtime_kit_python/runtime/tasks.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+"""Helpers for creating and shutting down tracked background tasks."""
+
+import asyncio
+import contextlib
+from typing import Any
+
+from .state import RuntimeProcessState
+
+
+def track_background_task(
+    task: asyncio.Task[Any],
+    *,
+    process_state: RuntimeProcessState,
+) -> asyncio.Task[Any]:
+    """Register an already-created task so it can be cleaned up later."""
+    process_state.background_tasks.add(task)
+    task.add_done_callback(process_state.background_tasks.discard)
+    return task
+
+
+def create_tracked_task(
+    coro,
+    *,
+    process_state: RuntimeProcessState,
+) -> asyncio.Task[Any]:
+    """Create a task and automatically register it with the process state."""
+    return track_background_task(
+        asyncio.create_task(coro),
+        process_state=process_state,
+    )
+
+
+async def shutdown_background_tasks(process_state: RuntimeProcessState) -> None:
+    """Cancel and await all tracked background tasks still running."""
+    pending_tasks = [task for task in process_state.background_tasks if not task.done()]
+    for task in pending_tasks:
+        task.cancel()
+    for task in pending_tasks:
+        with contextlib.suppress(asyncio.CancelledError):
+            await task

piphi_runtime_kit_python/runtime/telemetry.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+"""Helpers for sending PiPhi telemetry back to Core."""
+
+import datetime as dt
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from ..schemas import TelemetryPayload
+from .auth import RuntimeAuthContext, build_runtime_auth_headers
+from .errors import classify_core_delivery_error
+from .state import RuntimeProcessState
+
+
+DEFAULT_CORE_BASE_URL = "http://127.0.0.1:31419"
+DEFAULT_TELEMETRY_PATH = "/api/v2/integrations/telemetry"
+DEFAULT_TIMEOUT_SECONDS = 3.0
+
+def build_core_auth_headers(
+    *,
+    container_id: str,
+    internal_token: str | None,
+) -> dict[str, str]:
+    """Build outbound Core auth headers using the standard PiPhi header names."""
+    return build_runtime_auth_headers(
+        container_id=container_id,
+        internal_token=internal_token,
+    )
+
+
+def build_telemetry_payload(
+    *,
+    device_id: str,
+    metrics: dict[str, Any],
+    units: dict[str, Any] | None = None,
+    timestamp: str | None = None,
+) -> TelemetryPayload:
+    """Build the standard telemetry payload expected by PiPhi Core."""
+    return TelemetryPayload(
+        device_id=device_id,
+        metrics=metrics,
+        timestamp=timestamp or dt.datetime.now(dt.timezone.utc).isoformat(),
+        units=units or {},
+    )
+
+
+@dataclass(slots=True)
+class TelemetryClient:
+    """Thin Core telemetry client for runtime integrations.
+
+    This helper reuses a shared Core HTTP client when one is available and
+    otherwise creates a short-lived client with the configured timeout.
+    """
+    process_state: RuntimeProcessState
+    core_base_url: str = DEFAULT_CORE_BASE_URL
+    telemetry_path: str = DEFAULT_TELEMETRY_PATH
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+
+    @property
+    def telemetry_url(self) -> str:
+        """Return the fully qualified Core telemetry endpoint URL."""
+        return f"{self.core_base_url.rstrip('/')}{self.telemetry_path}"
+
+    @asynccontextmanager
+    async def borrow_http_client(self):
+        """Yield a shared Core client when present, otherwise a temporary client."""
+        if self.process_state.core_http_client is not None:
+            yield self.process_state.core_http_client
+            return
+
+        async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+            yield client
+
+    async def send_metrics(
+        self,
+        *,
+        device_id: str,
+        metrics: dict[str, Any],
+        auth_context: RuntimeAuthContext,
+        container_id: str | None = None,
+        units: dict[str, Any] | None = None,
+        timestamp: str | None = None,
+    ) -> None:
+        """Send a telemetry payload for one device to PiPhi Core.
+
+        Typical usage:
+            await telemetry_client.send_metrics(
+                device_id="plug-1",
+                metrics={"is_on": True, "current_power_w": 12.4},
+                units={"current_power_w": "W"},
+                auth_context=runtime_context.auth,
+                container_id="runtime-123",
+            )
+        """
+        resolved_container_id, resolved_internal_token = auth_context.resolve(
+            container_id=container_id,
+        )
+        if not resolved_container_id:
+            return
+
+        payload = build_telemetry_payload(
+            device_id=device_id,
+            metrics=metrics,
+            units=units,
+            timestamp=timestamp,
+        )
+        headers = build_core_auth_headers(
+            container_id=resolved_container_id,
+            internal_token=resolved_internal_token,
+        )
+
+        async with self.borrow_http_client() as client:
+            try:
+                response = await client.post(
+                    self.telemetry_url,
+                    json=payload.model_dump(),
+                    headers=headers,
+                    timeout=self.timeout_seconds,
+                )
+                response.raise_for_status()
+            except (httpx.HTTPStatusError, httpx.ConnectError, httpx.ReadTimeout) as exc:
+                raise classify_core_delivery_error(
+                    exc=exc,
+                    operation="telemetry_delivery",
+                    url=self.telemetry_url,
+                    timeout_seconds=self.timeout_seconds,
+                ) from exc

piphi_runtime_kit_python/schemas.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+"""Framework-agnostic schema models shared by PiPhi runtime integrations."""
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class RuntimeConfig(BaseModel):
+    """Base runtime config model with a required config id and extensible fields."""
+    id: str
+    model_config = ConfigDict(extra="allow")
+
+
+class RuntimeConfigSnapshot(BaseModel):
+    """Snapshot payload sent from PiPhi Core to an integration runtime."""
+    container_id: str
+    integration_id: str | None = None
+    driver_pid: int | None = None
+    reason: str | None = None
+    generation: int | None = None
+    configs: list[RuntimeConfig] = Field(default_factory=list)
+
+
+class RuntimeConfigSyncResponse(BaseModel):
+    """Standard response body returned by runtime config sync endpoints."""
+    status: str
+    container_id: str
+    reason: str | None = None
+    generation: int | None = None
+    applied: list[str] = Field(default_factory=list)
+    removed: list[str] = Field(default_factory=list)
+    active_config_ids: list[str] = Field(default_factory=list)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeConfigApplyResponse(BaseModel):
+    """Standard response body returned after one config is applied."""
+    status: str = "configured"
+    config_id: str
+    container_id: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeConfigRemoveResponse(BaseModel):
+    """Standard response body returned after one config is removed."""
+    status: str = "deconfigured"
+    config_id: str
+    removed: bool = True
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class IntegrationDiscoveryRequest(BaseModel):
+    """Standard discovery request sent from PiPhi Core to a runtime."""
+    container_id: str | None = None
+    driver_pid: int | None = None
+    inputs: dict[str, Any] = Field(default_factory=dict)
+
+
+class IntegrationDiscoveryResponse(BaseModel):
+    """Standard discovery response returned by a runtime."""
+    devices: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class IntegrationCommandRequest(BaseModel):
+    """Standard command payload forwarded from PiPhi Core to a runtime."""
+    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)
+
+
+class IntegrationEventRequest(BaseModel):
+    """Generic event payload emitted by a runtime integration."""
+    event_type: str
+    source: str | None = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+
+class IntegrationEventListResponse(BaseModel):
+    """Standard response body for listing previously captured runtime events."""
+    events: list[dict[str, Any]] = Field(default_factory=list)
+
+
+class IntegrationEventIngestResponse(BaseModel):
+    """Standard response body returned after a runtime ingests an event."""
+    status: str = "accepted"
+    event: dict[str, Any] = Field(default_factory=dict)
+
+
+class EventSeverity(str, Enum):
+    """Supported severity values for events sent back to PiPhi Core."""
+    info = "info"
+    warning = "warning"
+    error = "error"
+    critical = "critical"
+
+
+class EventTransport(str, Enum):
+    """Supported transport labels for events sent back to PiPhi Core."""
+    rest = "rest"
+    mqtt = "mqtt"
+
+
+class CoreEventPayload(BaseModel):
+    """Canonical event payload posted from a runtime back to PiPhi Core."""
+    event_id: str
+    type: str
+    ts: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    integration_id: str | None = None
+    config_id: str | None = None
+    container_id: str | None = None
+    device_id: str | None = None
+    severity: EventSeverity = Field(default=EventSeverity.info)
+    transport: EventTransport = Field(default=EventTransport.rest)
+    topic: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    received_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class RuntimeHealthResponse(BaseModel):
+    """Standard health response body returned by runtime integrations."""
+    status: str = "ok"
+    integration: dict[str, Any] = Field(default_factory=dict)
+    runtime: dict[str, Any] = Field(default_factory=dict)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeDiagnosticsResponse(BaseModel):
+    """Standard diagnostics response body returned by runtime integrations."""
+    status: str = "ok"
+    integration: dict[str, Any] = Field(default_factory=dict)
+    diagnostics: dict[str, Any] = Field(default_factory=dict)
+
+
+class TelemetryPayload(BaseModel):
+    """Standard telemetry request body posted back to PiPhi Core."""
+    device_id: str
+    metrics: dict[str, Any] = Field(default_factory=dict)
+    timestamp: str
+    units: dict[str, Any] = Field(default_factory=dict)