Get Started

This guide walks you through building and running the Store-wide Loss Prevention reference application, including the swlp-service, the Behavioral Analysis Service (pose + VLM), and the supporting Scenescape stack.

Before you begin, review the System Requirements to ensure your environment meets the recommended hardware and software prerequisites.

1. Clone the Repository

Note: Make sure you are in the suspicious-activity-detection directory before running the commands in this guide.

If you have not already cloned the repository that contains this workload, do so now:

git clone https://github.com/intel-retail/storewide-loss-prevention.git
cd storewide-loss-prevention/suspicious-activity-detection

2. Initialize Submodules

Clone the required submodules (for example, performance-tools):

make update-submodules

3. Provide Required Assets

Before starting, ensure these files are in place:

File	Purpose
configs/.env.example	Reference for all environment variables; copied to docker/.env by init.sh
configs/zone_config.json	Zone name → type mapping (for example, aisle1 → HIGH_VALUE)
configs/rules.yaml	Declarative rules: triggers, conditions, actions, and deduplication scope
../scenescape/webserver/storewide-loss-prevention.zip	Scene map + zone definitions imported into Scenescape
../scenescape/sample_data/lp-camera1.mp4	Sample video used by the camera replay

Note: The video file name must match the camera name defined in the Scenescape scene (for example, lp-camera1.mp4 corresponds to camera lp-camera1).

4. Download Sample Video

Download the sample video defined in configs/zone_config.json (video_url) to ../scenescape/sample_data/:

make download-sample-data

The video is saved with the filename specified by the video_file key in zone_config.json (for example, lp-camera1.mp4). If the file already exists, the download is skipped.

5. Download AI Models

The first run requires downloading the OpenVINO™ and VLM models:

make download-models

This downloads:

• Qwen/Qwen2.5-VL-7B-Instruct (VLM weights for behavioral analysis).

• YOLO pose-estimation and person-detection models.

Models are written to the suspicious-activity-detection/models/ directory on the host (for example, /home/intel/sachin/storewide-loss-prevention/suspicious-activity-detection/models) and shared with each container via a Docker volume. Expected layout:

suspicious-activity-detection/models/
├── vlm_models/
│   └── Qwen/Qwen2.5-VL-7B-Instruct/
└── yolo_models/

6. Run the Sample

Run Everything (Scenescape + LP)

make up

By default this uses the GPU detect + CPU re-identification configuration (all-gpu-cpu.env) so the app can deploy on hosts without an NPU. To select a different device profile, pass the DEVICE parameter:

# GPU detect + CPU reid (default — works on hosts without NPU)
make up DEVICE=all-gpu-cpu.env

# NPU detect + NPU reid
make up DEVICE=all-npu.env

# NPU detect + CPU reid
make up DEVICE=all-npu-cpu.env

# NPU detect + GPU reid
make up DEVICE=all-npu-gpu.env

# All GPU (detect + reid on GPU)
make up DEVICE=all-gpu.env

# All CPU (software decode, detect + reid on CPU)
make up DEVICE=all-cpu.env

Device profiles are defined in configs/res/ and control the GStreamer decode chain, inference device, pre-process backend, and throughput options. A single unified pipeline template (configs/scenescape/pipeline-config.json) is rendered at init time using the selected profile.

Disable the Gradio UI

The Gradio dashboard (swlp-suscpicious-ui) is enabled by default. To run the stack without the UI container (for example, headless deployments or resource-constrained systems), pass ENABLE_UI=false:

# Start without the Gradio UI
make up ENABLE_UI=false

# Start with the UI (default)
make up ENABLE_UI=true

When the UI is disabled, the swlp-suscpicious-ui container is not built or started, and the Gradio dashboard at http://localhost:7860 is unavailable. All other services (Scenescape, swlp-service, Behavioral Analysis, OVMS, etc.) continue to run normally.

make up performs the following steps automatically:

1. Sources the selected device resource config (configs/res/<DEVICE>).

2. Generates TLS certificates, Scenescape secrets, and docker/.env.

3. Renders pipeline-config.json with device-specific settings.

4. Copies the sample video into the Docker volume.

5. Initializes Docker volumes with correct permissions.

6. Builds the LP, Behavioral Analysis, and Gradio UI container images.

7. Starts all Scenescape and LP containers.

8. Imports the scene map into Scenescape.

7. View Logs

make logs

8. Stop Services

# Stop everything
make down

9. Access the UI

Once running:

Service	URL	Credentials
Scenescape UI	https://localhost	admin / password printed by make up
Gradio Dashboard	http://localhost:7860	—
LP REST API	http://localhost:8082	—
LP logs	make logs	View all service logs

From the Gradio dashboard you can observe live alerts, evidence frames, and session state across all configured cameras.

10. Inspect Alerts and Sessions via REST

# Health check
curl http://localhost:8082/health

# Active sessions
curl http://localhost:8082/api/v1/lp/sessions

# Service status + zone counts
curl http://localhost:8082/api/v1/lp/status

11. Tune Detection Behavior

Detection thresholds, deduplication scope, and severity escalation are defined declaratively in configs/rules.yaml. Edit the file and restart the swlp-service to apply changes:

variables:
  repeat_visit_threshold: 4
  loiter_threshold_seconds: 5

rules:
  - id: loitering
    trigger:
      event_type: zone_loiter
      zone_type: HIGH_VALUE
    conditions:
      - field: dwell_seconds
        op: gt
        value: ${loiter_threshold_seconds:20}
    actions:
      - type: alert
        params:
          alert_type: LOITERING
          severity: WARNING
          fire_once_per: zone

See How It Works for a full description of triggers, conditions, and the rule engine.

12. Search Recorded Footage (VLM Recall Search)

Recall Search lets an investigator find historical footage with a plain-English query such as “person in a blue shirt between 2:00–3:00 PM at the entrance camera.” Appearance is matched by multimodal embeddings, time by a capture-time filter, and location by a per-camera tag — results are short, playable video clips.

Recall is opt-in — a plain make up does not start it. Use the MODE flag:

# Core stack only (SceneScape + Suspicious Activity) — recall hidden (default)
make up

# Core + the search/recall stack — recall available at http://localhost:7860/recall
make up MODE=full

# Only the standalone search/recall stack
make up MODE=search

See the VLM Recall Search guide for the architecture, all tunable variables, and how to run recall queries from the dashboard.

Clean Up

# Stop and remove all containers + volumes
make clean

# Also remove generated secrets and .env
make clean-all

Next Steps

• Learn more about How It Works for a high-level architectural overview.

• Search recorded footage with plain-English queries using VLM Recall Search.

• Experiment with different device profiles (all-npu-cpu.env, all-gpu-cpu.env, all-cpu.env) to compare NPU, GPU, and CPU behavior.

• Replace the sample video, zone map, or rules with your own assets by updating the configs/, models/, and videos volumes.