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

piphi_runtime_kit_python/__init__.py

@@ -63,8 +63,17 @@ from .runtime.events import (
     format_event_log,
     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.health import (
+    build_runtime_diagnostics_response,
+    build_runtime_health_response,
+)
+from .runtime.identity import (
+    RuntimeDeviceRef,
+    RuntimeIdentityError,
+    build_runtime_identity,
+    resolve_config_id,
+    resolve_device_id,
+)
 from .runtime.lifespan import (
     DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
     DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
@@ -86,9 +95,24 @@ from .runtime.mqtt import (
 )
 from .runtime.registry import RuntimeRegistry
 from .runtime.state import RuntimeProcessState
-from .runtime.starter import RuntimeStarter, build_entities_response, create_runtime_starter
-from .runtime.tasks import create_tracked_task, shutdown_background_tasks, track_background_task
-from .runtime.telemetry import TelemetryClient, build_core_auth_headers
+from .runtime.starter import (
+    RuntimeStarter,
+    build_entities_response,
+    create_runtime_starter,
+)
+from .runtime.tasks import (
+    BackgroundTaskLimitError,
+    create_tracked_task,
+    shutdown_background_tasks,
+    track_background_task,
+)
+from .runtime.telemetry import (
+    TelemetryClient,
+    TelemetryReading,
+    TelemetryValue,
+    build_core_auth_headers,
+    build_telemetry_maps,
+)
 from .schemas import (
     CoreEventPayload,
     EventSeverity,
@@ -115,6 +139,7 @@ from .schemas import (
 )
 
 __all__ = [
+    "BackgroundTaskLimitError",
     "ConfigSyncCoordinator",
     "CoreAuthError",
     "CoreDeliveryError",
@@ -150,12 +175,16 @@ __all__ = [
     "RuntimeConfigSnapshot",
     "RuntimeConfigSyncResponse",
     "RuntimeContext",
+    "RuntimeDeviceRef",
+    "RuntimeIdentityError",
     "RuntimeRegistry",
     "RuntimeProcessState",
     "RuntimeStarter",
     "RuntimeDiagnosticsResponse",
     "RuntimeHealthResponse",
     "TelemetryClient",
+    "TelemetryReading",
+    "TelemetryValue",
     "EventClient",
     "TelemetryPayload",
     "CoreEventPayload",
@@ -172,6 +201,7 @@ __all__ = [
     "build_local_event_record",
     "build_runtime_identity",
     "build_core_auth_headers",
+    "build_telemetry_maps",
     "build_config_apply_response",
     "build_config_remove_response",
     "build_entities_response",

piphi_runtime_kit_python/adapters/fastapi.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Optional FastAPI-facing helpers for common PiPhi runtime patterns."""
 
+from __future__ import annotations
+
 from typing import TYPE_CHECKING, Any, Mapping
 
 from ..runtime.auth import RuntimeAuthHeaders

piphi_runtime_kit_python/py.typed

@@ -0,0 +1 @@
+

piphi_runtime_kit_python/runtime/__init__.py

@@ -8,7 +8,11 @@ from .auth import (
     format_runtime_auth_sync_log,
     mask_token,
 )
-from .config_sync import ConfigSyncCoordinator, build_sync_response, reconcile_config_ids
+from .config_sync import (
+    ConfigSyncCoordinator,
+    build_sync_response,
+    reconcile_config_ids,
+)
 from .configuration import (
     build_config_apply_response,
     build_config_remove_response,
@@ -49,6 +53,7 @@ from .events import (
     normalize_event_payload,
 )
 from .health import build_runtime_diagnostics_response, build_runtime_health_response
+from .identity import RuntimeDeviceRef, RuntimeIdentityError
 from .lifespan import (
     DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
     DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
@@ -60,10 +65,22 @@ from .lifespan import (
 from .registry import RuntimeRegistry
 from .state import RuntimeProcessState
 from .starter import RuntimeStarter, create_runtime_starter
-from .tasks import create_tracked_task, shutdown_background_tasks, track_background_task
-from .telemetry import TelemetryClient, build_core_auth_headers
+from .tasks import (
+    BackgroundTaskLimitError,
+    create_tracked_task,
+    shutdown_background_tasks,
+    track_background_task,
+)
+from .telemetry import (
+    TelemetryClient,
+    TelemetryReading,
+    TelemetryValue,
+    build_core_auth_headers,
+    build_telemetry_maps,
+)
 
 __all__ = [
+    "BackgroundTaskLimitError",
     "ConfigSyncCoordinator",
     "CoreAuthError",
     "CoreDeliveryError",
@@ -77,10 +94,14 @@ __all__ = [
     "RuntimeAuthContext",
     "RuntimeAuthHeaders",
     "RuntimeContext",
+    "RuntimeDeviceRef",
+    "RuntimeIdentityError",
     "RuntimeRegistry",
     "RuntimeProcessState",
     "RuntimeStarter",
     "TelemetryClient",
+    "TelemetryReading",
+    "TelemetryValue",
     "EventClient",
     "build_local_event_record",
     "build_config_apply_response",
@@ -90,6 +111,7 @@ __all__ = [
     "build_event_ingest_response",
     "build_event_list_response",
     "build_core_auth_headers",
+    "build_telemetry_maps",
     "build_runtime_auth_headers",
     "build_sync_response",
     "bind_core_http_client",

piphi_runtime_kit_python/runtime/auth.py

@@ -1,15 +1,15 @@
-from __future__ import annotations
-
 """Helpers for resolving PiPhi runtime auth across requests and background work."""
 
+from __future__ import annotations
+
 import os
 from dataclasses import dataclass
 from typing import Any, Mapping
 
 
-DEFAULT_INTERNAL_TOKEN_ENV_NAME = "PIPHI_INTEGRATION_INTERNAL_TOKEN"
+DEFAULT_INTERNAL_TOKEN_ENV_NAME = "PIPHI_INTEGRATION_INTERNAL_TOKEN"  # nosec B105
 RUNTIME_CONTAINER_ID_HEADER_NAME = "X-Container-Id"
-RUNTIME_INTERNAL_TOKEN_HEADER_NAME = "X-PiPhi-Integration-Token"
+RUNTIME_INTERNAL_TOKEN_HEADER_NAME = "X-PiPhi-Integration-Token"  # nosec B105
 
 
 def mask_token(token: str | None) -> str:
@@ -32,6 +32,7 @@ def _get_header_value(headers: Mapping[str, Any], name: str) -> str:
 @dataclass(slots=True, frozen=True)
 class RuntimeAuthHeaders:
     """Normalized PiPhi runtime auth values extracted from request headers."""
+
     container_id: str = ""
     internal_token: str = ""
 
@@ -81,6 +82,7 @@ class RuntimeAuthContext:
     Integrations can keep the most recent container scope and internal token here,
     then reuse it for outbound telemetry or config sync calls.
     """
+
     container_id: str = ""
     internal_token: str = ""
 
@@ -130,5 +132,7 @@ class RuntimeAuthContext:
     ) -> tuple[str, str]:
         """Resolve the effective container scope and internal token for a request."""
         resolved_container_id = str(container_id or "").strip() or self.container_id
-        resolved_internal_token = self.internal_token or (os.getenv(token_env_name) or "").strip()
+        resolved_internal_token = (
+            self.internal_token or (os.getenv(token_env_name) or "").strip()
+        )
         return resolved_container_id, resolved_internal_token

piphi_runtime_kit_python/runtime/config_sync.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Helpers for basic config-sync orchestration and generation tracking."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 import json
 import os
@@ -36,7 +36,9 @@ def resolve_core_base_url(default: str | None = None) -> str | None:
     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
+    return (
+        default.rstrip("/") if isinstance(default, str) and default.strip() else default
+    )
 
 
 def resolve_runtime_config_snapshot_path(
@@ -164,7 +166,7 @@ def build_runtime_config_snapshot_from_core_rows(
     rows: list[dict[str, Any]],
     *,
     container_id: str,
-    config_model: type[TConfig] = RuntimeConfig,
+    config_model: type[TConfig] = RuntimeConfig,  # type: ignore[assignment]
     snapshot_model: type[Any] = RuntimeConfigSnapshot,
     reason: str = "startup_rehydrate",
 ) -> Any:
@@ -200,7 +202,7 @@ async def fetch_core_runtime_config_snapshot(
     runtime_context: RuntimeContext,
     client: httpx.AsyncClient,
     core_base_url: str | None = None,
-    config_model: type[TConfig] = RuntimeConfig,
+    config_model: type[TConfig] = RuntimeConfig,  # type: ignore[assignment]
     snapshot_model: type[Any] = RuntimeConfigSnapshot,
     timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
     reason: str = "startup_rehydrate",
@@ -247,7 +249,7 @@ async def rehydrate_runtime_configs(
     runtime_context: RuntimeContext,
     client: httpx.AsyncClient,
     apply_snapshot: SnapshotApplyCallable,
-    config_model: type[TConfig] = RuntimeConfig,
+    config_model: type[TConfig] = RuntimeConfig,  # type: ignore[assignment]
     snapshot_model: type[Any] = RuntimeConfigSnapshot,
     core_base_url: str | None = None,
     timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
@@ -338,7 +340,7 @@ def build_sync_response(
     applied: list[str] | None = None,
     removed: list[str] | None = None,
     active_config_ids: list[str] | None = None,
-    metadata: dict | None = None,
+    metadata: dict[str, Any] | None = None,
 ) -> RuntimeConfigSyncResponse:
     """Build a standard PiPhi config-sync response payload."""
     return RuntimeConfigSyncResponse(
@@ -360,6 +362,7 @@ class ConfigSyncCoordinator:
     This class intentionally stays small. It helps integrations decide whether
     an incoming snapshot is stale and keeps generation tracking in one place.
     """
+
     process_state: RuntimeProcessState
 
     def get_current_generation(self) -> int | None:
@@ -443,7 +446,9 @@ class ConfigSyncCoordinator:
 
         current_generation = self.mark_generation(snapshot.generation)
         next_active_config_ids = (
-            get_active_config_ids() if get_active_config_ids is not None else incoming_ids
+            get_active_config_ids()
+            if get_active_config_ids is not None
+            else incoming_ids
         )
 
         return build_sync_response(

piphi_runtime_kit_python/runtime/configuration.py

@@ -1,10 +1,14 @@
-from __future__ import annotations
-
 """Helpers for typed runtime config handling, safe logging, and responses."""
 
+from __future__ import annotations
+
 from typing import Any, Mapping, TypeVar
 
-from ..schemas import RuntimeConfig, RuntimeConfigApplyResponse, RuntimeConfigRemoveResponse
+from ..schemas import (
+    RuntimeConfig,
+    RuntimeConfigApplyResponse,
+    RuntimeConfigRemoveResponse,
+)
 
 TConfig = TypeVar("TConfig", bound=RuntimeConfig)
 
@@ -53,7 +57,9 @@ def format_config_apply_log(
     secret_keys: tuple[str, ...] = DEFAULT_CONFIG_SECRET_KEYS,
 ) -> str:
     """Build a consistent config lifecycle log message with redacted values."""
-    raw_payload = payload.model_dump() if isinstance(payload, RuntimeConfig) else dict(payload)
+    raw_payload = (
+        payload.model_dump() if isinstance(payload, RuntimeConfig) else dict(payload)
+    )
     config_id = str(raw_payload.get("id") or "missing")
     container_id = str(raw_payload.get("container_id") or "missing")
     redacted_payload = redact_config_secrets(raw_payload, secret_keys=secret_keys)
@@ -97,7 +103,9 @@ def build_config_remove_response(
     )
 
 
-def validate_typed_config(payload: TConfig | Mapping[str, Any], config_model: type[TConfig]) -> TConfig:
+def validate_typed_config(
+    payload: TConfig | Mapping[str, Any], config_model: type[TConfig]
+) -> TConfig:
     """Validate one config payload against an integration-specific RuntimeConfig subclass."""
     if isinstance(payload, config_model):
         return payload

piphi_runtime_kit_python/runtime/context.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Higher-level runtime context that bundles auth and process state together."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 
 import httpx
@@ -17,6 +17,7 @@ class RuntimeContext:
     This is the easiest entry point when an integration wants one object that
     carries both request/runtime auth state and process-scoped helper state.
     """
+
     auth: RuntimeAuthContext = field(default_factory=RuntimeAuthContext)
     process_state: RuntimeProcessState = field(default_factory=RuntimeProcessState)
 

piphi_runtime_kit_python/runtime/discovery.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Helpers for thin, framework-agnostic discovery request/response handling."""
 
+from __future__ import annotations
+
 from typing import Any, Iterable, Mapping
 
 from ..schemas import IntegrationDiscoveryResponse

piphi_runtime_kit_python/runtime/dispatch.py

@@ -1,16 +1,20 @@
-from __future__ import annotations
-
 """Helpers for background dispatch of telemetry and event delivery."""
 
+from __future__ import annotations
+
 import asyncio
-from typing import Any, Callable, Mapping
+import datetime as dt
+import random
+from collections.abc import Awaitable
+from typing import Any, Callable, Mapping, TypeVar
+from uuid import uuid4
 
+from .auth import RuntimeAuthContext
 from .errors import CoreDeliveryError
 from .events import EventClient
+from .state import RuntimeProcessState
 from .tasks import create_tracked_task
 from .telemetry import TelemetryClient
-from .auth import RuntimeAuthContext
-from .state import RuntimeProcessState
 
 EventRecorder = Callable[[dict[str, Any]], Any]
 SkipHandler = Callable[[str, dict[str, Any]], Any]
@@ -18,6 +22,8 @@ ErrorHandler = Callable[[Exception, dict[str, Any]], Any]
 
 DEFAULT_RETRYABLE_DELIVERY_ATTEMPTS = 5
 DEFAULT_RETRYABLE_DELIVERY_INITIAL_DELAY_SECONDS = 0.5
+DEFAULT_RETRYABLE_DELIVERY_JITTER_RATIO = 0.2
+TDelivery = TypeVar("TDelivery")
 
 
 def build_local_event_record(
@@ -27,9 +33,12 @@ def build_local_event_record(
     payload: Mapping[str, Any] | None = None,
     source: str,
     severity: str,
+    event_id: str | None = None,
+    ts: str | dt.datetime | None = None,
+    topic: str | None = None,
 ) -> dict[str, Any]:
     """Build the canonical local runtime event record shape."""
-    return {
+    record = {
         "event_type": event_type,
         "source": source,
         "payload": dict(payload or {}),
@@ -39,28 +48,35 @@ def build_local_event_record(
         "config_id": device.get("config_id"),
         "severity": severity,
     }
+    if event_id is not None:
+        record["event_id"] = event_id
+    if ts is not None:
+        record["ts"] = ts.isoformat() if isinstance(ts, dt.datetime) else ts
+    if topic is not None:
+        record["topic"] = topic
+    return record
 
 
 async def _run_with_retryable_core_delivery_backoff(
-    delivery: Callable[[], Any],
+    delivery: Callable[[], Awaitable[TDelivery]],
     *,
     max_attempts: int = DEFAULT_RETRYABLE_DELIVERY_ATTEMPTS,
     initial_delay_seconds: float = DEFAULT_RETRYABLE_DELIVERY_INITIAL_DELAY_SECONDS,
-) -> Any:
+    jitter_ratio: float = DEFAULT_RETRYABLE_DELIVERY_JITTER_RATIO,
+    random_value: Callable[[], float] = random.random,
+) -> TDelivery:
     """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
+            return await delivery()
         except CoreDeliveryError as exc:
             if not exc.retryable or attempt >= max_attempts:
                 raise
-            await asyncio.sleep(delay_seconds)
+            jitter_multiplier = 1 - jitter_ratio + (2 * jitter_ratio * random_value())
+            await asyncio.sleep(delay_seconds * jitter_multiplier)
             attempt += 1
             delay_seconds *= 2
 
@@ -71,6 +87,7 @@ async def dispatch_telemetry_delivery(
     auth_context: RuntimeAuthContext,
     device_id: str,
     metrics: dict[str, Any],
+    config_id: str | None = None,
     container_id: str | None = None,
     units: dict[str, Any] | None = None,
     timestamp: str | None = None,
@@ -87,21 +104,31 @@ async def dispatch_telemetry_delivery(
             )
         return False
 
+    resolved_timestamp = timestamp or dt.datetime.now(dt.timezone.utc).isoformat()
+
     try:
         await _run_with_retryable_core_delivery_backoff(
             lambda: telemetry_client.send_metrics(
                 device_id=device_id,
                 metrics=metrics,
                 auth_context=auth_context,
+                config_id=config_id,
                 container_id=resolved_container_id,
                 units=units,
-                timestamp=timestamp,
+                timestamp=resolved_timestamp,
             )
         )
         return True
     except Exception as exc:
         if on_error is not None:
-            on_error(exc, {"device_id": device_id, "container_id": resolved_container_id})
+            on_error(
+                exc,
+                {
+                    "device_id": device_id,
+                    "config_id": config_id,
+                    "container_id": resolved_container_id,
+                },
+            )
             return False
         raise
 
@@ -113,12 +140,13 @@ def schedule_telemetry_delivery(
     auth_context: RuntimeAuthContext,
     device_id: str,
     metrics: dict[str, Any],
+    config_id: str | None = None,
     container_id: str | None = None,
     units: dict[str, Any] | None = None,
     timestamp: str | None = None,
     on_skipped: SkipHandler | None = None,
     on_error: ErrorHandler | None = None,
-):
+) -> asyncio.Task[bool]:
     """Schedule background telemetry delivery on the tracked runtime task set."""
     return create_tracked_task(
         dispatch_telemetry_delivery(
@@ -126,6 +154,7 @@ def schedule_telemetry_delivery(
             auth_context=auth_context,
             device_id=device_id,
             metrics=metrics,
+            config_id=config_id,
             container_id=container_id,
             units=units,
             timestamp=timestamp,
@@ -145,10 +174,16 @@ async def dispatch_event_delivery(
     payload: Mapping[str, Any] | None = None,
     source: str,
     severity: str = "info",
+    event_id: str | None = None,
+    ts: str | dt.datetime | None = None,
+    topic: str | None = None,
     on_skipped: SkipHandler | None = None,
     on_error: ErrorHandler | None = None,
 ) -> bool:
     """Send one event to Core and return whether delivery succeeded."""
+    resolved_event_id = event_id or uuid4().hex
+    resolved_ts = ts or dt.datetime.now(dt.timezone.utc)
+
     try:
         event_sent = await _run_with_retryable_core_delivery_backoff(
             lambda: event_client.send_event(
@@ -161,6 +196,9 @@ async def dispatch_event_delivery(
                 payload=payload,
                 source=source,
                 severity=severity,
+                event_id=resolved_event_id,
+                ts=resolved_ts,
+                topic=topic,
             )
         )
         if not event_sent and on_skipped is not None:
@@ -199,11 +237,17 @@ def schedule_event_delivery(
     payload: Mapping[str, Any] | None = None,
     source: str,
     severity: str = "info",
+    event_id: str | None = None,
+    ts: str | dt.datetime | None = None,
+    topic: str | None = None,
     record_event: EventRecorder | None = None,
     on_skipped: SkipHandler | None = None,
     on_error: ErrorHandler | None = None,
-):
+) -> asyncio.Task[bool]:
     """Record an optional local event and schedule delivery to Core."""
+    resolved_event_id = event_id or uuid4().hex
+    resolved_ts = ts or dt.datetime.now(dt.timezone.utc)
+
     if record_event is not None:
         record_event(
             build_local_event_record(
@@ -212,6 +256,9 @@ def schedule_event_delivery(
                 payload=payload,
                 source=source,
                 severity=severity,
+                event_id=resolved_event_id,
+                ts=resolved_ts,
+                topic=topic,
             )
         )
     return create_tracked_task(
@@ -223,6 +270,9 @@ def schedule_event_delivery(
             payload=payload,
             source=source,
             severity=severity,
+            event_id=resolved_event_id,
+            ts=resolved_ts,
+            topic=topic,
             on_skipped=on_skipped,
             on_error=on_error,
         ),

piphi_runtime_kit_python/runtime/errors.py

@@ -1,7 +1,7 @@
-from __future__ import annotations
-
 """Typed delivery errors for PiPhi runtime-to-Core communication."""
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 
 import httpx
@@ -66,7 +66,7 @@ def classify_core_delivery_error(
     timeout_seconds: float | None,
 ) -> CoreDeliveryError:
     """Convert raw HTTP client exceptions into stable PiPhi delivery errors."""
-    if isinstance(exc, httpx.ReadTimeout):
+    if isinstance(exc, httpx.TimeoutException):
         return CoreTimeoutError(
             operation=operation,
             url=url,
@@ -75,7 +75,7 @@ def classify_core_delivery_error(
             timeout_seconds=timeout_seconds,
         )
 
-    if isinstance(exc, httpx.ConnectError):
+    if isinstance(exc, httpx.TransportError):
         return CoreUnavailableError(
             operation=operation,
             url=url,