twinops 1.5.1__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.
Files changed (74) hide show
  1. twinops/__init__.py +3 -0
  2. twinops/api/__init__.py +5 -0
  3. twinops/api/app.py +352 -0
  4. twinops/api/auth.py +109 -0
  5. twinops/api/live.py +490 -0
  6. twinops/api/persist.py +228 -0
  7. twinops/api/sso.py +102 -0
  8. twinops/api/state_io.py +34 -0
  9. twinops/api/store.py +94 -0
  10. twinops/api/streaming.py +113 -0
  11. twinops/api/tlsutil.py +25 -0
  12. twinops/api/webrtc_signal.py +82 -0
  13. twinops/cli.py +1615 -0
  14. twinops/composer/__init__.py +5 -0
  15. twinops/composer/compose.py +194 -0
  16. twinops/composer/usda.py +208 -0
  17. twinops/doctor.py +234 -0
  18. twinops/drift/__init__.py +11 -0
  19. twinops/drift/apply.py +213 -0
  20. twinops/drift/csv_report.py +48 -0
  21. twinops/drift/engine.py +382 -0
  22. twinops/drift/html_report.py +171 -0
  23. twinops/drift/loaders.py +223 -0
  24. twinops/drift/model.py +85 -0
  25. twinops/drift/reconcile.py +170 -0
  26. twinops/drift/sarif.py +109 -0
  27. twinops/drift/table.py +56 -0
  28. twinops/drift/verify.py +94 -0
  29. twinops/incident/__init__.py +13 -0
  30. twinops/incident/model.py +83 -0
  31. twinops/incident/record.py +75 -0
  32. twinops/incident/replay.py +216 -0
  33. twinops/plm/__init__.py +37 -0
  34. twinops/plm/base.py +29 -0
  35. twinops/plm/errors.py +34 -0
  36. twinops/plm/file.py +16 -0
  37. twinops/plm/http_mock.py +239 -0
  38. twinops/plm/mock.py +261 -0
  39. twinops/plm/rest.py +323 -0
  40. twinops/plm/stubs.py +57 -0
  41. twinops/plm/sync.py +229 -0
  42. twinops/scene/__init__.py +14 -0
  43. twinops/scene/highlight.py +108 -0
  44. twinops/scene/html_report.py +133 -0
  45. twinops/scene/validate.py +62 -0
  46. twinops/schema/__init__.py +13 -0
  47. twinops/schema/manifest.py +254 -0
  48. twinops/streaming_sidecar/__init__.py +5 -0
  49. twinops/streaming_sidecar/__main__.py +80 -0
  50. twinops/streaming_sidecar/app.py +192 -0
  51. twinops/streaming_sidecar/config.py +41 -0
  52. twinops/streaming_sidecar/encoder.py +108 -0
  53. twinops/streaming_sidecar/frames.py +254 -0
  54. twinops/streaming_sidecar/input_bridge.py +61 -0
  55. twinops/streaming_sidecar/metrics.py +120 -0
  56. twinops/streaming_sidecar/nvenc_bridge.py +216 -0
  57. twinops/streaming_sidecar/session.py +254 -0
  58. twinops/streaming_sidecar/stats.py +56 -0
  59. twinops/streaming_sidecar/webrtc_media.py +331 -0
  60. twinops/telemetry/__init__.py +28 -0
  61. twinops/telemetry/bus.py +298 -0
  62. twinops/telemetry/ingest.py +335 -0
  63. twinops/telemetry/payload.py +35 -0
  64. twinops/telemetry/reliability.py +328 -0
  65. twinops/telemetry/simulator.py +289 -0
  66. twinops/telemetry/topics.py +68 -0
  67. twinops/validate/__init__.py +5 -0
  68. twinops/validate/report.py +119 -0
  69. twinops-1.5.1.dist-info/METADATA +488 -0
  70. twinops-1.5.1.dist-info/RECORD +74 -0
  71. twinops-1.5.1.dist-info/WHEEL +5 -0
  72. twinops-1.5.1.dist-info/entry_points.txt +2 -0
  73. twinops-1.5.1.dist-info/licenses/LICENSE +190 -0
  74. twinops-1.5.1.dist-info/top_level.txt +1 -0
twinops/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """TwinOps — GitOps toolkit for industrial digital twins."""
2
+
3
+ __version__ = "1.5.1"
@@ -0,0 +1,5 @@
1
+ """TwinOps live control-plane API."""
2
+
3
+ from twinops.api.app import create_app
4
+
5
+ __all__ = ["create_app"]
twinops/api/app.py ADDED
@@ -0,0 +1,352 @@
1
+ """FastAPI application exposing live twin drift over HTTP + WebSocket."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import asyncio
6
+ from collections.abc import AsyncIterator
7
+ from contextlib import asynccontextmanager
8
+ from pathlib import Path
9
+ from typing import Any
10
+
11
+ from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
12
+ from fastapi.middleware.cors import CORSMiddleware
13
+ from fastapi.responses import FileResponse, HTMLResponse, PlainTextResponse
14
+ from fastapi.staticfiles import StaticFiles
15
+
16
+ from twinops import __version__
17
+ from twinops.api.auth import authorize_headers, build_http_auth_middleware, resolve_api_token
18
+ from twinops.api.live import LiveDriftRuntime
19
+ from twinops.api.sso import resolve_sso_secret
20
+ from twinops.api.streaming import build_streaming_session, webrtc_lab_enabled
21
+ from twinops.api.webrtc_signal import SIGNAL_HUB
22
+
23
+
24
+ class _WsClient:
25
+ def __init__(self, websocket: WebSocket, loop: asyncio.AbstractEventLoop) -> None:
26
+ self.websocket = websocket
27
+ self.loop = loop
28
+
29
+ def send_json(self, message: dict[str, Any]) -> None:
30
+ future = asyncio.run_coroutine_threadsafe(
31
+ self.websocket.send_json(message), self.loop
32
+ )
33
+ future.result(timeout=2)
34
+
35
+
36
+ def create_app(
37
+ *,
38
+ example_dir: str | Path,
39
+ work_dir: str | Path,
40
+ interval_seconds: float = 1.0,
41
+ mqtt_host: str | None = None,
42
+ mqtt_port: int = 1883,
43
+ mqtt_ingest: bool = True,
44
+ mqtt_tls: bool = False,
45
+ mqtt_ca_certs: str | None = None,
46
+ mqtt_tls_insecure: bool = False,
47
+ autostart: bool = True,
48
+ web_dist: str | Path | None = None,
49
+ api_token: str | None = None,
50
+ sso_secret: str | None = None,
51
+ webrtc: bool | None = None,
52
+ db_path: str | Path | None = None,
53
+ streaming_sidecar_url: str | None = None,
54
+ ) -> FastAPI:
55
+ from twinops.api.persist import create_store
56
+ from twinops.api.streaming import sidecar_url as resolve_sidecar_url
57
+
58
+ store = create_store(db_path=db_path)
59
+ sidecar = resolve_sidecar_url(streaming_sidecar_url)
60
+ runtime = LiveDriftRuntime(
61
+ example_dir=Path(example_dir),
62
+ work_dir=Path(work_dir),
63
+ store=store,
64
+ interval_seconds=interval_seconds,
65
+ mqtt_host=mqtt_host,
66
+ mqtt_port=mqtt_port,
67
+ mqtt_ingest=mqtt_ingest,
68
+ mqtt_tls=mqtt_tls,
69
+ mqtt_ca_certs=mqtt_ca_certs,
70
+ mqtt_tls_insecure=mqtt_tls_insecure,
71
+ )
72
+
73
+ @asynccontextmanager
74
+ async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
75
+ runtime.bootstrap()
76
+ if autostart:
77
+ runtime.start()
78
+ try:
79
+ yield
80
+ finally:
81
+ runtime.stop()
82
+
83
+ app = FastAPI(
84
+ title="TwinOps Live API",
85
+ version=__version__,
86
+ description="Live telemetry + drift control plane for TwinOps demos",
87
+ lifespan=lifespan,
88
+ )
89
+ app.add_middleware(
90
+ CORSMiddleware,
91
+ allow_origins=["*"],
92
+ allow_credentials=True,
93
+ allow_methods=["*"],
94
+ allow_headers=["*"],
95
+ )
96
+ token = resolve_api_token(api_token)
97
+ jwt_secret = resolve_sso_secret(sso_secret)
98
+ if token or jwt_secret:
99
+ app.middleware("http")(
100
+ build_http_auth_middleware(token, sso_secret=jwt_secret)
101
+ )
102
+ app.state.store = store
103
+ app.state.runtime = runtime
104
+ app.state.api_token_configured = bool(token)
105
+ app.state.sso_configured = bool(jwt_secret)
106
+ app.state.webrtc_lab = webrtc
107
+ app.state.streaming_sidecar_url = sidecar
108
+
109
+ @app.get("/api/health")
110
+ def health() -> dict[str, Any]:
111
+ return {
112
+ "status": "ok",
113
+ "version": __version__,
114
+ "service": "twinops-live",
115
+ "mqtt": runtime.mqtt_status(),
116
+ "auth": {"required": bool(token)},
117
+ }
118
+
119
+ @app.get("/api/ready")
120
+ def ready() -> dict[str, Any]:
121
+ """Readiness: twin metadata loaded and at least one drift evaluation present."""
122
+ twin_name = (runtime.store.twin_meta or {}).get("name")
123
+ has_drift_report = runtime.store.latest_drift is not None
124
+ ok = bool(twin_name) and has_drift_report
125
+ return {
126
+ "status": "ready" if ok else "not_ready",
127
+ "version": __version__,
128
+ "twin": twin_name,
129
+ "hasDriftReport": has_drift_report,
130
+ }
131
+
132
+ @app.get("/api/twin")
133
+ def twin() -> dict[str, Any]:
134
+ return store.snapshot()
135
+
136
+ @app.get("/api/drift/latest")
137
+ def drift_latest() -> dict[str, Any]:
138
+ return store.latest_drift or {}
139
+
140
+ @app.get("/api/drift/report", response_class=HTMLResponse)
141
+ def drift_report() -> HTMLResponse:
142
+ """Self-contained HTML drift dashboard from the latest evaluation."""
143
+ return HTMLResponse(runtime.drift_html())
144
+
145
+ @app.get("/api/drift/csv")
146
+ def drift_csv() -> PlainTextResponse:
147
+ """CSV export of the latest drift findings."""
148
+ return PlainTextResponse(
149
+ runtime.drift_csv(),
150
+ media_type="text/csv; charset=utf-8",
151
+ headers={"Content-Disposition": 'attachment; filename="drift-report.csv"'},
152
+ )
153
+
154
+ @app.get("/api/scene")
155
+ def scene() -> dict[str, Any]:
156
+ """OpenUSD prim highlight snapshot (Omniverse-ready, GPU not required)."""
157
+ return runtime.scene_snapshot()
158
+
159
+ @app.get("/api/scene/report", response_class=HTMLResponse)
160
+ def scene_report() -> HTMLResponse:
161
+ """Self-contained HTML scene highlight dashboard from the latest snapshot."""
162
+ return HTMLResponse(runtime.scene_html())
163
+
164
+ @app.get("/api/mqtt/topics")
165
+ def mqtt_topics() -> dict[str, Any]:
166
+ """Canonical demo MQTT topic catalog (+ live ingest status when enabled)."""
167
+ from twinops.telemetry.topics import topic_catalog
168
+
169
+ catalog = topic_catalog()
170
+ mqtt = runtime.mqtt_status()
171
+ catalog["status"] = {
172
+ "mqtt": mqtt,
173
+ }
174
+ return catalog
175
+
176
+ @app.get("/api/metrics")
177
+ def metrics() -> dict[str, Any]:
178
+ """Compact control-plane metrics for demos / scrape adapters."""
179
+ return runtime.metrics()
180
+
181
+ @app.get("/metrics")
182
+ def metrics_prometheus() -> Any:
183
+ from fastapi.responses import PlainTextResponse
184
+
185
+ return PlainTextResponse(
186
+ runtime.metrics_prometheus(),
187
+ media_type="text/plain; version=0.0.4; charset=utf-8",
188
+ )
189
+
190
+ @app.get("/api/timeline")
191
+ def timeline(limit: int = 50) -> dict[str, Any]:
192
+ return {"items": store.timeline(limit=limit)}
193
+
194
+ @app.get("/api/audit")
195
+ def audit(limit: int = 100) -> dict[str, Any]:
196
+ if hasattr(store, "audit_trail"):
197
+ return {"items": store.audit_trail(limit=limit)} # type: ignore[attr-defined]
198
+ return {"items": [], "persistent": False}
199
+
200
+ @app.post("/api/simulate/spike")
201
+ def simulate_spike() -> dict[str, Any]:
202
+ return runtime.trigger_spike()
203
+
204
+ @app.post("/api/reconcile")
205
+ def reconcile() -> dict[str, Any]:
206
+ return runtime.reconcile()
207
+
208
+ @app.get("/api/proposal/latest")
209
+ def proposal_latest() -> dict[str, Any]:
210
+ return store.latest_proposal or {}
211
+
212
+ @app.get("/api/proposal/latest/bundle")
213
+ def proposal_latest_bundle() -> dict[str, Any]:
214
+ """Downloadable proposal artifacts for local `twinopsctl apply --from-url`."""
215
+ proposal = store.latest_proposal or {}
216
+ if not proposal:
217
+ return {"proposal": {}, "overlay": "", "pullRequest": "", "available": False}
218
+ overlay_path = Path((proposal.get("spec") or {}).get("overlay") or "")
219
+ pr_path = overlay_path.parent / "PULL_REQUEST.md" if overlay_path.name else Path()
220
+ overlay_text = (
221
+ overlay_path.read_text(encoding="utf-8") if overlay_path.is_file() else ""
222
+ )
223
+ pr_text = pr_path.read_text(encoding="utf-8") if pr_path.is_file() else ""
224
+ return {
225
+ "available": bool(overlay_text),
226
+ "proposal": proposal,
227
+ "overlay": overlay_text,
228
+ "pullRequest": pr_text,
229
+ }
230
+
231
+ @app.get("/api/streaming/session")
232
+ def streaming_session(request: Request) -> dict[str, Any]:
233
+ """Kit streaming session descriptor (mock / lab WebRTC / kit sidecar)."""
234
+ base = str(request.base_url).rstrip("/")
235
+ return build_streaming_session(
236
+ base_url=base, webrtc=webrtc, sidecar=sidecar
237
+ )
238
+
239
+ @app.get("/api/streaming/webrtc")
240
+ def webrtc_info() -> dict[str, Any]:
241
+ """Lab WebRTC control-plane info (not NVIDIA Kit App Streaming)."""
242
+ return {
243
+ "apiVersion": "twinops.io/v1alpha1",
244
+ "kind": "WebRTCLabInfo",
245
+ "enabled": webrtc_lab_enabled(webrtc),
246
+ "signaling": "/api/streaming/webrtc/signal",
247
+ "notes": (
248
+ "Browser attaches a scene-driven MediaStream; signaling stores "
249
+ "offer/answer/ICE for a future Kit App Streaming sidecar."
250
+ ),
251
+ }
252
+
253
+ @app.post("/api/streaming/webrtc/signal")
254
+ def webrtc_signal(payload: dict[str, Any]) -> dict[str, Any]:
255
+ """REST signaling for lab WebRTC (offer/answer/candidate)."""
256
+ action = str(payload.get("action") or "").strip().lower()
257
+ session_id = str(payload.get("sessionId") or "").strip()
258
+ if action == "create":
259
+ session = SIGNAL_HUB.create()
260
+ return {"ok": True, "sessionId": session.session_id}
261
+ if not session_id:
262
+ return {"ok": False, "error": "sessionId required"}
263
+ if action == "offer":
264
+ offer = payload.get("sdp") or payload.get("offer")
265
+ if not isinstance(offer, dict):
266
+ return {"ok": False, "error": "offer sdp object required"}
267
+ SIGNAL_HUB.set_offer(session_id, offer)
268
+ # Lab echo answer: browser uses local MediaStream; Kit sidecar later.
269
+ answer = {
270
+ "type": "answer",
271
+ "sdp": offer.get("sdp", ""),
272
+ "labEcho": True,
273
+ "note": "Lab echo — replace with Kit App Streaming answer",
274
+ }
275
+ SIGNAL_HUB.set_answer(session_id, answer)
276
+ return {"ok": True, "sessionId": session_id, "answer": answer}
277
+ if action == "answer":
278
+ answer = payload.get("sdp") or payload.get("answer")
279
+ if not isinstance(answer, dict):
280
+ return {"ok": False, "error": "answer sdp object required"}
281
+ if SIGNAL_HUB.set_answer(session_id, answer) is None:
282
+ return {"ok": False, "error": "unknown sessionId"}
283
+ return {"ok": True, "sessionId": session_id}
284
+ if action == "candidate":
285
+ candidate = payload.get("candidate")
286
+ if not isinstance(candidate, dict):
287
+ return {"ok": False, "error": "candidate object required"}
288
+ local = bool(payload.get("local"))
289
+ if SIGNAL_HUB.add_candidate(session_id, candidate, local=local) is None:
290
+ return {"ok": False, "error": "unknown sessionId"}
291
+ return {"ok": True, "sessionId": session_id}
292
+ if action == "get":
293
+ snap = SIGNAL_HUB.snapshot(session_id)
294
+ if snap is None:
295
+ return {"ok": False, "error": "unknown sessionId"}
296
+ return {"ok": True, **snap}
297
+ return {"ok": False, "error": f"unknown action: {action}"}
298
+
299
+ @app.post("/api/drift/refresh")
300
+ def drift_refresh() -> dict[str, Any]:
301
+ return runtime.evaluate_drift(record_telemetry=True)
302
+
303
+ @app.websocket("/ws/events")
304
+ async def ws_events(websocket: WebSocket) -> None:
305
+ # Browsers cannot set WS Authorization headers; allow ?token= for demos.
306
+ query_token = websocket.query_params.get("token")
307
+ auth_needed = bool(token or jwt_secret)
308
+ authorized = authorize_headers(
309
+ authorization=websocket.headers.get("authorization"),
310
+ header_token=websocket.headers.get("x-twinops-token"),
311
+ expected_token=token,
312
+ sso_secret=jwt_secret,
313
+ ) or (bool(token) and query_token == token)
314
+ if auth_needed and not authorized:
315
+ await websocket.close(code=4401)
316
+ return
317
+ await websocket.accept()
318
+ client = _WsClient(websocket, asyncio.get_running_loop())
319
+ runtime.register_ws(client)
320
+ try:
321
+ await websocket.send_json(
322
+ {
323
+ "type": "snapshot",
324
+ "snapshot": store.snapshot(),
325
+ "scene": runtime.scene_snapshot(),
326
+ }
327
+ )
328
+ while True:
329
+ await websocket.receive_text()
330
+ except WebSocketDisconnect:
331
+ runtime.unregister_ws(client)
332
+ finally:
333
+ runtime.unregister_ws(client)
334
+
335
+ dist = Path(web_dist).resolve() if web_dist else None
336
+ if dist and dist.is_dir() and (dist / "index.html").is_file():
337
+ assets = dist / "assets"
338
+ if assets.is_dir():
339
+ app.mount("/assets", StaticFiles(directory=assets), name="assets")
340
+
341
+ @app.get("/")
342
+ def index() -> FileResponse:
343
+ return FileResponse(dist / "index.html")
344
+
345
+ @app.get("/{path:path}")
346
+ def spa_fallback(path: str) -> FileResponse:
347
+ candidate = dist / path
348
+ if candidate.is_file():
349
+ return FileResponse(candidate)
350
+ return FileResponse(dist / "index.html")
351
+
352
+ return app
twinops/api/auth.py ADDED
@@ -0,0 +1,109 @@
1
+ """Optional bearer-token + demo SSO JWT auth for the TwinOps live API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ from collections.abc import Awaitable, Callable
7
+
8
+ from starlette.requests import Request
9
+ from starlette.responses import JSONResponse, Response
10
+
11
+ from twinops.api.sso import resolve_sso_secret, validate_hs256_jwt
12
+
13
+ # Unauthenticated probes stay open so compose/k8s readiness keeps working.
14
+ PUBLIC_PATHS = frozenset(
15
+ {
16
+ "/api/health",
17
+ "/api/ready",
18
+ "/metrics",
19
+ "/docs",
20
+ "/openapi.json",
21
+ "/redoc",
22
+ }
23
+ )
24
+
25
+
26
+ def resolve_api_token(explicit: str | None = None) -> str | None:
27
+ """Return the configured API token, or None when auth is disabled."""
28
+ if explicit is not None:
29
+ value = explicit.strip()
30
+ return value or None
31
+ env = (os.environ.get("TWINOPS_API_TOKEN") or "").strip()
32
+ return env or None
33
+
34
+
35
+ def extract_bearer_token(authorization: str | None, header_token: str | None) -> str | None:
36
+ if header_token and header_token.strip():
37
+ return header_token.strip()
38
+ if not authorization:
39
+ return None
40
+ parts = authorization.split(None, 1)
41
+ if len(parts) == 2 and parts[0].lower() == "bearer":
42
+ token = parts[1].strip()
43
+ return token or None
44
+ return None
45
+
46
+
47
+ def is_public_path(path: str) -> bool:
48
+ if path in PUBLIC_PATHS:
49
+ return True
50
+ if path.startswith("/assets"):
51
+ return True
52
+ # SPA shell + non-API routes (API/WS still gated).
53
+ if not path.startswith("/api/") and not path.startswith("/ws/"):
54
+ return True
55
+ return False
56
+
57
+
58
+ def authorize_headers(
59
+ *,
60
+ authorization: str | None,
61
+ header_token: str | None,
62
+ expected_token: str | None,
63
+ sso_secret: str | None = None,
64
+ ) -> bool:
65
+ provided = extract_bearer_token(authorization, header_token)
66
+ if not provided:
67
+ return False
68
+ if expected_token and provided == expected_token:
69
+ return True
70
+ if sso_secret and validate_hs256_jwt(provided, secret=sso_secret) is not None:
71
+ return True
72
+ return False
73
+
74
+
75
+ def build_http_auth_middleware(
76
+ token: str | None = None,
77
+ *,
78
+ sso_secret: str | None = None,
79
+ ) -> Callable[[Request, Callable[[Request], Awaitable[Response]]], Awaitable[Response]]:
80
+ api_token = token
81
+ jwt_secret = sso_secret if sso_secret is not None else resolve_sso_secret()
82
+
83
+ async def middleware(
84
+ request: Request,
85
+ call_next: Callable[[Request], Awaitable[Response]],
86
+ ) -> Response:
87
+ path = request.url.path
88
+ if is_public_path(path):
89
+ return await call_next(request)
90
+ if not api_token and not jwt_secret:
91
+ return await call_next(request)
92
+ if authorize_headers(
93
+ authorization=request.headers.get("authorization"),
94
+ header_token=request.headers.get("x-twinops-token"),
95
+ expected_token=api_token,
96
+ sso_secret=jwt_secret,
97
+ ):
98
+ return await call_next(request)
99
+ return JSONResponse(
100
+ status_code=401,
101
+ content={
102
+ "detail": "unauthorized",
103
+ "hint": (
104
+ "Pass Authorization: Bearer <api-token|sso-jwt> or X-TwinOps-Token"
105
+ ),
106
+ },
107
+ )
108
+
109
+ return middleware