@blueharford/scrypted-spatial-awareness 0.6.23 → 0.6.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueharford/scrypted-spatial-awareness",
-  "version": "0.6.23",
+  "version": "0.6.25",
   "description": "Cross-camera object tracking for Scrypted NVR with spatial awareness",
   "author": "Joshua Seidel <blueharford>",
   "license": "Apache-2.0",

package/src/alerts/alert-manager.ts

@@ -155,6 +155,7 @@ export class AlertManager {
 
   /**
    * Get notification title based on alert type
+   * For movement alerts with LLM descriptions, use the smart description as title
    */
   private getNotificationTitle(alert: Alert): string {
     const prefix = alert.severity === 'critical' ? '🚨 ' :
@@ -167,11 +168,26 @@ export class AlertManager {
 
     switch (alert.type) {
       case 'property_entry':
+        // Legacy - use simple title
         return `${prefix}${objectType} Arrived`;
       case 'property_exit':
+        // Legacy - use simple title
         return `${prefix}${objectType} Left`;
       case 'movement':
-        // Include destination in title
+        // For smart activity alerts, use the LLM description as title if available
+        // This gives us rich context like "Person walking toward front door"
+        if (alert.details.objectLabel && alert.details.usedLlm) {
+          // Truncate to reasonable title length (first sentence or 60 chars)
+          let smartTitle = alert.details.objectLabel;
+          const firstPeriod = smartTitle.indexOf('.');
+          if (firstPeriod > 0 && firstPeriod < 60) {
+            smartTitle = smartTitle.substring(0, firstPeriod);
+          } else if (smartTitle.length > 60) {
+            smartTitle = smartTitle.substring(0, 57) + '...';
+          }
+          return `${prefix}${smartTitle}`;
+        }
+        // Fallback: include destination in title
         const dest = alert.details.toCameraName || 'area';
         return `${prefix}${objectType} → ${dest}`;
       case 'unusual_path':

package/src/core/tracking-engine.ts

@@ -324,6 +324,16 @@ export class TrackingEngine {
     this.lastLlmCallTime = Date.now();
   }
 
+  /** Check and record LLM call - returns false if rate limited */
+  private tryLlmCall(): boolean {
+    if (!this.isLlmCallAllowed()) {
+      this.console.log('[LLM] Rate limited, skipping LLM call');
+      return false;
+    }
+    this.recordLlmCall();
+    return true;
+  }
+
   /** Get spatial reasoning result for movement (uses RAG + LLM) with debouncing and fallback */
   private async getSpatialDescription(
     tracked: TrackedObject,
@@ -337,8 +347,8 @@ export class TrackingEngine {
 
     try {
       // Check rate limiting - if not allowed, return null to use basic description
-      if (!this.isLlmCallAllowed()) {
-        this.console.log('LLM rate-limited, using basic notification');
+      if (!this.tryLlmCall()) {
+        this.console.log('[Movement] LLM rate-limited, using basic notification');
         return null;
       }
 
@@ -351,9 +361,6 @@ export class TrackingEngine {
         }
       }
 
-      // Record that we're making an LLM call
-      this.recordLlmCall();
-
       // Use spatial reasoning engine for rich context-aware description
       // Apply timeout if fallback is enabled
       let result: SpatialReasoningResult;
@@ -567,44 +574,38 @@ export class TrackingEngine {
           spatialResult = await pendingDescription;
           this.console.log(`[Entry Alert] Prefetch result: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
         } catch (e) {
-          this.console.warn(`[Entry Alert] Prefetch failed, generating fallback: ${e}`);
+          this.console.warn(`[Entry Alert] Prefetch failed, using basic description: ${e}`);
+          // Don't make another LLM call - use basic description (no mediaObject = no LLM)
           spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId);
         }
         this.pendingDescriptions.delete(globalId);
       } else {
-        // Fallback: generate description now (slower path)
-        this.console.log(`[Entry Alert] No prefetch available, generating now`);
-        const mediaObject = this.snapshotCache.get(globalId);
-        spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId, mediaObject);
-        this.console.log(`[Entry Alert] Got description: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
+        // No prefetch available - only call LLM if rate limit allows
+        if (this.tryLlmCall()) {
+          this.console.log(`[Entry Alert] No prefetch, generating with LLM`);
+          const mediaObject = this.snapshotCache.get(globalId);
+          spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId, mediaObject);
+          this.console.log(`[Entry Alert] Got description: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
+        } else {
+          // Rate limited - use basic description (no LLM)
+          this.console.log(`[Entry Alert] Rate limited, using basic description`);
+          spatialResult = await this.spatialReasoning.generateEntryDescription(tracked, sighting.cameraId);
+        }
       }
 
-      if (isEntryPoint) {
-        // Entry point - generate property entry alert
-        await this.alertManager.checkAndAlert('property_entry', tracked, {
-          cameraId: sighting.cameraId,
-          cameraName: sighting.cameraName,
-          objectClass: sighting.detection.className,
-          objectLabel: spatialResult.description,
-          detectionId: sighting.detectionId,
-          involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
-          usedLlm: spatialResult.usedLlm,
-        });
-      } else {
-        // Non-entry point - still alert about activity using movement alert type
-        // This notifies about any activity around the property using topology context
-        await this.alertManager.checkAndAlert('movement', tracked, {
-          cameraId: sighting.cameraId,
-          cameraName: sighting.cameraName,
-          toCameraId: sighting.cameraId,
-          toCameraName: sighting.cameraName,
-          objectClass: sighting.detection.className,
-          objectLabel: spatialResult.description, // Use spatial reasoning description (topology-based)
-          detectionId: sighting.detectionId,
-          involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
-          usedLlm: spatialResult.usedLlm,
-        });
-      }
+      // Always use movement alert type for smart notifications with LLM descriptions
+      // The property_entry/property_exit types are legacy and disabled by default
+      await this.alertManager.checkAndAlert('movement', tracked, {
+        cameraId: sighting.cameraId,
+        cameraName: sighting.cameraName,
+        toCameraId: sighting.cameraId,
+        toCameraName: sighting.cameraName,
+        objectClass: sighting.detection.className,
+        objectLabel: spatialResult.description, // Smart LLM-generated description
+        detectionId: sighting.detectionId,
+        involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),
+        usedLlm: spatialResult.usedLlm,
+      });
 
       this.recordAlertTime(globalId);
     }, this.config.loiteringThreshold);
@@ -624,9 +625,9 @@ export class TrackingEngine {
           this.snapshotCache.set(globalId, mediaObject);
           this.console.log(`[Snapshot] Cached snapshot for ${globalId.slice(0, 8)} from ${cameraId}`);
 
-          // Start LLM analysis immediately in parallel (don't await)
+          // Start LLM analysis immediately in parallel (don't await) - but respect rate limits
           const tracked = this.state.getObject(globalId);
-          if (tracked && this.config.useLlmDescriptions) {
+          if (tracked && this.config.useLlmDescriptions && this.tryLlmCall()) {
             this.console.log(`[LLM Prefetch] Starting ${eventType} analysis for ${globalId.slice(0, 8)}`);
             const descriptionPromise = eventType === 'exit'
               ? this.spatialReasoning.generateExitDescription(tracked, cameraId, mediaObject)
@@ -640,6 +641,8 @@ export class TrackingEngine {
             }).catch(e => {
               this.console.warn(`[LLM Prefetch] Failed for ${globalId.slice(0, 8)}: ${e}`);
             });
+          } else if (tracked && this.config.useLlmDescriptions) {
+            this.console.log(`[LLM Prefetch] Skipped for ${globalId.slice(0, 8)} - rate limited`);
           }
         }
       }
@@ -719,21 +722,31 @@ export class TrackingEngine {
             spatialResult = await pendingDescription;
             this.console.log(`[Exit Alert] Prefetch result: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
           } catch (e) {
-            this.console.warn(`[Exit Alert] Prefetch failed, generating fallback: ${e}`);
+            this.console.warn(`[Exit Alert] Prefetch failed, using basic description: ${e}`);
+            // Don't make another LLM call - use basic description
             spatialResult = await this.spatialReasoning.generateExitDescription(current, sighting.cameraId);
           }
           this.pendingDescriptions.delete(tracked.globalId);
         } else {
-          // Fallback: generate description now (slower path)
-          this.console.log(`[Exit Alert] No prefetch available, generating now`);
-          const mediaObject = this.snapshotCache.get(tracked.globalId);
-          spatialResult = await this.spatialReasoning.generateExitDescription(current, sighting.cameraId, mediaObject);
-          this.console.log(`[Exit Alert] Got description: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
+          // No prefetch available - only call LLM if rate limit allows
+          if (this.tryLlmCall()) {
+            this.console.log(`[Exit Alert] No prefetch, generating with LLM`);
+            const mediaObject = this.snapshotCache.get(tracked.globalId);
+            spatialResult = await this.spatialReasoning.generateExitDescription(current, sighting.cameraId, mediaObject);
+            this.console.log(`[Exit Alert] Got description: "${spatialResult.description.substring(0, 60)}...", usedLlm=${spatialResult.usedLlm}`);
+          } else {
+            // Rate limited - use basic description (no LLM)
+            this.console.log(`[Exit Alert] Rate limited, using basic description`);
+            spatialResult = await this.spatialReasoning.generateExitDescription(current, sighting.cameraId);
+          }
         }
 
-        await this.alertManager.checkAndAlert('property_exit', current, {
+        // Use movement alert for exit too - smart notifications with LLM descriptions
+        await this.alertManager.checkAndAlert('movement', current, {
           cameraId: sighting.cameraId,
           cameraName: sighting.cameraName,
+          toCameraId: sighting.cameraId,
+          toCameraName: sighting.cameraName,
           objectClass: current.className,
           objectLabel: spatialResult.description,
           involvedLandmarks: spatialResult.involvedLandmarks?.map(l => l.name),

package/src/main.ts

@@ -130,8 +130,8 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
     llmDebounceInterval: {
       title: 'LLM Rate Limit (seconds)',
       type: 'number',
-      defaultValue: 10,
-      description: 'Minimum time between LLM calls to prevent API overload (0 = no limit)',
+      defaultValue: 30,
+      description: 'Minimum time between LLM calls to prevent API rate limiting. Increase if you get rate limit errors. (0 = no limit)',
       group: 'AI & Spatial Reasoning',
     },
     llmFallbackEnabled: {

package/src/models/alert.ts

@@ -128,8 +128,8 @@ export function createDefaultRules(): AlertRule[] {
   return [
     {
       id: 'property-entry',
-      name: 'Property Entry',
-      enabled: true,
+      name: 'Property Entry (Legacy)',
+      enabled: false, // Disabled - use movement alerts with LLM descriptions instead
       type: 'property_entry',
       conditions: [],
       severity: 'info',
@@ -138,8 +138,8 @@ export function createDefaultRules(): AlertRule[] {
     },
     {
       id: 'property-exit',
-      name: 'Property Exit',
-      enabled: true,
+      name: 'Property Exit (Legacy)',
+      enabled: false, // Disabled - use movement alerts with LLM descriptions instead
       type: 'property_exit',
       conditions: [],
       severity: 'info',
@@ -148,7 +148,7 @@ export function createDefaultRules(): AlertRule[] {
     },
     {
       id: 'movement',
-      name: 'Movement Between Cameras',
+      name: 'Smart Activity Alerts',
       enabled: true,
       type: 'movement',
       conditions: [],