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

piphi_runtime_kit_python/__init__.py

@@ -70,7 +70,7 @@ from .runtime.mqtt import (
 )
 from .runtime.registry import RuntimeRegistry
 from .runtime.state import RuntimeProcessState
-from .runtime.starter import RuntimeStarter, create_runtime_starter
+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 .schemas import (
@@ -80,6 +80,9 @@ from .schemas import (
     IntegrationCommandRequest,
     IntegrationDiscoveryRequest,
     IntegrationDiscoveryResponse,
+    RuntimeEntityDashboardResponse,
+    RuntimeEntitiesResponse,
+    RuntimeEntityResponse,
     IntegrationEventIngestResponse,
     IntegrationEventListResponse,
     IntegrationEventRequest,
@@ -110,6 +113,9 @@ __all__ = [
     "IntegrationCommandRequest",
     "IntegrationDiscoveryRequest",
     "IntegrationDiscoveryResponse",
+    "RuntimeEntityDashboardResponse",
+    "RuntimeEntitiesResponse",
+    "RuntimeEntityResponse",
     "IntegrationEventRequest",
     "RuntimeAuthContext",
     "RuntimeAuthHeaders",
@@ -141,6 +147,7 @@ __all__ = [
     "build_core_auth_headers",
     "build_config_apply_response",
     "build_config_remove_response",
+    "build_entities_response",
     "build_runtime_auth_headers",
     "build_runtime_diagnostics_response",
     "build_runtime_health_response",

piphi_runtime_kit_python/runtime/starter.py

@@ -11,6 +11,7 @@ from .events import DEFAULT_CORE_BASE_URL as DEFAULT_EVENTS_CORE_BASE_URL, Event
 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
+from ..schemas import RuntimeEntitiesResponse
 
 
 @dataclass(slots=True)
@@ -77,6 +78,34 @@ class RuntimeStarter:
             },
         )
 
+    def entities_response(
+        self,
+        *,
+        entities: list[dict[str, Any]],
+        capabilities: dict[str, Any] | None = None,
+        commands: dict[str, Any] | None = None,
+    ) -> RuntimeEntitiesResponse:
+        """Build the standard /entities response body for this runtime."""
+        return build_entities_response(
+            entities=entities,
+            capabilities=capabilities,
+            commands=commands,
+        )
+
+
+def build_entities_response(
+    *,
+    entities: list[dict[str, Any]],
+    capabilities: dict[str, Any] | None = None,
+    commands: dict[str, Any] | None = None,
+) -> RuntimeEntitiesResponse:
+    """Return the standard runtime /entities response wrapper."""
+    return RuntimeEntitiesResponse(
+        entities=entities,
+        capabilities=capabilities or {},
+        commands=commands or {},
+    )
+
 
 def create_runtime_starter(
     *,

piphi_runtime_kit_python/schemas.py

@@ -6,7 +6,7 @@ from datetime import datetime, timezone
 from enum import Enum
 from typing import Any
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 
 class RuntimeConfig(BaseModel):
@@ -74,6 +74,68 @@ class IntegrationCommandRequest(BaseModel):
     args: dict[str, Any] = Field(default_factory=dict)
 
 
+class RuntimeEntityDashboardResponse(BaseModel):
+    """Optional per-entity dashboard hints returned by a runtime."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    allowed_widgets: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("allowed_widgets", "allowedWidgets"),
+    )
+    default_widget: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("default_widget", "defaultWidget"),
+    )
+    recommended_widgets: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("recommended_widgets", "recommendedWidgets"),
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeEntityResponse(BaseModel):
+    """One live runtime entity tied to a configured device/account."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    id: str
+    name: str
+    capabilities: list[str] = Field(default_factory=list)
+    config_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("config_id", "configId"),
+    )
+    device_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("device_id", "deviceId"),
+    )
+    device_type: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("device_type", "deviceType"),
+    )
+    device_class: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("device_class", "deviceClass"),
+    )
+    entity_type: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("entity_type", "entityType"),
+    )
+    dashboard: RuntimeEntityDashboardResponse | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class RuntimeEntitiesResponse(BaseModel):
+    """Standard response body returned by runtime /entities endpoints."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    entities: list[RuntimeEntityResponse] = Field(default_factory=list)
+    capabilities: dict[str, Any] = Field(default_factory=dict)
+    commands: dict[str, Any] = Field(default_factory=dict)
+
+
 class IntegrationEventRequest(BaseModel):
     """Generic event payload emitted by a runtime integration."""
     event_type: str

{piphi_runtime_kit_python-0.3.0.dist-info → piphi_runtime_kit_python-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.3.0
+Version: 0.4.1
 Summary: PiPhi Network runtime integration helpers
 Keywords: piphi,runtime,integration,iot
 Author-Email: KelvinSan <support@piphi.network>
@@ -113,18 +113,28 @@ hide vendor logic behind an overly magical abstraction.
 
 The package currently supports Python `>=3.11`.
 
-Install from a local checkout:
+Install from PyPI:
 
 ```bash
-pdm add /path/to/piphi-runtime-kit-python
+pdm add piphi-runtime-kit-python
 ```
 
 If you need the optional FastAPI helpers:
 
 ```bash
-pdm add "/path/to/piphi-runtime-kit-python[fastapi]"
+pdm add "piphi-runtime-kit-python[fastapi]"
 ```
 
+If you prefer `pip`:
+
+```bash
+pip install piphi-runtime-kit-python
+```
+
+Package page:
+
+- https://pypi.org/project/piphi-runtime-kit-python/0.3.0/
+
 ## First 15 Minutes
 
 If you want the shortest path to a working runtime, do this:
@@ -160,9 +170,71 @@ These are the most common runtime routes and what they are for.
 | `/deconfigure` | `POST` | Usually | Remove one config | `RuntimeConfigRemoveResponse` |
 | `/events` | `GET` | Common | Show recent local runtime events | `build_event_list_response(...)` |
 | `/state` | `GET` | Common | Show current runtime state | `registry.entries`, `registry.state_snapshots` |
-| `/entities` | `GET` | Integration-specific | Show normalized entity list | integration-owned |
+| `/entities` | `GET` | Integration-specific | Show normalized entity list | `build_entities_response(...)`, `starter.entities_response(...)` |
 | `/ui` or `/ui-config` | `GET` | Optional | Return config UI metadata | integration-owned |
 
+## Modeling `/entities`
+
+For simple integrations, `/entities` can still be a plain list of generic
+entities.
+
+For smart-home and multi-device integrations, PiPhi now recommends a richer
+runtime-owned entity shape that ties each entity to a real saved config or
+device. That lets Core make better device-first dashboard suggestions, and it
+gives the frontend enough context to render better widget defaults for plugs,
+bulbs, thermostats, and other device-specific entities.
+
+Recommended fields:
+
+- `id`: stable runtime entity id
+- `name`: user-facing label
+- `capabilities`: actual capabilities for that specific device
+- `config_id` / `configId`: PiPhi config UUID when available
+- `device_id` / `deviceId`: integration-native device id
+- `device_type` / `device_class`: values like `plug`, `bulb`, `sensor`, `climate`
+- `entity_type`: values like `switch`, `light`, `sensor`, `media`
+- `dashboard.allowed_widgets`, `dashboard.default_widget`, `dashboard.recommended_widgets`: optional UI hints
+
+The SDK now includes `RuntimeEntityResponse`, `RuntimeEntitiesResponse`,
+`build_entities_response(...)`, and `starter.entities_response(...)` to make
+that payload easier to return.
+
+The helper returns the standard wrapper shape:
+
+- `entities`: the runtime-owned list you generated
+- `capabilities`: optional manifest capability metadata
+- `commands`: optional manifest command metadata
+
+```python
+from piphi_runtime_kit_python import build_entities_response
+
+@app.get("/entities")
+async def entities() -> dict[str, Any]:
+    return build_entities_response(
+        entities=[
+            {
+                "id": "office-plug",
+                "name": "Office Plug",
+                "config_id": "core-config-uuid",
+                "device_id": "office-plug",
+                "device_class": "plug",
+                "entity_type": "switch",
+                "capabilities": ["switch", "power", "energy_today"],
+                "dashboard": {
+                    "allowed_widgets": ["tile", "button", "stat"],
+                    "default_widget": "tile",
+                },
+            }
+        ],
+        capabilities=manifest["capabilities"],
+        commands=manifest.get("commands", {}),
+    ).model_dump(exclude_none=True)
+```
+
+If you are already using the starter object, the same response can be built with
+`starter.entities_response(...)` instead of calling the standalone helper
+directly.
+
 ## UI Config Endpoints
 
 Many integrations expose `/ui` or `/ui-config` so the PiPhi frontend knows how

{piphi_runtime_kit_python-0.3.0.dist-info → piphi_runtime_kit_python-0.4.1.dist-info}/RECORD

@@ -1,8 +1,8 @@
-piphi_runtime_kit_python-0.3.0.dist-info/METADATA,sha256=xrNx3CQWKqmAHmFVv5OXY2In7GQCSNAONP78SKeB-_M,28376
-piphi_runtime_kit_python-0.3.0.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
-piphi_runtime_kit_python-0.3.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-piphi_runtime_kit_python-0.3.0.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
-piphi_runtime_kit_python/__init__.py,sha256=ghbPOQY3QMbEZrH8xSH8ZS9rbpYwkuRITReOUtZ9NsU,5446
+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/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
@@ -19,9 +19,9 @@ piphi_runtime_kit_python/runtime/health.py,sha256=9YO0K_UCJKTe6uSFLgb1kStr5dAgtI
 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/starter.py,sha256=K62F_3qTy-HAjWYAs3TADeR_wwC0u9kCUbQbNK66ThI,3747
+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=NDG6g0BZZOEy35O5sz9_A4HlH-BnHyztOQMLbpKqF0E,4924
-piphi_runtime_kit_python-0.3.0.dist-info/RECORD,,
+piphi_runtime_kit_python/schemas.py,sha256=weCqTPFafourOVe1Me4282hezJ9jwttDtKLBHrEqlnU,7069
+piphi_runtime_kit_python-0.4.1.dist-info/RECORD,,