piphi-runtime-kit-python 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

piphi_runtime_kit_python/__init__.py

@@ -49,6 +49,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 +81,8 @@ from .schemas import (
     IntegrationCommandRequest,
     IntegrationDiscoveryRequest,
     IntegrationDiscoveryResponse,
+    RuntimeEntityCommandFieldResponse,
+    RuntimeEntityCommandResponse,
     RuntimeEntityDashboardResponse,
     RuntimeEntitiesResponse,
     RuntimeEntityResponse,
@@ -113,6 +116,8 @@ __all__ = [
     "IntegrationCommandRequest",
     "IntegrationDiscoveryRequest",
     "IntegrationDiscoveryResponse",
+    "RuntimeEntityCommandFieldResponse",
+    "RuntimeEntityCommandResponse",
     "RuntimeEntityDashboardResponse",
     "RuntimeEntitiesResponse",
     "RuntimeEntityResponse",
@@ -144,6 +149,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",
@@ -175,6 +181,8 @@ __all__ = [
     "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/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/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/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/schemas.py

@@ -11,8 +11,26 @@ 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):
@@ -94,6 +112,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 +178,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.1.dist-info → piphi_runtime_kit_python-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.4.1
+Version: 0.4.2
 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.dist-info → piphi_runtime_kit_python-0.4.2.dist-info}/RECORD

@@ -1,8 +1,8 @@
-piphi_runtime_kit_python-0.4.1.dist-info/METADATA,sha256=ug1yodvcOA6KxVr4DkKDbOvp_s7GI2GF1tFtnVdVhPw,30934
-piphi_runtime_kit_python-0.4.1.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
-piphi_runtime_kit_python-0.4.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-piphi_runtime_kit_python-0.4.1.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
-piphi_runtime_kit_python/__init__.py,sha256=_2HtSbXo2VN9267D-JFDBvX0Xvtzhhg4Y1d8KQ53W0Q,5692
+piphi_runtime_kit_python-0.4.2.dist-info/METADATA,sha256=th_AhsVfZ_at7LDyKQv7ZA1EVxiasOUwoSdTxQvdulI,30849
+piphi_runtime_kit_python-0.4.2.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
+piphi_runtime_kit_python-0.4.2.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+piphi_runtime_kit_python-0.4.2.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
+piphi_runtime_kit_python/__init__.py,sha256=P8yx6C1P88xuXWuf3D58d5zhUD-pprhBhbVeyNbDaJQ,6013
 piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
 piphi_runtime_kit_python/adapters/fastapi.py,sha256=1QcOBYprg6AmQVrkI8g61NIelBB_7BTbdvNaMvG2-s8,2098
 piphi_runtime_kit_python/fastapi.py,sha256=OZ-ds2-g32kB4YkF90D5bM4vVVjpOWPtrNC-WdhDNyo,361
@@ -12,16 +12,17 @@ piphi_runtime_kit_python/runtime/config_sync.py,sha256=IzsH5AGxnISISWx8OYfNMTk2O
 piphi_runtime_kit_python/runtime/configuration.py,sha256=4kkoJeENOhJHeNvC9QDu81ejDJUQJG7S5GmQG1sv3YQ,3631
 piphi_runtime_kit_python/runtime/context.py,sha256=CwXgrivciBd7eTREn0u0zjqkDPy6VthASW-gsoZqCTg,1109
 piphi_runtime_kit_python/runtime/discovery.py,sha256=uH6rJ4BnLVukTCxu2QwvN8yJhsI_fcT29VEat62oBcY,2274
-piphi_runtime_kit_python/runtime/dispatch.py,sha256=N0Fxqd9QLkareAOX4aOGBBzQpPU3-v5vDxbWEill0zI,6218
+piphi_runtime_kit_python/runtime/dispatch.py,sha256=QcbA9B5izyyg0znlKHq94dbr-oqHVxKW2LCjrQKYfkY,7341
 piphi_runtime_kit_python/runtime/errors.py,sha256=_mjqmJLsdM5NfrTwb6YFkhheqPfn6Df-QtAKgl9U6QU,4120
 piphi_runtime_kit_python/runtime/events.py,sha256=JcvrTZlJ-vgY237jTDVOAVTbSxbcuh9u2QCdOGyuduA,6543
 piphi_runtime_kit_python/runtime/health.py,sha256=9YO0K_UCJKTe6uSFLgb1kStr5dAgtIUc8Ha0dnRi2vA,1880
+piphi_runtime_kit_python/runtime/identity.py,sha256=cth0_QHR9R5LTdp-6DPD1IhM8cYJT5HB1OUQYW7kLGs,2762
 piphi_runtime_kit_python/runtime/lifespan.py,sha256=mVSdZZAS66xlcnlzAwkztFjzw_l2pyLrJqULJsb0Ezk,2850
 piphi_runtime_kit_python/runtime/mqtt.py,sha256=JKMN5zxg1BcOidu7TaYnuRD3HuoAJ_WcvXMTTSlAteo,6069
-piphi_runtime_kit_python/runtime/registry.py,sha256=AOpd5NgwSAhN8Us8nLW6084GrMtitMMaQP916EpMZrk,3103
+piphi_runtime_kit_python/runtime/registry.py,sha256=8rKLCWt1_0SlDm3TepEUGDliOhVEDTv_zYR0kxLpSHM,3373
 piphi_runtime_kit_python/runtime/starter.py,sha256=j5C4GOOcRHNLJ-HYu8fmf3bE00baDOzAfuq1MefT-Jg,4651
 piphi_runtime_kit_python/runtime/state.py,sha256=4xvQGTT59DF9rXHAtM3kDyV_UGg2a9tLPvGiCp_PFMc,674
 piphi_runtime_kit_python/runtime/tasks.py,sha256=gMd-2K96jMU8tCPvI12xdWxuyNt5gsLDss2QWOoM94k,1241
 piphi_runtime_kit_python/runtime/telemetry.py,sha256=RN6SFrhmAZ7aJLyioQMBzJEFsxQgOjjA1pV5qNeaR4E,4279
-piphi_runtime_kit_python/schemas.py,sha256=weCqTPFafourOVe1Me4282hezJ9jwttDtKLBHrEqlnU,7069
-piphi_runtime_kit_python-0.4.1.dist-info/RECORD,,
+piphi_runtime_kit_python/schemas.py,sha256=LGz53OHmWwUEQb_nHbVBgRDGVGowJPT53S2P7otP3lo,9073
+piphi_runtime_kit_python-0.4.2.dist-info/RECORD,,