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.
@@ -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]]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.1
2
2
  Name: piphi-runtime-kit-python
3
- Version: 0.8.1
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
@@ -1,11 +1,12 @@
1
- piphi_runtime_kit_python-0.8.1.dist-info/METADATA,sha256=robDy1ZQqUYHM0FX-dtNdkGCpxCdpon3XxQh9ANLmVc,37561
2
- piphi_runtime_kit_python-0.8.1.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
3
- piphi_runtime_kit_python-0.8.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
4
- piphi_runtime_kit_python-0.8.1.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
5
- piphi_runtime_kit_python/__init__.py,sha256=woPKAm8V389AYMeAVjPBGvnmClyYkVYVT8o4WUuL6Pg,8292
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.8.1.dist-info/RECORD,,
32
+ piphi_runtime_kit_python-0.9.3.dist-info/RECORD,,