piphi-runtime-kit-python 0.8.1__py3-none-any.whl → 0.9.3__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- piphi_runtime_kit_python/__init__.py +36 -0
- piphi_runtime_kit_python/camera.py +237 -0
- {piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/METADATA +2 -1
- {piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/RECORD +7 -6
- {piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/WHEEL +0 -0
- {piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/entry_points.txt +0 -0
- {piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/licenses/LICENSE +0 -0
|
@@ -14,6 +14,25 @@ from .automations import (
|
|
|
14
14
|
audit_behaviors_contract,
|
|
15
15
|
build_mock_automation_event,
|
|
16
16
|
)
|
|
17
|
+
from .camera import (
|
|
18
|
+
CAMERA_MAX_SDP_BYTES,
|
|
19
|
+
CAMERA_MAX_SNAPSHOT_BYTES,
|
|
20
|
+
CAMERA_MAX_SOURCE_URL_BYTES,
|
|
21
|
+
CAMERA_MEDIA_CONTRACT_VERSION,
|
|
22
|
+
CameraCapabilityDeclaration,
|
|
23
|
+
CameraCapabilityEndpoints,
|
|
24
|
+
CameraMediaError,
|
|
25
|
+
CameraMediaProvider,
|
|
26
|
+
CameraSessionClose,
|
|
27
|
+
CameraSessionOffer,
|
|
28
|
+
CameraSessionOpened,
|
|
29
|
+
CameraSidecarSessionOpen,
|
|
30
|
+
CameraSidecarStatus,
|
|
31
|
+
CameraSnapshotRequest,
|
|
32
|
+
CameraSourceDescriptor,
|
|
33
|
+
CameraSourceResolver,
|
|
34
|
+
CameraWebRtcOffer,
|
|
35
|
+
)
|
|
17
36
|
from .runtime.auth import (
|
|
18
37
|
RUNTIME_CONTAINER_ID_HEADER_NAME,
|
|
19
38
|
RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
|
|
@@ -156,6 +175,10 @@ from .schemas import (
|
|
|
156
175
|
)
|
|
157
176
|
|
|
158
177
|
__all__ = [
|
|
178
|
+
"CAMERA_MAX_SDP_BYTES",
|
|
179
|
+
"CAMERA_MAX_SNAPSHOT_BYTES",
|
|
180
|
+
"CAMERA_MAX_SOURCE_URL_BYTES",
|
|
181
|
+
"CAMERA_MEDIA_CONTRACT_VERSION",
|
|
159
182
|
"CORE_BASE_URL_ENV_NAME",
|
|
160
183
|
"DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS",
|
|
161
184
|
"DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME",
|
|
@@ -176,6 +199,19 @@ __all__ = [
|
|
|
176
199
|
"AutomationIdempotencyStore",
|
|
177
200
|
"AutomationRegistry",
|
|
178
201
|
"BackgroundTaskLimitError",
|
|
202
|
+
"CameraCapabilityDeclaration",
|
|
203
|
+
"CameraCapabilityEndpoints",
|
|
204
|
+
"CameraMediaError",
|
|
205
|
+
"CameraMediaProvider",
|
|
206
|
+
"CameraSessionClose",
|
|
207
|
+
"CameraSessionOffer",
|
|
208
|
+
"CameraSessionOpened",
|
|
209
|
+
"CameraSidecarSessionOpen",
|
|
210
|
+
"CameraSidecarStatus",
|
|
211
|
+
"CameraSnapshotRequest",
|
|
212
|
+
"CameraSourceDescriptor",
|
|
213
|
+
"CameraSourceResolver",
|
|
214
|
+
"CameraWebRtcOffer",
|
|
179
215
|
"ConfigSyncCoordinator",
|
|
180
216
|
"CoreAuthError",
|
|
181
217
|
"CoreDeliveryError",
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
"""Versioned camera-media contract helpers for PiPhi runtimes."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Awaitable, Callable
|
|
6
|
+
from typing import Literal, Protocol
|
|
7
|
+
from urllib.parse import urlsplit
|
|
8
|
+
|
|
9
|
+
from pydantic import BaseModel, ConfigDict, Field, model_validator
|
|
10
|
+
|
|
11
|
+
CAMERA_MEDIA_CONTRACT_VERSION: Literal["camera.media.v1"] = "camera.media.v1"
|
|
12
|
+
CAMERA_MAX_SDP_BYTES = 256 * 1024
|
|
13
|
+
CAMERA_MAX_SOURCE_URL_BYTES = 4096
|
|
14
|
+
CAMERA_MAX_SNAPSHOT_BYTES = 8 * 1024 * 1024
|
|
15
|
+
|
|
16
|
+
CameraMediaTransport = Literal["snapshot", "webrtc", "hls"]
|
|
17
|
+
CameraSourceProtocol = Literal["rtsp", "rtsps", "http", "https"]
|
|
18
|
+
CameraSourceTransport = Literal["tcp", "udp", "auto"]
|
|
19
|
+
CameraMediaAudience = Literal["browser-core", "core-sidecar"]
|
|
20
|
+
CameraErrorCode = Literal[
|
|
21
|
+
"CAMERA_OFFLINE",
|
|
22
|
+
"CAMERA_ACCESS_DENIED",
|
|
23
|
+
"CAMERA_SOURCE_INVALID",
|
|
24
|
+
"CAMERA_CODEC_UNSUPPORTED",
|
|
25
|
+
"CAMERA_SIDECAR_UNAVAILABLE",
|
|
26
|
+
"CAMERA_CAPACITY_REACHED",
|
|
27
|
+
"CAMERA_SESSION_EXPIRED",
|
|
28
|
+
"CAMERA_NEGOTIATION_FAILED",
|
|
29
|
+
"CAMERA_SNAPSHOT_UNAVAILABLE",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class CameraContractModel(BaseModel):
|
|
34
|
+
"""Closed base model used by every camera-media message."""
|
|
35
|
+
|
|
36
|
+
model_config = ConfigDict(extra="forbid")
|
|
37
|
+
|
|
38
|
+
contract_version: Literal["camera.media.v1"] = CAMERA_MEDIA_CONTRACT_VERSION
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class CameraCapabilityEndpoints(BaseModel):
|
|
42
|
+
"""Path-only runtime endpoints declared for one camera capability."""
|
|
43
|
+
|
|
44
|
+
model_config = ConfigDict(extra="forbid")
|
|
45
|
+
|
|
46
|
+
source: str | None = None
|
|
47
|
+
snapshot: str | None = None
|
|
48
|
+
events: str | None = None
|
|
49
|
+
hls: str | None = None
|
|
50
|
+
webrtc: str | None = None
|
|
51
|
+
webrtc_close: str | None = None
|
|
52
|
+
|
|
53
|
+
@model_validator(mode="after")
|
|
54
|
+
def validate_paths(self) -> CameraCapabilityEndpoints:
|
|
55
|
+
values = [
|
|
56
|
+
self.source,
|
|
57
|
+
self.snapshot,
|
|
58
|
+
self.events,
|
|
59
|
+
self.hls,
|
|
60
|
+
self.webrtc,
|
|
61
|
+
self.webrtc_close,
|
|
62
|
+
]
|
|
63
|
+
if not any(values):
|
|
64
|
+
raise ValueError("at least one camera endpoint is required")
|
|
65
|
+
for value in (entry for entry in values if entry is not None):
|
|
66
|
+
if (
|
|
67
|
+
not value.startswith("/")
|
|
68
|
+
or value.startswith("//")
|
|
69
|
+
or "\\" in value
|
|
70
|
+
or any(segment in {".", ".."} for segment in value.split("/"))
|
|
71
|
+
):
|
|
72
|
+
raise ValueError("camera endpoints must be safe path-only values")
|
|
73
|
+
return self
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
class CameraCapabilityDeclaration(CameraContractModel):
|
|
77
|
+
"""Portable camera capability metadata shared with Core."""
|
|
78
|
+
|
|
79
|
+
message_type: Literal["camera.capability"] = "camera.capability"
|
|
80
|
+
capability_id: str = Field(min_length=1, max_length=300, pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
|
|
81
|
+
transports: list[CameraMediaTransport] = Field(min_length=1)
|
|
82
|
+
audio_available: bool = False
|
|
83
|
+
recording_available: bool = False
|
|
84
|
+
refresh_seconds: int = Field(default=15, ge=2, le=300)
|
|
85
|
+
endpoints: CameraCapabilityEndpoints
|
|
86
|
+
|
|
87
|
+
@model_validator(mode="after")
|
|
88
|
+
def validate_transports(self) -> CameraCapabilityDeclaration:
|
|
89
|
+
if len(self.transports) != len(set(self.transports)):
|
|
90
|
+
raise ValueError("camera transports must be unique")
|
|
91
|
+
required_endpoints = {
|
|
92
|
+
"snapshot": self.endpoints.snapshot,
|
|
93
|
+
"hls": self.endpoints.hls,
|
|
94
|
+
"webrtc": self.endpoints.webrtc,
|
|
95
|
+
}
|
|
96
|
+
for transport, endpoint in required_endpoints.items():
|
|
97
|
+
if transport in self.transports and endpoint is None and self.endpoints.source is None:
|
|
98
|
+
raise ValueError(f"{transport} requires its endpoint or a protected source endpoint")
|
|
99
|
+
return self
|
|
100
|
+
|
|
101
|
+
def manifest_capability(self) -> dict[str, object]:
|
|
102
|
+
"""Return the current PiPhi manifest representation."""
|
|
103
|
+
|
|
104
|
+
camera: dict[str, object] = {
|
|
105
|
+
"contract_version": CAMERA_MEDIA_CONTRACT_VERSION,
|
|
106
|
+
"refresh_seconds": self.refresh_seconds,
|
|
107
|
+
}
|
|
108
|
+
endpoint_keys = {
|
|
109
|
+
"source": "gateway_source_endpoint",
|
|
110
|
+
"snapshot": "snapshot_endpoint",
|
|
111
|
+
"events": "events_endpoint",
|
|
112
|
+
"hls": "stream_endpoint",
|
|
113
|
+
"webrtc": "webrtc_endpoint",
|
|
114
|
+
"webrtc_close": "webrtc_close_endpoint",
|
|
115
|
+
}
|
|
116
|
+
for field_name, manifest_name in endpoint_keys.items():
|
|
117
|
+
value = getattr(self.endpoints, field_name)
|
|
118
|
+
if value is not None:
|
|
119
|
+
camera[manifest_name] = value
|
|
120
|
+
if "hls" in self.transports:
|
|
121
|
+
camera["stream_type"] = "hls"
|
|
122
|
+
return {"kind": "camera", "value_kind": "camera", "camera": camera}
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
class CameraSourceDescriptor(CameraContractModel):
|
|
126
|
+
"""Private camera source passed only between an integration, Core, and a sidecar."""
|
|
127
|
+
|
|
128
|
+
message_type: Literal["camera.source"] = "camera.source"
|
|
129
|
+
audience: Literal["core-sidecar"] = "core-sidecar"
|
|
130
|
+
camera_id: str = Field(min_length=1, max_length=300, pattern=r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
|
|
131
|
+
source_url: str = Field(min_length=1, max_length=CAMERA_MAX_SOURCE_URL_BYTES)
|
|
132
|
+
source_protocol: CameraSourceProtocol
|
|
133
|
+
preferred_transport: CameraSourceTransport = "auto"
|
|
134
|
+
connect_timeout_seconds: int = Field(default=10, ge=1, le=60)
|
|
135
|
+
|
|
136
|
+
@model_validator(mode="after")
|
|
137
|
+
def validate_source(self) -> CameraSourceDescriptor:
|
|
138
|
+
if any(character in self.source_url for character in "\r\n\0"):
|
|
139
|
+
raise ValueError("camera source URL contains a forbidden control character")
|
|
140
|
+
parsed = urlsplit(self.source_url)
|
|
141
|
+
if parsed.scheme.lower() != self.source_protocol or not parsed.hostname:
|
|
142
|
+
raise ValueError("camera source URL and source_protocol must match and include a host")
|
|
143
|
+
return self
|
|
144
|
+
|
|
145
|
+
def safe_summary(self) -> dict[str, object]:
|
|
146
|
+
"""Return diagnostics that cannot disclose the URL or credentials."""
|
|
147
|
+
|
|
148
|
+
return {
|
|
149
|
+
"camera_id": self.camera_id,
|
|
150
|
+
"source_protocol": self.source_protocol,
|
|
151
|
+
"preferred_transport": self.preferred_transport,
|
|
152
|
+
"connect_timeout_seconds": self.connect_timeout_seconds,
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
class CameraWebRtcOffer(BaseModel):
|
|
157
|
+
"""Bounded SDP offer reusable inside browser and sidecar messages."""
|
|
158
|
+
|
|
159
|
+
model_config = ConfigDict(extra="forbid")
|
|
160
|
+
|
|
161
|
+
type: Literal["offer"] = "offer"
|
|
162
|
+
sdp: str = Field(min_length=1, max_length=CAMERA_MAX_SDP_BYTES)
|
|
163
|
+
include_audio: bool = False
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
class CameraSessionOffer(CameraWebRtcOffer, CameraContractModel):
|
|
167
|
+
message_type: Literal["camera.session.offer"] = "camera.session.offer"
|
|
168
|
+
audience: Literal["browser-core"] = "browser-core"
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
class CameraSidecarSessionOpen(CameraContractModel):
|
|
172
|
+
message_type: Literal["camera.sidecar.session.open"] = "camera.sidecar.session.open"
|
|
173
|
+
audience: Literal["core-sidecar"] = "core-sidecar"
|
|
174
|
+
source: CameraSourceDescriptor
|
|
175
|
+
offer: CameraWebRtcOffer
|
|
176
|
+
idle_timeout_seconds: int = Field(default=60, ge=10, le=900)
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
class CameraSessionOpened(CameraContractModel):
|
|
180
|
+
message_type: Literal["camera.session.opened"] = "camera.session.opened"
|
|
181
|
+
audience: CameraMediaAudience
|
|
182
|
+
session_id: str = Field(min_length=1, max_length=4096)
|
|
183
|
+
type: Literal["answer"] = "answer"
|
|
184
|
+
sdp: str = Field(min_length=1, max_length=CAMERA_MAX_SDP_BYTES)
|
|
185
|
+
expires_at: str | None = Field(default=None, max_length=128)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
class CameraSessionClose(CameraContractModel):
|
|
189
|
+
message_type: Literal["camera.session.close"] = "camera.session.close"
|
|
190
|
+
audience: CameraMediaAudience
|
|
191
|
+
session_id: str = Field(min_length=1, max_length=4096)
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
class CameraSnapshotRequest(CameraContractModel):
|
|
195
|
+
message_type: Literal["camera.snapshot.request"] = "camera.snapshot.request"
|
|
196
|
+
audience: CameraMediaAudience
|
|
197
|
+
maximum_bytes: int = Field(default=CAMERA_MAX_SNAPSHOT_BYTES, ge=1024, le=CAMERA_MAX_SNAPSHOT_BYTES)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
class CameraSidecarStatus(CameraContractModel):
|
|
201
|
+
message_type: Literal["camera.sidecar.status"] = "camera.sidecar.status"
|
|
202
|
+
audience: Literal["core-sidecar"] = "core-sidecar"
|
|
203
|
+
ready: bool
|
|
204
|
+
active_sessions: int = Field(ge=0)
|
|
205
|
+
session_capacity: int = Field(ge=1)
|
|
206
|
+
degraded_reason: str | None = Field(default=None, max_length=300)
|
|
207
|
+
supported_source_protocols: list[CameraSourceProtocol] = Field(default_factory=list)
|
|
208
|
+
supported_transports: list[CameraMediaTransport] = Field(default_factory=list)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
class CameraMediaError(CameraContractModel):
|
|
212
|
+
message_type: Literal["camera.error"] = "camera.error"
|
|
213
|
+
audience: CameraMediaAudience
|
|
214
|
+
code: CameraErrorCode
|
|
215
|
+
message: str = Field(min_length=1, max_length=300)
|
|
216
|
+
retryable: bool
|
|
217
|
+
retry_after_seconds: int | None = Field(default=None, ge=1, le=3600)
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
class CameraMediaProvider(Protocol):
|
|
221
|
+
"""Narrow integration-owned interface consumed by Core camera brokering."""
|
|
222
|
+
|
|
223
|
+
def resolve_source(
|
|
224
|
+
self,
|
|
225
|
+
config_id: str,
|
|
226
|
+
capability_id: str,
|
|
227
|
+
) -> Awaitable[CameraSourceDescriptor]: ...
|
|
228
|
+
|
|
229
|
+
def capture_snapshot(
|
|
230
|
+
self,
|
|
231
|
+
config_id: str,
|
|
232
|
+
capability_id: str,
|
|
233
|
+
request: CameraSnapshotRequest,
|
|
234
|
+
) -> Awaitable[tuple[str, bytes]]: ...
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
CameraSourceResolver = Callable[[str, str], Awaitable[CameraSourceDescriptor]]
|
{piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/METADATA
RENAMED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.1
|
|
2
2
|
Name: piphi-runtime-kit-python
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.9.3
|
|
4
4
|
Summary: PiPhi Network runtime integration helpers
|
|
5
5
|
Keywords: piphi,runtime,integration,iot
|
|
6
6
|
Author-Email: KelvinSan <support@piphi.network>
|
|
@@ -18,6 +18,7 @@ Project-URL: Repository, https://github.com/PiPhi-io/piphi-runtime-kit-python
|
|
|
18
18
|
Project-URL: Issues, https://github.com/PiPhi-io/piphi-runtime-kit-python/issues
|
|
19
19
|
Requires-Python: >=3.11
|
|
20
20
|
Requires-Dist: anyio<5.0,>=4.14.2
|
|
21
|
+
Requires-Dist: certifi>=2026.10.19
|
|
21
22
|
Requires-Dist: httpx<1.0,>=0.27
|
|
22
23
|
Requires-Dist: pydantic<2.14,>=2.8
|
|
23
24
|
Provides-Extra: fastapi
|
{piphi_runtime_kit_python-0.8.1.dist-info → piphi_runtime_kit_python-0.9.3.dist-info}/RECORD
RENAMED
|
@@ -1,11 +1,12 @@
|
|
|
1
|
-
piphi_runtime_kit_python-0.
|
|
2
|
-
piphi_runtime_kit_python-0.
|
|
3
|
-
piphi_runtime_kit_python-0.
|
|
4
|
-
piphi_runtime_kit_python-0.
|
|
5
|
-
piphi_runtime_kit_python/__init__.py,sha256=
|
|
1
|
+
piphi_runtime_kit_python-0.9.3.dist-info/METADATA,sha256=TD_WPbfXv7OHX-XKS1On4MLFbi_qcpugLjNvZYcCur0,37596
|
|
2
|
+
piphi_runtime_kit_python-0.9.3.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
|
|
3
|
+
piphi_runtime_kit_python-0.9.3.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
|
|
4
|
+
piphi_runtime_kit_python-0.9.3.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
|
|
5
|
+
piphi_runtime_kit_python/__init__.py,sha256=Fzsg1KKJFp54Jif7eG7nwCHoJNMIJbus8wFTMkyHQnk,9286
|
|
6
6
|
piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
|
|
7
7
|
piphi_runtime_kit_python/adapters/fastapi.py,sha256=4BP_Ewm2K4NmyUvhgOzCUH7-fN3JwQFRwSUVxrHptQI,3099
|
|
8
8
|
piphi_runtime_kit_python/automations.py,sha256=mDK62mo0hbsXGU48zEp-W7Q9MSzO9CsjnUEf75X6Yvw,20545
|
|
9
|
+
piphi_runtime_kit_python/camera.py,sha256=37LCMzRvP1NxCWXa4Z7WmWWRLsw92MM3CZLNscTdMe8,9093
|
|
9
10
|
piphi_runtime_kit_python/fastapi.py,sha256=xvHU19-CVDPKjmXW6nW72mpdbJEOLZzT8Twal7lCCkc,453
|
|
10
11
|
piphi_runtime_kit_python/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
11
12
|
piphi_runtime_kit_python/runtime/__init__.py,sha256=giSFLVRYGZU8icAWAgThevj59oTAXRoKTe5zo3fEeiA,4081
|
|
@@ -28,4 +29,4 @@ piphi_runtime_kit_python/runtime/state_service.py,sha256=bWxQD9JJRJsOA2k1S_TttFx
|
|
|
28
29
|
piphi_runtime_kit_python/runtime/tasks.py,sha256=E9WoE75NQiJp3buJYexysl3NuP8HJHJ3KfaGVKLdiw0,3238
|
|
29
30
|
piphi_runtime_kit_python/runtime/telemetry.py,sha256=b08Faq0CBrTqc5MCDjRUnX0KVT-MN8n4Le_FE-b2BVo,6719
|
|
30
31
|
piphi_runtime_kit_python/schemas.py,sha256=eXb_WEEGREGTRWkhShaof9N64vlrsHhVKAJECSia_to,10435
|
|
31
|
-
piphi_runtime_kit_python-0.
|
|
32
|
+
piphi_runtime_kit_python-0.9.3.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|