@trillboards/edge-core 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,93 @@
+# @trillboards/edge-core
+
+> **Core runtime for Trillboards Edge AI SDK.** Device identity, Socket.io connectivity, configuration, signal buffering, health monitoring, and auto-recovery for DOOH/CTV devices.
+
+## Install
+
+```bash
+npm install @trillboards/edge-core
+```
+
+## What This Does
+
+Provides the foundational infrastructure that all other `@trillboards/edge-*` packages depend on:
+
+- **Device Identity** — generates stable device fingerprints and session IDs from hardware characteristics
+- **Socket.io Manager** — real-time connection to Trillboards API with auto-reconnection and telemetry emission
+- **Signal Buffer** — SQLite-backed offline queue that caches audience metrics when connectivity drops
+- **Health Registry** — tracks 6 subsystems (socket, player, camera, microphone, ML pipeline, memory)
+- **Recovery Ladder** — 6-level auto-recovery from reconnect through service restart to rollback
+- **Capability Tiers** — classifies devices into TIER_1 through TIER_4 based on RAM and NPU availability
+- **Sensing Config** — deserializes 70+ sensing parameters for audience measurement tuning
+
+## Usage
+
+```typescript
+import {
+  DeviceIdentity,
+  SocketManager,
+  SignalBuffer,
+  SubsystemHealthRegistry,
+  SensingConfig,
+  computeTier,
+  classifyObservationSignal
+} from '@trillboards/edge-core';
+
+// Device identity
+const identity = new DeviceIdentity();
+const fingerprint = await identity.getFingerprint();
+
+// Capability detection
+const tier = computeTier({ ramMB: 4096, hasNPU: false });
+// → TIER_2
+
+// Socket.io connectivity
+const socket = new SocketManager({
+  url: 'https://api.trillboards.com',
+  deviceToken: 'your-token'
+});
+await socket.connect();
+
+// Offline-resilient signal buffering
+const buffer = new SignalBuffer({ dataDir: './data' });
+await buffer.push({ type: 'audience_metrics', payload: { faceCount: 3 } });
+
+// Signal classification
+const signal = classifyObservationSignal(rawPayload);
+// → { family: 'SCREEN_AUDIENCE', evidenceGrade: 'FACE_BACKED', ... }
+```
+
+## Subsystem Health Monitoring
+
+```typescript
+const health = new SubsystemHealthRegistry();
+
+health.update('camera', 'healthy');
+health.update('ml_pipeline', 'degraded');
+
+const report = health.getReport();
+// → { camera: 'healthy', ml_pipeline: 'degraded', ... }
+```
+
+## Capability Matrix
+
+```typescript
+import { getCapabilityMatrix } from '@trillboards/edge-core';
+
+const matrix = getCapabilityMatrix(tier);
+// → { models: ['blazeface'], inferenceHz: 2, resolution: 320, ... }
+```
+
+## Key Types
+
+- `PlatformAdapter` — interface for platform-specific adapters (Linux, Windows)
+- `CameraProvider` — interface for camera capture implementations
+- `AudioProvider` — interface for audio capture implementations
+- `AudienceMetricsPayload` — structured audience measurement data
+- `VASResult` — Viewability Attention Score output
+- `DetectedFace` — face detection result with bounding box, age, gender, emotion
+- `EdgeQualityReport` — inference quality telemetry
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trillboards/edge-core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core identity, heartbeat, Socket.io, config, and signal buffer for Trillboards Edge AI SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,6 +34,20 @@
     "url": "https://github.com/trillboards/packages.git",
     "directory": "trillboards-edge-sdk/packages/edge-core"
   },
+  "keywords": [
+    "edge-ai",
+    "dooh",
+    "audience-sensing",
+    "iot",
+    "digital-signage",
+    "heartbeat",
+    "socket-io",
+    "device-identity",
+    "ctv",
+    "signal-buffer",
+    "trillboards",
+    "ai-agent"
+  ],
   "engines": {
     "node": ">=18.0.0"
   }