Project Info
Mantis is an intelligent security system that transforms ordinary cameras into proactive theft prevention tools. By combining real-time computer vision and AI, Mantis detects shoplifting, weapons, and threatening behavior the moment they occur—alerting store owners before losses happen.
Inspiration
We started with one question: Why do most security systems only react after it’s too late? Retailers lose billions every year to theft, yet most cameras just record footage for later review. Humans can’t monitor every feed at once—and by the time incidents are noticed, the culprit is gone. So, we set out to make cameras that could think—systems that recognize suspicious behavior in real time and act before damage is done. What Mantis Does Mantis is an end-to-end intelligent monitoring platform that learns, detects, and alerts: Real-Time Threat Detection: Detects shoplifting, weapons, and aggressive actions within 2 seconds. Face Recognition System: Uses vector embeddings to identify and track repeat offenders across all footage—without storing private identity data. Live Dashboard: LiveKit-powered dashboard overlays detections on the video feed and streams alerts instantly. Smart Querying: Ask questions like “Who stole yesterday?” and get timestamped clips and summaries. Building Mantis taught us invaluable lessons about real-time video processing, multi-agent AI pipelines, and face recognition at scale. Balancing speed, accuracy, and privacy showed us what it takes to move from simple detection to true prevention. How We Built It Architecture Detection Engine: Processes frames at 0.5–1 FPS using specialized AI agents for theft, weapons, and face detection. Face Recognition: Generates and compares facial vector embeddings for cross-incident identification. Live Streaming: Combines LiveKit (for video delivery) and WebSockets (for detection metadata) for synchronized, low-latency updates. Analytics Layer: Uses ChromaDB for semantic vector search and natural-language querying. 💻 Tech Stack Backend: FastAPI + Python AI Models: Hugging Face + Ultralytics Video: OpenCV + LiveKit Database: ChromaDB (for face and clip embeddings) Challenges We Overcame Real-Time Performance at Scale: Achieved <2-second latency across multiple feeds using async job queues, frame sampling, and optimized inference. Accurate Threat Detection: Reduced false positives through a fusion approach combining multiple AI signals. Face Recognition & Privacy: Stored face embeddings separately from personal data, ensuring privacy without losing analytical power. Live Streaming Integration: Engineered a dual-channel pipeline—one for video, one for detection metadata—for seamless synchronization. Accomplishments We’re Proud Of Sub-2-second detection latency—true real-time prevention Face search that scans hours of footage in seconds Multi-agent fusion achieving high accuracy with minimal false alarms A live, intuitive dashboard built for instant response—no training required A system ready for production, not just a demo What We Learned Real-time AI demands millisecond-level optimization—batch processing principles don’t apply 1–2 FPS sampling is the sweet spot for retail: frequent enough to catch incidents, efficient enough for multiple feeds Vector embeddings are game-changing for semantic face tracking and event linking The best AI fails if the UX isn’t intuitive during stressful moments Privacy and ethics must be designed in, not patched later What’s Next Short-Term Mobile alerts with video clips POS integration to detect employee and self-checkout theft Predictive analytics for identifying high-risk locations and times Long-Term Cross-store networks to spot organized retail crime Behavioral analysis for professional shoplifters Edge-deployable systems for privacy-focused retailers Open API for integration with existing security infrastructure Our Vision We envision a world where retail theft becomes economically irrational—where prevention is instant, automated, and intelligent. Mantis isn’t just another security product. It’s the future of proactive protection.
Mantis — Real-time Shoplifting & Weapon Detection
Mantis is an AI-powered surveillance system that detects shoplifting, weapons, and suspicious behavior in real time, alerts store owners, and automatically extracts short, timestamped clips from long footage for easy review or police.
Features
- ✅ Real-time detection (<2s) of theft, weapons, and aggressive actions
- 🔔 Instant alerts to store owners via dashboard or SMS
- ✂️ Auto-generates short clips from long recordings (10+ hours)
- 🔎 Annotated video frames and forensic summaries
Demo Footage
Auto Video Analysis — What happened and how
Clip Generation from Long Footage — Ready to share with police
Analysis
View
Metric
- 3
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- JavaScriptIn code
- Next.jsIn code
- ReactIn code
- SupabaseIn code
- Tailwind CSSIn code
- TypeScriptIn code
- Vercel AI SDKIn code
- FastAPIClaimed
- Hugging FaceClaimed
- PythonClaimed
8 of 11 appear in the indexed code. 3 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
222 KB
Source files
38
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
oviozz/mantis
53 files · 550 KB · @ 0052748
Structure
Interface
22 files · 42%Screens, components and styles rendered to the user.
API & routing
2 files · 4%Request entry points: routes, handlers and controllers.
Application logic
13 files · 25%Domain rules, services and shared utilities.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- TypeScript96%
- CSS2%
- JavaScript2%
- Markdown0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 28- @ai-sdk/groq
- @ffmpeg/ffmpeg
- @ffmpeg/util
- @gradio/client
- @radix-ui/react-slot
- @supabase/supabase-js
- ai
- chromadb
- class-variance-authority
- clsx
- convex
- framer-motion
- lucide-react
- next
- react
- react-dom
- react-icons
- tailwind-merge
- +10 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
Auto video analysis: AI-generated timeline of what happened and how, with severity/descriptionVerified
Auto Video Analysis - What happened and how (demo), and detects shoplifting/weapons/aggressive actions
Claimed on readmehigh confidenceconvex/footageAnalyzer.ts:33— analyzeFootage action uploads video to the Reka Vision API, prompts it for a chronological security timeline, structures the result via Groq generateObject into typed timestamps (action/severity/description), and saves it to the footageAnalysis table.src/app/(dashboard)/footages/_components/footage-analytics.tsx:264— UI renders the stored timeline, subtitles, and severity badges over the video player, sourced from the saved analysis.
Auto-generated short clips from long footage, downloadable for sharing/policeVerified
Auto-generates short clips from long recordings (10+ hours); Clip Generation from Long Footage - Ready to share with police
Claimed on readmehigh confidencesrc/app/api/generate-clip/route.ts:69— API route downloads the source video, uses ffmpeg (via child_process exec) to extract and concatenate segments around selected timestamps, and returns the resulting mp4 file.src/app/(dashboard)/event-breakdown/_components/video-clip-generator.tsx:32— UI lets the user pick timestamps from the AI analysis and calls /api/generate-clip, then offers the resulting clip for preview/download.
Video footage upload and storageVerified
implied end-to-end monitoring platform; footage upload pipeline referenced in README/architecture
Claimed on readmehigh confidencesrc/components/upload-footage.tsx:1— Component exists for uploading footage.convex/footages.ts:5— create mutation inserts footage records and schedules analysis via ctx.scheduler.runAfter, wiring upload to the AI analysis pipeline.
Annotated video frames and forensic summariesCode-supported
Annotated video frames and forensic summaries
Claimed on readmemedium confidencesrc/app/(dashboard)/overview/_components/camera-model.tsx:253— Live camera view draws bounding-box annotations from WebSocket detection results onto an overlay canvas; combined with the Reka/Groq-generated timeline descriptions, this partially covers 'annotated frames and forensic summaries,' though the live annotation depends on the external, unverifiable detection backend and there is no per-frame screenshot annotation (getScreenshotForTimestamp in footageAnalyzer.ts always returns an empty string).convex/footageAnalyzer.ts:252— getScreenshotForTimestamp stub returns an empty string, meaning screenshots/frame annotations for the post-hoc analysis timeline are not actually populated despite the schema supporting them.
ChromaDB-based semantic vector search / analytics layerCode-supported
Analytics Layer: Uses ChromaDB for semantic vector search and natural-language querying
Claimed on Devpostmedium confidencesrc/app/api/add/route.ts:11— A Next.js API route instantiates a ChromaDB CloudClient and exposes a POST endpoint to add documents/metadata to a collection, but nothing in the codebase calls this endpoint or performs semantic search/querying against it (the search UI is fully mocked), so it is unwired scaffolding.
Instant alerts to store owners via dashboard or SMSCode-supported
Instant alerts to store owners via dashboard or SMS
Claimed on readmemedium confidenceconvex/alerts.ts:32— A reactive Convex query/mutation exists for alerts and a live dashboard panel subscribes to it in real time, satisfying the 'dashboard' half; however alerts are only ever created by a manual 'Create Random Alert' test button (test-alerts.tsx) with mock data, not by any real detection pipeline, and there is no SMS integration (no Twilio or similar) anywhere in the repo.src/app/(dashboard)/overview/_components/test-alerts.tsx:69— Only source of alert creation in the codebase is this manual random-scenario test button, not an automated detection-to-alert pipeline.
Live dashboard with LiveKit-powered video overlay and alert streamingCode-supported
Live Dashboard: LiveKit-powered dashboard overlays detections on the video feed and streams alerts instantly
Claimed on Devpostmedium confidencesrc/app/(dashboard)/overview/_components/live-alerts.tsx:57— A live alerts panel exists that reactively queries Convex (api.alerts.getAll) and animates new entries, but no LiveKit dependency, import, or usage exists anywhere in the codebase (package.json and full-repo search found none), so the 'LiveKit-powered' claim is unsupported; the overlay itself uses a raw WebSocket to a local backend, not LiveKit.
Real-time threat detection (<2s) for theft, weapons, aggressive behavior via camera feedCode-supported
Real-Time Threat Detection: Detects shoplifting, weapons, and threatening behavior the moment they occur, within 2 seconds
Claimed on Devpostmedium confidencesrc/app/(dashboard)/overview/_components/camera-model.tsx:69— Client captures webcam frames every 500ms and streams them over a WebSocket to ws://127.0.0.1:8000/ws, then renders returned bounding boxes for theft/weapon/face classes, but the detection backend/model server itself is not present in this repository (no Python/FastAPI/Ultralytics code found), so the actual detection logic is unverifiable here.
Face recognition with vector embeddings to identify repeat offendersClaimed only
Face Recognition System: Uses vector embeddings to identify and track repeat offenders across all footage without storing private identity data
Claimed on Devposthigh confidenceSmart natural-language querying of footage (e.g. 'Who stole yesterday?')Claimed only
Smart Querying: Ask questions like 'Who stole yesterday?' and get timestamped clips and summaries
Claimed on Devposthigh confidencesrc/app/(dashboard)/search/page.tsx:65— The search page's handleSearch function only sets a timeout and returns a hardcoded mockResults array; there is no call to any backend, LLM, or vector search API, so natural-language querying is not implemented.
Multi-agent AI detection pipeline (specialized agents for theft, weapons, faces) at 0.5-1 FPSBlocked
Detection Engine: Processes frames at 0.5-1 FPS using specialized AI agents for theft, weapons, and face detection
Claimed on Devpostmedium confidencesrc/app/(dashboard)/overview/_components/camera-model.tsx:200— Frontend sends a frame every 500ms (2 FPS) to an external local WebSocket server and expects theft/weapon/face detection results in the response shape, consistent with the claim, but the actual model/agent implementation lives outside this repository and cannot be inspected.
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.