@blueharford/scrypted-spatial-awareness 0.6.24 → 0.6.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueharford/scrypted-spatial-awareness",
-  "version": "0.6.24",
+  "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/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,16 +574,23 @@ 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);
+        }
       }
 
       // Always use movement alert type for smart notifications with LLM descriptions
@@ -611,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)
@@ -627,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`);
           }
         }
       }
@@ -706,16 +722,23 @@ 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);
+          }
         }
 
         // Use movement alert for exit too - smart notifications with LLM descriptions

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: {