@blueharford/scrypted-spatial-awareness 0.1.15 → 0.2.0

package/src/core/tracking-engine.ts

@@ -10,8 +10,11 @@ import sdk, {
   ObjectDetectionResult,
   ScryptedInterface,
   EventListenerRegister,
+  ObjectDetection,
+  Camera,
+  MediaObject,
 } from '@scrypted/sdk';
-import { CameraTopology, findCamera, findConnection, findConnectionsFrom } from '../models/topology';
+import { CameraTopology, findCamera, findConnection, findConnectionsFrom, Landmark } from '../models/topology';
 import {
   TrackedObject,
   ObjectSighting,
@@ -22,6 +25,11 @@ import {
 import { TrackingState } from '../state/tracking-state';
 import { AlertManager } from '../alerts/alert-manager';
 import { ObjectCorrelator } from './object-correlator';
+import {
+  SpatialReasoningEngine,
+  SpatialReasoningConfig,
+  SpatialReasoningResult,
+} from './spatial-reasoning';
 
 const { systemManager } = sdk;
 
@@ -34,6 +42,16 @@ export interface TrackingEngineConfig {
   lostTimeout: number;
   /** Enable visual embedding matching */
   useVisualMatching: boolean;
+  /** Loitering threshold - object must be visible this long before alerting (ms) */
+  loiteringThreshold: number;
+  /** Per-object alert cooldown (ms) */
+  objectAlertCooldown: number;
+  /** Use LLM for enhanced descriptions */
+  useLlmDescriptions: boolean;
+  /** Enable landmark learning from AI */
+  enableLandmarkLearning?: boolean;
+  /** Minimum confidence for landmark suggestions */
+  landmarkConfidenceThreshold?: number;
 }
 
 export class TrackingEngine {
@@ -43,9 +61,14 @@ export class TrackingEngine {
   private config: TrackingEngineConfig;
   private console: Console;
   private correlator: ObjectCorrelator;
+  private spatialReasoning: SpatialReasoningEngine;
   private listeners: Map<string, EventListenerRegister> = new Map();
   private pendingTimers: Map<GlobalTrackingId, NodeJS.Timeout> = new Map();
   private lostCheckInterval: NodeJS.Timeout | null = null;
+  /** Track last alert time per object to enforce cooldown */
+  private objectLastAlertTime: Map<GlobalTrackingId, number> = new Map();
+  /** Callback for topology changes (e.g., landmark suggestions) */
+  private onTopologyChange?: (topology: CameraTopology) => void;
 
   constructor(
     topology: CameraTopology,
@@ -60,6 +83,21 @@ export class TrackingEngine {
     this.config = config;
     this.console = console;
     this.correlator = new ObjectCorrelator(topology, config);
+
+    // Initialize spatial reasoning engine
+    const spatialConfig: SpatialReasoningConfig = {
+      enableLlm: config.useLlmDescriptions,
+      enableLandmarkLearning: config.enableLandmarkLearning ?? true,
+      landmarkConfidenceThreshold: config.landmarkConfidenceThreshold ?? 0.7,
+      contextCacheTtl: 60000, // 1 minute cache
+    };
+    this.spatialReasoning = new SpatialReasoningEngine(spatialConfig, console);
+    this.spatialReasoning.updateTopology(topology);
+  }
+
+  /** Set callback for topology changes */
+  setTopologyChangeCallback(callback: (topology: CameraTopology) => void): void {
+    this.onTopologyChange = callback;
   }
 
   /** Start listening to all cameras in topology */
@@ -176,6 +214,90 @@ export class TrackingEngine {
     }
   }
 
+  /** Check if object passes loitering threshold */
+  private passesLoiteringThreshold(tracked: TrackedObject): boolean {
+    const visibleDuration = tracked.lastSeen - tracked.firstSeen;
+    return visibleDuration >= this.config.loiteringThreshold;
+  }
+
+  /** Check if object is in alert cooldown */
+  private isInAlertCooldown(globalId: GlobalTrackingId): boolean {
+    const lastAlertTime = this.objectLastAlertTime.get(globalId);
+    if (!lastAlertTime) return false;
+    return (Date.now() - lastAlertTime) < this.config.objectAlertCooldown;
+  }
+
+  /** Record that we alerted for this object */
+  private recordAlertTime(globalId: GlobalTrackingId): void {
+    this.objectLastAlertTime.set(globalId, Date.now());
+  }
+
+  /** Get spatial reasoning result for movement (uses RAG + LLM) */
+  private async getSpatialDescription(
+    tracked: TrackedObject,
+    fromCameraId: string,
+    toCameraId: string,
+    transitTime: number,
+    currentCameraId: string
+  ): Promise<SpatialReasoningResult | null> {
+    try {
+      // Get snapshot from camera for LLM analysis (if LLM is enabled)
+      let mediaObject: MediaObject | undefined;
+      if (this.config.useLlmDescriptions) {
+        const camera = systemManager.getDeviceById<Camera>(currentCameraId);
+        if (camera?.interfaces?.includes(ScryptedInterface.Camera)) {
+          mediaObject = await camera.takePicture();
+        }
+      }
+
+      // Use spatial reasoning engine for rich context-aware description
+      const result = await this.spatialReasoning.generateMovementDescription(
+        tracked,
+        fromCameraId,
+        toCameraId,
+        transitTime,
+        mediaObject
+      );
+
+      // Optionally trigger landmark learning
+      if (this.config.enableLandmarkLearning && mediaObject) {
+        this.tryLearnLandmark(currentCameraId, mediaObject, tracked.className);
+      }
+
+      return result;
+    } catch (e) {
+      this.console.warn('Spatial reasoning failed:', e);
+      return null;
+    }
+  }
+
+  /** Try to learn new landmarks from detections (background task) */
+  private async tryLearnLandmark(
+    cameraId: string,
+    mediaObject: MediaObject,
+    objectClass: string
+  ): Promise<void> {
+    try {
+      // Position is approximate - could be improved with object position from detection
+      const position = { x: 50, y: 50 };
+      const suggestion = await this.spatialReasoning.suggestLandmark(
+        cameraId,
+        mediaObject,
+        objectClass,
+        position
+      );
+
+      if (suggestion) {
+        this.console.log(
+          `AI suggested landmark: ${suggestion.landmark.name} ` +
+          `(${suggestion.landmark.type}, confidence: ${suggestion.landmark.aiConfidence?.toFixed(2)})`
+        );
+      }
+    } catch (e) {
+      // Landmark learning is best-effort, don't log errors
+    }
+  }
+
   /** Process a single sighting */
   private async processSighting(
     sighting: ObjectSighting,
@@ -212,17 +334,35 @@ export class TrackingEngine {
           `(confidence: ${(correlation.confidence * 100).toFixed(0)}%)`
         );
 
-        // Generate movement alert for cross-camera transition
-        await this.alertManager.checkAndAlert('movement', tracked, {
-          fromCameraId: lastSighting.cameraId,
-          fromCameraName: lastSighting.cameraName,
-          toCameraId: sighting.cameraId,
-          toCameraName: sighting.cameraName,
-          transitTime: transitDuration,
-          objectClass: sighting.detection.className,
-          objectLabel: sighting.detection.label,
-          detectionId: sighting.detectionId,
-        });
+        // Check loitering threshold and per-object cooldown before alerting
+        if (this.passesLoiteringThreshold(tracked) && !this.isInAlertCooldown(tracked.globalId)) {
+          // Get spatial reasoning result with RAG context
+          const spatialResult = await this.getSpatialDescription(
+            tracked,
+            lastSighting.cameraId,
+            sighting.cameraId,
+            transitDuration,
+            sighting.cameraId
+          );
+
+          // Generate movement alert for cross-camera transition
+          await this.alertManager.checkAndAlert('movement', tracked, {
+            fromCameraId: lastSighting.cameraId,
+            fromCameraName: lastSighting.cameraName,
+            toCameraId: sighting.cameraId,
+            toCameraName: sighting.cameraName,
+            transitTime: transitDuration,
+            objectClass: sighting.detection.className,
+            objectLabel: spatialResult?.description || sighting.detection.label,
+            detectionId: sighting.detectionId,
+            // Include spatial context for enriched alerts
+            pathDescription: spatialResult?.pathDescription,
+            involvedLandmarks: spatialResult?.involvedLandmarks?.map(l => l.name),
+            usedLlm: spatialResult?.usedLlm,
+          });
+
+          this.recordAlertTime(tracked.globalId);
+        }
       }
 
       // Add sighting to tracked object
@@ -253,14 +393,28 @@ export class TrackingEngine {
       );
 
       // Generate entry alert if this is an entry point
-      if (isEntryPoint) {
+      // Entry alerts also respect loitering threshold and cooldown
+      if (isEntryPoint && this.passesLoiteringThreshold(tracked) && !this.isInAlertCooldown(globalId)) {
+        // Get spatial reasoning for entry event
+        const spatialResult = await this.getSpatialDescription(
+          tracked,
+          'outside', // Virtual "outside" location for entry
+          sighting.cameraId,
+          0,
+          sighting.cameraId
+        );
+
         await this.alertManager.checkAndAlert('property_entry', tracked, {
           cameraId: sighting.cameraId,
           cameraName: sighting.cameraName,
           objectClass: sighting.detection.className,
-          objectLabel: sighting.detection.label,
+          objectLabel: spatialResult?.description || sighting.detection.label,
           detectionId: sighting.detectionId,
+          involvedLandmarks: spatialResult?.involvedLandmarks?.map(l => l.name),
+          usedLlm: spatialResult?.usedLlm,
         });
+
+        this.recordAlertTime(globalId);
       }
     }
   }
@@ -362,6 +516,45 @@ export class TrackingEngine {
   updateTopology(topology: CameraTopology): void {
     this.topology = topology;
     this.correlator = new ObjectCorrelator(topology, this.config);
+    this.spatialReasoning.updateTopology(topology);
+  }
+
+  /** Get pending landmark suggestions */
+  getPendingLandmarkSuggestions(): import('../models/topology').LandmarkSuggestion[] {
+    return this.spatialReasoning.getPendingSuggestions();
+  }
+
+  /** Accept a landmark suggestion, adding it to topology */
+  acceptLandmarkSuggestion(suggestionId: string): Landmark | null {
+    const landmark = this.spatialReasoning.acceptSuggestion(suggestionId);
+    if (landmark && this.topology) {
+      // Add the accepted landmark to topology
+      if (!this.topology.landmarks) {
+        this.topology.landmarks = [];
+      }
+      this.topology.landmarks.push(landmark);
+
+      // Notify about topology change
+      if (this.onTopologyChange) {
+        this.onTopologyChange(this.topology);
+      }
+    }
+    return landmark;
+  }
+
+  /** Reject a landmark suggestion */
+  rejectLandmarkSuggestion(suggestionId: string): boolean {
+    return this.spatialReasoning.rejectSuggestion(suggestionId);
+  }
+
+  /** Get landmark templates for UI */
+  getLandmarkTemplates(): typeof import('../models/topology').LANDMARK_TEMPLATES {
+    return this.spatialReasoning.getLandmarkTemplates();
+  }
+
+  /** Get the spatial reasoning engine for direct access */
+  getSpatialReasoningEngine(): SpatialReasoningEngine {
+    return this.spatialReasoning;
   }
 
   /** Get current topology */

package/src/main.ts

@@ -15,7 +15,14 @@ import sdk, {
   Readme,
 } from '@scrypted/sdk';
 import { StorageSettings } from '@scrypted/sdk/storage-settings';
-import { CameraTopology, createEmptyTopology } from './models/topology';
+import {
+  CameraTopology,
+  createEmptyTopology,
+  Landmark,
+  LandmarkSuggestion,
+  LANDMARK_TEMPLATES,
+  inferRelationships,
+} from './models/topology';
 import { TrackedObject } from './models/tracked-object';
 import { Alert, AlertRule, createDefaultRules } from './models/alert';
 import { TrackingState } from './state/tracking-state';
@@ -85,6 +92,43 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
       description: 'Use visual embeddings for object correlation (requires compatible detectors)',
       group: 'Tracking',
     },
+    loiteringThreshold: {
+      title: 'Loitering Threshold (seconds)',
+      type: 'number',
+      defaultValue: 3,
+      description: 'Object must be visible for this duration before triggering movement alerts',
+      group: 'Tracking',
+    },
+    objectAlertCooldown: {
+      title: 'Per-Object Alert Cooldown (seconds)',
+      type: 'number',
+      defaultValue: 30,
+      description: 'Minimum time between alerts for the same tracked object',
+      group: 'Tracking',
+    },
+
+    // LLM Integration
+    useLlmDescriptions: {
+      title: 'Use LLM for Rich Descriptions',
+      type: 'boolean',
+      defaultValue: true,
+      description: 'Use LLM plugin (if installed) to generate descriptive alerts like "Man walking from garage towards front door"',
+      group: 'AI & Spatial Reasoning',
+    },
+    enableLandmarkLearning: {
+      title: 'Learn Landmarks from AI',
+      type: 'boolean',
+      defaultValue: true,
+      description: 'Allow AI to suggest new landmarks based on detected objects and camera context',
+      group: 'AI & Spatial Reasoning',
+    },
+    landmarkConfidenceThreshold: {
+      title: 'Landmark Suggestion Confidence',
+      type: 'number',
+      defaultValue: 0.7,
+      description: 'Minimum AI confidence (0-1) to suggest a landmark',
+      group: 'AI & Spatial Reasoning',
+    },
 
     // MQTT Settings
     enableMqtt: {
@@ -244,6 +288,11 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
       correlationThreshold: this.storageSettings.values.correlationThreshold as number || 0.6,
       lostTimeout: (this.storageSettings.values.lostTimeout as number || 300) * 1000,
       useVisualMatching: this.storageSettings.values.useVisualMatching as boolean ?? true,
+      loiteringThreshold: (this.storageSettings.values.loiteringThreshold as number || 3) * 1000,
+      objectAlertCooldown: (this.storageSettings.values.objectAlertCooldown as number || 30) * 1000,
+      useLlmDescriptions: this.storageSettings.values.useLlmDescriptions as boolean ?? true,
+      enableLandmarkLearning: this.storageSettings.values.enableLandmarkLearning as boolean ?? true,
+      landmarkConfidenceThreshold: this.storageSettings.values.landmarkConfidenceThreshold as number ?? 0.7,
     };
 
     this.trackingEngine = new TrackingEngine(
@@ -254,6 +303,12 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
       this.console
     );
 
+    // Set up callback to save topology changes (e.g., from accepted landmark suggestions)
+    this.trackingEngine.setTopologyChangeCallback((updatedTopology) => {
+      this.storage.setItem('topology', JSON.stringify(updatedTopology));
+      this.console.log('Topology auto-saved after change');
+    });
+
     await this.trackingEngine.startTracking();
     this.console.log('Tracking engine started');
   }
@@ -517,7 +572,12 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
       key === 'correlationWindow' ||
       key === 'correlationThreshold' ||
       key === 'lostTimeout' ||
-      key === 'useVisualMatching'
+      key === 'useVisualMatching' ||
+      key === 'loiteringThreshold' ||
+      key === 'objectAlertCooldown' ||
+      key === 'useLlmDescriptions' ||
+      key === 'enableLandmarkLearning' ||
+      key === 'landmarkConfidenceThreshold'
     ) {
       const topologyJson = this.storage.getItem('topology');
       if (topologyJson) {
@@ -580,6 +640,34 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
         return this.handleFloorPlanRequest(request, response);
       }
 
+      if (path.endsWith('/api/landmarks')) {
+        return this.handleLandmarksRequest(request, response);
+      }
+
+      if (path.match(/\/api\/landmarks\/[\w-]+$/)) {
+        const landmarkId = path.split('/').pop()!;
+        return this.handleLandmarkRequest(landmarkId, request, response);
+      }
+
+      if (path.endsWith('/api/landmark-suggestions')) {
+        return this.handleLandmarkSuggestionsRequest(request, response);
+      }
+
+      if (path.match(/\/api\/landmark-suggestions\/[\w-]+\/(accept|reject)$/)) {
+        const parts = path.split('/');
+        const action = parts.pop()!;
+        const suggestionId = parts.pop()!;
+        return this.handleSuggestionActionRequest(suggestionId, action, response);
+      }
+
+      if (path.endsWith('/api/landmark-templates')) {
+        return this.handleLandmarkTemplatesRequest(response);
+      }
+
+      if (path.endsWith('/api/infer-relationships')) {
+        return this.handleInferRelationshipsRequest(response);
+      }
+
       // UI Routes
       if (path.endsWith('/ui/editor') || path.endsWith('/ui/editor/')) {
         return this.serveEditorUI(response);
@@ -762,6 +850,210 @@ export class SpatialAwarenessPlugin extends ScryptedDeviceBase
     }
   }
 
+  private handleLandmarksRequest(request: HttpRequest, response: HttpResponse): void {
+    const topology = this.getTopology();
+    if (!topology) {
+      response.send(JSON.stringify({ landmarks: [] }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return;
+    }
+
+    if (request.method === 'GET') {
+      response.send(JSON.stringify({
+        landmarks: topology.landmarks || [],
+      }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+    } else if (request.method === 'POST') {
+      try {
+        const landmark = JSON.parse(request.body!) as Landmark;
+        if (!landmark.id) {
+          landmark.id = `landmark_${Date.now()}`;
+        }
+        if (!topology.landmarks) {
+          topology.landmarks = [];
+        }
+        topology.landmarks.push(landmark);
+        this.storage.setItem('topology', JSON.stringify(topology));
+        if (this.trackingEngine) {
+          this.trackingEngine.updateTopology(topology);
+        }
+        response.send(JSON.stringify({ success: true, landmark }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } catch (e) {
+        response.send(JSON.stringify({ error: 'Invalid landmark data' }), {
+          code: 400,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+  }
+
+  private handleLandmarkRequest(
+    landmarkId: string,
+    request: HttpRequest,
+    response: HttpResponse
+  ): void {
+    const topology = this.getTopology();
+    if (!topology) {
+      response.send(JSON.stringify({ error: 'No topology configured' }), {
+        code: 404,
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return;
+    }
+
+    const landmarkIndex = topology.landmarks?.findIndex(l => l.id === landmarkId) ?? -1;
+
+    if (request.method === 'GET') {
+      const landmark = topology.landmarks?.[landmarkIndex];
+      if (landmark) {
+        response.send(JSON.stringify(landmark), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } else {
+        response.send(JSON.stringify({ error: 'Landmark not found' }), {
+          code: 404,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    } else if (request.method === 'PUT') {
+      try {
+        const updates = JSON.parse(request.body!) as Partial<Landmark>;
+        if (landmarkIndex >= 0) {
+          topology.landmarks![landmarkIndex] = {
+            ...topology.landmarks![landmarkIndex],
+            ...updates,
+            id: landmarkId, // Preserve ID
+          };
+          this.storage.setItem('topology', JSON.stringify(topology));
+          if (this.trackingEngine) {
+            this.trackingEngine.updateTopology(topology);
+          }
+          response.send(JSON.stringify({ success: true, landmark: topology.landmarks![landmarkIndex] }), {
+            headers: { 'Content-Type': 'application/json' },
+          });
+        } else {
+          response.send(JSON.stringify({ error: 'Landmark not found' }), {
+            code: 404,
+            headers: { 'Content-Type': 'application/json' },
+          });
+        }
+      } catch (e) {
+        response.send(JSON.stringify({ error: 'Invalid landmark data' }), {
+          code: 400,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    } else if (request.method === 'DELETE') {
+      if (landmarkIndex >= 0) {
+        topology.landmarks!.splice(landmarkIndex, 1);
+        this.storage.setItem('topology', JSON.stringify(topology));
+        if (this.trackingEngine) {
+          this.trackingEngine.updateTopology(topology);
+        }
+        response.send(JSON.stringify({ success: true }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } else {
+        response.send(JSON.stringify({ error: 'Landmark not found' }), {
+          code: 404,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    }
+  }
+
+  private handleLandmarkSuggestionsRequest(request: HttpRequest, response: HttpResponse): void {
+    if (!this.trackingEngine) {
+      response.send(JSON.stringify({ suggestions: [] }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return;
+    }
+
+    const suggestions = this.trackingEngine.getPendingLandmarkSuggestions();
+    response.send(JSON.stringify({
+      suggestions,
+      count: suggestions.length,
+    }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  private handleSuggestionActionRequest(
+    suggestionId: string,
+    action: string,
+    response: HttpResponse
+  ): void {
+    if (!this.trackingEngine) {
+      response.send(JSON.stringify({ error: 'Tracking engine not running' }), {
+        code: 500,
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return;
+    }
+
+    if (action === 'accept') {
+      const landmark = this.trackingEngine.acceptLandmarkSuggestion(suggestionId);
+      if (landmark) {
+        response.send(JSON.stringify({ success: true, landmark }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } else {
+        response.send(JSON.stringify({ error: 'Suggestion not found' }), {
+          code: 404,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    } else if (action === 'reject') {
+      const success = this.trackingEngine.rejectLandmarkSuggestion(suggestionId);
+      if (success) {
+        response.send(JSON.stringify({ success: true }), {
+          headers: { 'Content-Type': 'application/json' },
+        });
+      } else {
+        response.send(JSON.stringify({ error: 'Suggestion not found' }), {
+          code: 404,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+    } else {
+      response.send(JSON.stringify({ error: 'Invalid action' }), {
+        code: 400,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+  }
+
+  private handleLandmarkTemplatesRequest(response: HttpResponse): void {
+    response.send(JSON.stringify({
+      templates: LANDMARK_TEMPLATES,
+    }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  private handleInferRelationshipsRequest(response: HttpResponse): void {
+    const topology = this.getTopology();
+    if (!topology) {
+      response.send(JSON.stringify({ relationships: [] }), {
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return;
+    }
+
+    const inferred = inferRelationships(topology);
+    response.send(JSON.stringify({
+      relationships: inferred,
+      count: inferred.length,
+    }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
   private serveEditorUI(response: HttpResponse): void {
     response.send(EDITOR_HTML, {
       headers: { 'Content-Type': 'text/html' },

package/src/models/alert.ts

@@ -78,6 +78,13 @@ export interface AlertDetails {
   objectLabel?: string;
   /** Thumbnail image URL or data */
   thumbnailUrl?: string;
+  // --- Spatial Context from RAG ---
+  /** Description of the path taken (from spatial reasoning) */
+  pathDescription?: string;
+  /** Names of landmarks involved in the movement */
+  involvedLandmarks?: string[];
+  /** Whether LLM was used for description */
+  usedLlm?: boolean;
 }
 
 /** A condition for alert rules */
@@ -211,9 +218,22 @@ export function generateAlertMessage(
     case 'property_exit':
       return `${objectDesc} exited property via ${details.cameraName || 'unknown camera'}`;
     case 'movement':
+      // If we have a rich description from LLM/RAG, use it
+      if (details.objectLabel && details.usedLlm) {
+        const transitSecs = details.transitTime ? Math.round(details.transitTime / 1000) : 0;
+        const transitStr = transitSecs > 0 ? ` (${transitSecs}s)` : '';
+        // Include path/landmark context if available
+        const pathContext = details.pathDescription ? ` via ${details.pathDescription}` : '';
+        return `${details.objectLabel}${pathContext}${transitStr}`;
+      }
+      // Fallback to basic message with landmark info
       const transitSecs = details.transitTime ? Math.round(details.transitTime / 1000) : 0;
       const transitStr = transitSecs > 0 ? ` (${transitSecs}s transit)` : '';
-      return `${objectDesc} moving from ${details.fromCameraName || 'unknown'} towards ${details.toCameraName || 'unknown'}${transitStr}`;
+      let movementDesc = `${objectDesc} moving from ${details.fromCameraName || 'unknown'} towards ${details.toCameraName || 'unknown'}`;
+      if (details.involvedLandmarks && details.involvedLandmarks.length > 0) {
+        movementDesc += ` near ${details.involvedLandmarks.join(', ')}`;
+      }
+      return `${movementDesc}${transitStr}`;
     case 'unusual_path':
       return `${objectDesc} took unusual path: ${details.actualPath || 'unknown'}`;
     case 'dwell_time':