@trillboards/edge-sdk 0.2.1 → 0.2.3

package/deploy/helm/README.md

@@ -0,0 +1,508 @@
+# Kubernetes / Helm Deployment -- Trillboards Edge SDK
+
+This guide covers deploying the Trillboards Edge AI agent across a fleet of Kubernetes nodes using Helm or plain kubectl manifests. The agent runs as a DaemonSet, placing one instance on each labeled edge node.
+
+## Prerequisites
+
+- Kubernetes 1.24 or later
+- Helm 3.0 or later (for Helm-based deployment)
+- `kubectl` configured to communicate with your cluster
+- A Trillboards device token (obtain from the Trillboards dashboard under **Devices > Add Device**)
+- For GPU nodes: NVIDIA device plugin for Kubernetes (`k8s-device-plugin`) installed
+
+## Quick Start with Helm
+
+```bash
+# 1. Create the device token secret
+kubectl create secret generic trillboards-edge \
+  --from-literal=device-token=YOUR_DEVICE_TOKEN_HERE
+
+# 2. Add the Helm chart (local path -- chart is bundled in the SDK)
+helm install trillboards-edge \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge
+
+# 3. Label your edge nodes so the DaemonSet schedules onto them
+kubectl label node my-edge-node-01 trillboards.com/edge-device=true
+kubectl label node my-edge-node-02 trillboards.com/edge-device=true
+```
+
+The agent pod will start on every node carrying the `trillboards.com/edge-device=true` label.
+
+## Chart Information
+
+| Field | Value |
+|-------|-------|
+| Chart name | `trillboards-edge` |
+| Chart version | `0.2.2` |
+| App version | `0.2.2` |
+| Type | `application` |
+| Source | `https://github.com/trillboards/packages` |
+
+## Creating the Device Token Secret
+
+The chart expects a Kubernetes Secret containing the device token. This secret is referenced by all pods in the DaemonSet.
+
+**Single token for the entire fleet:**
+
+```bash
+kubectl create secret generic trillboards-edge \
+  --from-literal=device-token=YOUR_TOKEN
+```
+
+**From a file:**
+
+```bash
+echo -n 'YOUR_TOKEN' > device-token.txt
+kubectl create secret generic trillboards-edge \
+  --from-file=device-token=device-token.txt
+rm device-token.txt
+```
+
+To use a different secret name or key, set `deviceToken.existingSecret` and `deviceToken.secretKey` in your values override.
+
+## values.yaml Reference
+
+Below is the complete set of configurable values with defaults.
+
+### Image
+
+```yaml
+image:
+  repository: trillboards/edge-sdk   # Container image repository
+  tag: "latest"                       # Image tag: latest (CPU), cuda, openvino
+  pullPolicy: Always                  # Image pull policy
+```
+
+For GPU nodes, override the tag:
+
+```yaml
+# NVIDIA GPU nodes
+image:
+  tag: "cuda"
+
+# Intel OpenVINO nodes
+image:
+  tag: "openvino"
+```
+
+### API Configuration
+
+```yaml
+api:
+  baseUrl: "https://api.trillboards.com"   # Backend API URL
+```
+
+### Device Token
+
+```yaml
+deviceToken:
+  existingSecret: "trillboards-edge"   # Name of the Kubernetes Secret
+  secretKey: "device-token"            # Key within the Secret
+```
+
+### Sensing Configuration
+
+```yaml
+sensing:
+  camera:
+    enabled: true                      # Enable camera capture for face detection
+  audio:
+    enabled: true                      # Enable audio capture for ambient classification
+  kiosk:
+    enabled: false                     # Launch headless Chromium for screen player
+    url: "https://screen.trillboards.com"  # Kiosk URL when enabled
+  executionProvider: "cpu"             # ONNX execution provider: cpu, openvino, directml, cuda
+  logLevel: "info"                     # Log level: debug, info, warn, error
+```
+
+### Resource Limits
+
+```yaml
+resources:
+  requests:
+    cpu: "250m"                        # CPU request per pod
+    memory: "256Mi"                    # Memory request per pod
+  limits:
+    cpu: "1000m"                       # CPU limit per pod
+    memory: "1Gi"                      # Memory limit per pod
+```
+
+### GPU Resources
+
+```yaml
+gpu:
+  enabled: false   # Set to true and add nvidia.com/gpu limits for GPU pods
+```
+
+When `gpu.enabled` is true, add GPU resource limits to the `resources` block in your values override:
+
+```yaml
+gpu:
+  enabled: true
+resources:
+  limits:
+    cpu: "2000m"
+    memory: "2Gi"
+    nvidia.com/gpu: 1
+```
+
+### Status Server
+
+```yaml
+statusServer:
+  port: 9090       # HTTP port for /status, /health, /metrics endpoints
+```
+
+### Prometheus Integration
+
+```yaml
+prometheus:
+  enabled: true    # Add Prometheus scrape annotations to pods
+  port: 9090       # Metrics port (matches statusServer.port)
+  path: "/metrics" # Metrics endpoint path
+```
+
+When `prometheus.enabled` is `true`, pods receive these annotations automatically:
+
+```yaml
+prometheus.io/scrape: "true"
+prometheus.io/port: "9090"
+prometheus.io/path: "/metrics"
+```
+
+No additional ServiceMonitor or PodMonitor CRDs are required. Prometheus discovers the pods via annotation-based scraping.
+
+### Health Probes
+
+```yaml
+probes:
+  liveness:
+    initialDelaySeconds: 30    # Wait for agent startup before first liveness check
+    periodSeconds: 30          # Check interval
+  readiness:
+    initialDelaySeconds: 10    # Wait before first readiness check
+    periodSeconds: 10          # Check interval
+```
+
+Both probes hit the StatusServer's `/health` endpoint:
+- **200 OK** -- agent is healthy; pod marked Ready
+- **503 Service Unavailable** -- one or more subsystems degraded; pod marked NotReady
+
+### Storage
+
+```yaml
+models:
+  hostPath: "/opt/trillboards/models"   # Host path for ONNX model persistence
+
+data:
+  hostPath: "/opt/trillboards/data"     # Host path for signal buffer and device identity
+```
+
+Both volumes use `DirectoryOrCreate` type, so the directories are created automatically on first pod start.
+
+### Node Scheduling
+
+```yaml
+nodeSelector:
+  trillboards.com/edge-device: "true"   # Only schedule on labeled nodes
+
+tolerations:
+  - key: "edge"
+    operator: "Exists"
+    effect: "NoSchedule"                # Tolerate edge-tainted nodes
+
+affinity: {}                            # Additional affinity rules (optional)
+```
+
+### Update Strategy
+
+```yaml
+updateStrategy:
+  type: RollingUpdate
+  rollingUpdate:
+    maxUnavailable: 1    # Roll one pod at a time during upgrades
+```
+
+### Security Context
+
+```yaml
+securityContext:
+  privileged: false                # No privileged mode by default
+  readOnlyRootFilesystem: false    # Agent writes to /app/data at runtime
+```
+
+## GPU Node Deployment
+
+For nodes with NVIDIA GPUs, install the NVIDIA device plugin and deploy with the CUDA image.
+
+### 1. Install NVIDIA Device Plugin
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/NVIDIA/k8s-device-plugin/v0.14.3/nvidia-device-plugin.yml
+```
+
+### 2. Label and Taint GPU Nodes
+
+```bash
+kubectl label node gpu-node-01 trillboards.com/edge-device=true
+kubectl taint node gpu-node-01 nvidia.com/gpu=present:NoSchedule
+```
+
+### 3. Deploy with GPU Values
+
+Create a `values-gpu.yaml`:
+
+```yaml
+image:
+  tag: "cuda"
+
+sensing:
+  executionProvider: "cuda"
+
+gpu:
+  enabled: true
+
+resources:
+  requests:
+    cpu: "500m"
+    memory: "512Mi"
+  limits:
+    cpu: "2000m"
+    memory: "2Gi"
+    nvidia.com/gpu: 1
+
+tolerations:
+  - key: "edge"
+    operator: "Exists"
+    effect: "NoSchedule"
+  - key: "nvidia.com/gpu"
+    operator: "Exists"
+    effect: "NoSchedule"
+```
+
+```bash
+helm install trillboards-edge-gpu \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge \
+  -f values-gpu.yaml
+```
+
+## Heterogeneous Fleet (Mixed CPU + GPU Nodes)
+
+For fleets with both CPU-only and GPU nodes, deploy two Helm releases with different node selectors.
+
+```bash
+# CPU nodes
+kubectl label node cpu-node-01 trillboards.com/edge-device=true trillboards.com/gpu=false
+kubectl label node cpu-node-02 trillboards.com/edge-device=true trillboards.com/gpu=false
+
+# GPU nodes
+kubectl label node gpu-node-01 trillboards.com/edge-device=true trillboards.com/gpu=true
+kubectl label node gpu-node-02 trillboards.com/edge-device=true trillboards.com/gpu=true
+```
+
+```bash
+# Deploy CPU fleet
+helm install trillboards-cpu \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge \
+  --set image.tag=latest \
+  --set sensing.executionProvider=cpu \
+  --set nodeSelector."trillboards\.com/gpu"=false
+
+# Deploy GPU fleet
+helm install trillboards-gpu \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge \
+  -f values-gpu.yaml \
+  --set nodeSelector."trillboards\.com/gpu"=true
+```
+
+## Node Labeling for Edge Devices
+
+The DaemonSet schedules only onto nodes with the `trillboards.com/edge-device=true` label. This prevents the agent from running on control plane nodes or non-edge workers.
+
+**Label a node:**
+
+```bash
+kubectl label node <node-name> trillboards.com/edge-device=true
+```
+
+**Remove the label (stops the agent on that node):**
+
+```bash
+kubectl label node <node-name> trillboards.com/edge-device-
+```
+
+**List all edge nodes:**
+
+```bash
+kubectl get nodes -l trillboards.com/edge-device=true
+```
+
+## Scaling Strategy
+
+The chart deploys a **DaemonSet**, not a Deployment. This means:
+
+- **One agent per labeled node** -- adding a new edge node and labeling it automatically starts an agent pod
+- **Removing a label** stops the agent on that node
+- There is no replica count to configure; the fleet scales with node count
+- Rolling updates proceed one node at a time (`maxUnavailable: 1`)
+
+This is the correct scaling model for edge sensing: each physical device needs exactly one agent reading its camera and audio inputs.
+
+## Upgrading
+
+```bash
+# Update to a new image tag
+helm upgrade trillboards-edge \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge \
+  --set image.tag=0.3.0
+
+# Or apply a full values file
+helm upgrade trillboards-edge \
+  ./packages/edge-sdk/deploy/helm/trillboards-edge \
+  -f my-values.yaml
+```
+
+The DaemonSet uses `RollingUpdate` strategy with `maxUnavailable: 1`, so pods are restarted one at a time across the fleet.
+
+## Rollback
+
+```bash
+# View release history
+helm history trillboards-edge
+
+# Roll back to a specific revision
+helm rollback trillboards-edge 2
+
+# Roll back to the previous release
+helm rollback trillboards-edge
+```
+
+## Prometheus Integration
+
+When `prometheus.enabled` is `true` (the default), pod annotations are added for Prometheus auto-discovery. The agent exposes Prometheus-format metrics at `GET /metrics` on the status server port.
+
+Exported metrics:
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `trillboards_face_count` | gauge | Current detected face count |
+| `trillboards_attention_score` | gauge | Average attention score (0-1) |
+| `trillboards_vas_score` | gauge | Weighted VAS score (0-1) |
+| `trillboards_signal_buffer_count` | gauge | Buffered signals waiting to send |
+| `trillboards_signal_buffer_capacity` | gauge | Maximum signal buffer capacity |
+| `trillboards_uptime_seconds` | gauge | Agent uptime in seconds |
+| `trillboards_heap_used_mb` | gauge | V8 heap used in MB |
+| `trillboards_memory_rss_mb` | gauge | Process RSS memory in MB |
+| `trillboards_socket_connected` | gauge | Socket.io connection status (1/0) |
+| `trillboards_federated_enabled` | gauge | Federated learning enabled (1/0) |
+| `trillboards_tier` | gauge | Device capability tier (1-4) |
+| `trillboards_models_loaded_count` | gauge | Number of loaded ML models |
+
+**Prometheus scrape config** (if not using annotation-based auto-discovery):
+
+```yaml
+scrape_configs:
+  - job_name: 'trillboards-edge'
+    kubernetes_sd_configs:
+      - role: pod
+    relabel_configs:
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
+        action: keep
+        regex: true
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_port]
+        action: replace
+        target_label: __address__
+        regex: (.+)
+        replacement: ${1}:$1
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
+        action: replace
+        target_label: __metrics_path__
+        regex: (.+)
+```
+
+## Plain kubectl Deployment (Without Helm)
+
+If you prefer not to use Helm, a standalone Kubernetes manifest is provided at `deploy/k8s/daemonset.yaml`.
+
+### 1. Create the Secret
+
+```bash
+kubectl create secret generic trillboards-edge \
+  --from-literal=device-token=YOUR_TOKEN
+```
+
+### 2. Apply the Manifest
+
+```bash
+kubectl apply -f packages/edge-sdk/deploy/k8s/daemonset.yaml
+```
+
+This creates:
+- A `DaemonSet` named `trillboards-edge-agent` with all environment variables, volume mounts, probes, and Prometheus annotations pre-configured
+- A headless `Service` named `trillboards-edge-status` for per-pod addressability
+
+### 3. Label Nodes
+
+```bash
+kubectl label node <node-name> trillboards.com/edge-device=true
+```
+
+### 4. Customizing the kubectl Manifest
+
+Edit `daemonset.yaml` directly to change:
+- Image tag (line: `image: trillboards/edge-sdk:latest`)
+- Environment variable values
+- Resource requests and limits
+- Node selector labels
+- Tolerations
+
+## Service Topology
+
+The Helm chart creates a **headless Service** (`clusterIP: None`). This means:
+
+- Each pod is individually addressable via DNS: `<pod-name>.trillboards-edge.<namespace>.svc.cluster.local`
+- There is no load balancing across pods (each pod serves a unique physical device)
+- The service enables Prometheus service discovery and direct pod access for debugging
+
+To query a specific device's status from within the cluster:
+
+```bash
+kubectl exec -it debug-pod -- curl http://trillboards-edge-0.trillboards-edge.default.svc.cluster.local:9090/status
+```
+
+## Volume Architecture
+
+The DaemonSet mounts three volumes:
+
+| Volume | Type | Mount Path | Purpose |
+|--------|------|-----------|---------|
+| `models` | `hostPath` (DirectoryOrCreate) | `/app/models` | ONNX model files. Persisted across pod restarts. |
+| `data` | `hostPath` (DirectoryOrCreate) | `/app/data` | Signal buffer (SQLite), device identity, federated gradients. |
+| `video-devices` | `hostPath` (Directory) | `/dev` (read-only) | Camera device passthrough (`/dev/video*`). |
+
+Host paths default to `/opt/trillboards/models` and `/opt/trillboards/data`. Override in values if your nodes use a different layout.
+
+## Troubleshooting
+
+**Pods stuck in Pending:**
+- Verify nodes are labeled: `kubectl get nodes -l trillboards.com/edge-device=true`
+- Check for taint issues: `kubectl describe pod <pod-name>` and look for taint-related scheduling failures
+- Verify resource availability: `kubectl describe node <node-name>`
+
+**Pods in CrashLoopBackOff:**
+- Check logs: `kubectl logs <pod-name>`
+- The most common cause is a missing or invalid `DEVICE_TOKEN`. Verify the secret exists: `kubectl get secret trillboards-edge -o yaml`
+
+**Health check failures (pod NotReady):**
+- The liveness probe waits 30 seconds before starting. If the agent takes longer to initialize (first-time model download), increase `probes.liveness.initialDelaySeconds`.
+- Check the status endpoint directly: `kubectl exec <pod-name> -- curl -s http://localhost:9090/health`
+
+**Camera not detected inside pod:**
+- Verify `/dev/video*` exists on the host node
+- The `video-devices` volume mounts `/dev` read-only. If your device requires write access, set `securityContext.privileged: true` (not recommended for production).
+- Some USB cameras need `--privileged` or specific device cgroup rules
+
+**No metrics in Prometheus:**
+- Verify annotations: `kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}'`
+- Check that Prometheus is configured for annotation-based pod discovery
+- Test metrics endpoint: `kubectl exec <pod-name> -- curl -s http://localhost:9090/metrics`

package/deploy/helm/trillboards-edge/Chart.yaml

@@ -0,0 +1,19 @@
+apiVersion: v2
+name: trillboards-edge
+description: Trillboards Edge AI SDK — fleet-wide audience sensing for DOOH devices
+type: application
+version: 0.2.2
+appVersion: "0.2.2"
+keywords:
+  - dooh
+  - edge-ai
+  - audience-sensing
+  - digital-signage
+  - onnx
+  - ctv
+home: https://trillboards.com
+sources:
+  - https://github.com/trillboards/packages
+maintainers:
+  - name: Trillboards Engineering
+    email: engineering@trillboards.com

package/deploy/helm/trillboards-edge/templates/_helpers.tpl

@@ -0,0 +1,40 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "trillboards-edge.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+*/}}
+{{- define "trillboards-edge.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "trillboards-edge.labels" -}}
+helm.sh/chart: {{ include "trillboards-edge.name" . }}-{{ .Chart.Version }}
+{{ include "trillboards-edge.selectorLabels" . }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "trillboards-edge.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "trillboards-edge.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}

package/deploy/helm/trillboards-edge/templates/daemonset.yaml

@@ -0,0 +1,120 @@
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: {{ include "trillboards-edge.fullname" . }}
+  labels:
+    {{- include "trillboards-edge.labels" . | nindent 4 }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "trillboards-edge.selectorLabels" . | nindent 6 }}
+  updateStrategy:
+    {{- toYaml .Values.updateStrategy | nindent 4 }}
+  template:
+    metadata:
+      labels:
+        {{- include "trillboards-edge.selectorLabels" . | nindent 8 }}
+      annotations:
+        {{- if .Values.prometheus.enabled }}
+        prometheus.io/scrape: "true"
+        prometheus.io/port: {{ .Values.prometheus.port | quote }}
+        prometheus.io/path: {{ .Values.prometheus.path | quote }}
+        {{- end }}
+    spec:
+      terminationGracePeriodSeconds: 30
+      containers:
+        - name: edge-agent
+          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+          imagePullPolicy: {{ .Values.image.pullPolicy }}
+          ports:
+            - name: status
+              containerPort: {{ .Values.statusServer.port }}
+              protocol: TCP
+          env:
+            - name: DEVICE_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ .Values.deviceToken.existingSecret }}
+                  key: {{ .Values.deviceToken.secretKey }}
+            - name: SCREEN_ID
+              valueFrom:
+                fieldRef:
+                  fieldPath: spec.nodeName
+            - name: API_BASE_URL
+              value: {{ .Values.api.baseUrl | quote }}
+            - name: CAMERA_ENABLED
+              value: {{ .Values.sensing.camera.enabled | quote }}
+            - name: AUDIO_ENABLED
+              value: {{ .Values.sensing.audio.enabled | quote }}
+            - name: KIOSK_ENABLED
+              value: {{ .Values.sensing.kiosk.enabled | quote }}
+            {{- if .Values.sensing.kiosk.enabled }}
+            - name: KIOSK_URL
+              value: {{ .Values.sensing.kiosk.url | quote }}
+            {{- end }}
+            - name: EXECUTION_PROVIDER
+              value: {{ .Values.sensing.executionProvider | quote }}
+            - name: LOG_LEVEL
+              value: {{ .Values.sensing.logLevel | quote }}
+            - name: STATUS_PORT
+              value: {{ .Values.statusServer.port | quote }}
+            - name: NODE_NAME
+              valueFrom:
+                fieldRef:
+                  fieldPath: spec.nodeName
+          resources:
+            {{- toYaml .Values.resources | nindent 12 }}
+          {{- if .Values.gpu.enabled }}
+          # GPU resource requests are added to limits
+          {{- end }}
+          livenessProbe:
+            httpGet:
+              path: /health
+              port: status
+            initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
+            timeoutSeconds: 5
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /health
+              port: status
+            initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
+            periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
+            timeoutSeconds: 3
+            failureThreshold: 2
+          volumeMounts:
+            - name: models
+              mountPath: /app/models
+            - name: data
+              mountPath: /app/data
+            - name: video-devices
+              mountPath: /dev
+              readOnly: true
+          securityContext:
+            {{- toYaml .Values.securityContext | nindent 12 }}
+      volumes:
+        - name: models
+          hostPath:
+            path: {{ .Values.models.hostPath }}
+            type: DirectoryOrCreate
+        - name: data
+          hostPath:
+            path: {{ .Values.data.hostPath }}
+            type: DirectoryOrCreate
+        - name: video-devices
+          hostPath:
+            path: /dev
+            type: Directory
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}

package/deploy/helm/trillboards-edge/templates/service.yaml

@@ -0,0 +1,15 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "trillboards-edge.fullname" . }}
+  labels:
+    {{- include "trillboards-edge.labels" . | nindent 4 }}
+spec:
+  selector:
+    {{- include "trillboards-edge.selectorLabels" . | nindent 4 }}
+  ports:
+    - name: status
+      port: {{ .Values.statusServer.port }}
+      targetPort: status
+      protocol: TCP
+  clusterIP: None  # Headless — each pod addressable individually