Transform any camera into an intelligent AI-powered surveillance system
π Quick Start β’ π Documentation β’ π±Mobile App β’ π€ Contributing
GemmaGuardian converts any RTSP camera into an intelligent surveillance system using Google's Gemma models. It eliminates false positives through AI-powered analysis and provides professional-grade threat assessment with mobile integration.
- π Setup Guide - Complete installation and configuration
- ποΈ System Architecture - Technical deep dive with official architecture diagram
- π§ Network Setup - Firewall, ports, and network configuration
- π§ Dual AI Modes: Ollama server-based or direct transformer processing
- πΉ Universal Camera Support: Works with any RTSP-enabled camera
- π¨ Intelligent Alerts: Context-aware threat classification (Critical/High/Medium/Low)
- π± Mobile App: Complete Android companion with live streaming
- π Privacy-First: Local processing, no cloud dependency required
- β‘ Real-time Processing: <100ms person detection, 30-60s analysis
Complete GemmaGuardian system flow from RTSP input through AI processing to mobile notifications and storage.
graph TD
A[πΉ RTSP Stream Input] --> B[π Real-time Person Detection MobileNet SSD]
B --> C{π€ Person Detected?}
C -->|Yes Confidence > 0.5| D[πΉ Record 60s HD Security Clip]
C -->|No| B
D --> E[πΌοΈ Extract Frames Every 2 Seconds]
E --> F[π Resize to 1024x1024 Resolution]
F --> G[π¦ Group into Batches of 4 Frames]
G --> H[π§ AI Mode Selection]
H --> I[π Ollama Mode]
H --> J[π₯ Transformer Mode]
I --> I1[π‘ Send to Ollama Server]
I1 --> I2[π― Gemma 3 4b Vision Analysis]
I2 --> I3[π Gemma 3n e2b Consolidation]
I3 --> K[π‘οΈ Security Assessment]
J --> J1[πΎ Load Model to GPU/CPU]
J1 --> J2[π Direct PyTorch Inference]
J2 --> J3[π§ Memory-Optimized Processing]
J3 --> K
K --> L[π Threat Classification]
L --> M{β οΈ Threat Level?}
M -->|Critical/High| N[π¨ Immediate Alert]
M -->|Medium/Low| O[π Activity Log]
N --> P[π± Mobile Notification]
O --> P
P --> Q[πΎ Database Storage]
Q --> R[π Archive & Cleanup]
R --> B
subgraph "π§ AI Processing Comparison"
AI1[Ollama: Server-based Client-Server]
AI2[Transformer: Direct In-Process]
AI3[Both: Anti-hallucination Validation]
H --> AI1
H --> AI2
AI1 --> AI3
AI2 --> AI3
end
Professional Android companion with local network connectivity:
π± Home Dashboard |
πΉ Video Feed |
π¨ Alert Management |
π Technical Details |
Key Features:
- π± Real-time RTSP Streaming: Direct camera feed access within LAN
- π UDP Broadcast Alerts: Instant notifications via local network
- π AI Analysis Dashboard: Historical threat assessments and statistics
- βοΈ Remote Configuration: System settings via local API calls
The setup.py script is your gateway to GemmaGuardian - it handles EVERYTHING automatically:
python setup.pyπ― What this powerful script accomplishes:
- β Environment Setup: Creates virtual environment and installs all dependencies
- β Model Downloads: Downloads MobileNet SSD and Gemma AI models automatically
- β AI Mode Configuration: Guides you through Ollama or Transformer mode setup
- β Network Configuration: Sets up firewall rules for camera and mobile access
- β System Testing: Runs comprehensive tests to verify everything works
- β Camera Setup: Prompts for your RTSP URL and validates connection
- β Auto-Launch: Optionally starts the surveillance system immediately
π After running setup.py, your surveillance system will be fully operational!
π‘ Pro Tip: The setup script includes intelligent error handling, GPU detection, and guided configuration - making professional surveillance setup accessible to everyone.
GemmaGuardian requires specific network ports for mobile connectivity:
# Windows (Run as Administrator) - Automated Setup
cd src/SurveillanceAgent
.\setup_firewall.ps1# Linux/Ubuntu - Manual Setup
sudo ufw allow 37020/udp # UDP broadcast notifications
sudo ufw allow 8888/tcp # REST API server
sudo ufw reload
β οΈ Critical: Without proper firewall configuration, the mobile app won't receive notifications or connect to the surveillance system.
π Detailed Setup Guide: docs/SETUP_GUIDE.md
- Python 3.8+
- 8GB+ RAM (16GB recommended)
- RTSP Camera (IP camera, NVR, or mobile app)
- GPU (optional, for Transformer mode acceleration)
- οΏ½ Setup Guide - Complete installation and configuration
- ποΈ System Architecture - Technical deep dive and system design
- π§ Network Setup - Firewall, ports, and network configuration
- π‘ API Reference - Complete REST API documentation
- π± Mobile App Setup - Android companion app guide
- π² Android APK Download - Pre-built mobile app for instant installation
# Automated firewall configuration
cd src/SurveillanceAgent
.\setup_firewall.ps1cd src/SurveillanceAgent
python main.py --mode ollama # or --mode transformerProfessional Android companion app with enterprise-grade features:
- πΉ Live Streaming: Real-time RTSP feed viewing
- π Smart Notifications: Threat-level based alerts only
- π Analysis History: Browse and search security events
- βοΈ Remote Control: Configure system from anywhere
- π¨ Emergency Alerts: Critical threat escalation
Ready-to-install APK: Download the pre-built Android app directly from docs/gemmaguardian.apk
π± Mobile App Setup: src/MobileApp/README.md
# Run the provided PowerShell script as Administrator
cd src/SurveillanceAgent
.\setup_firewall.ps1π Complete Configuration Guide: docs/SETUP_GUIDE.md
# Quick system test
cd src/SurveillanceAgent
python test_setup.py
# AI model validation
python test_ai_flow.py
We welcome contributions! Areas of focus:
- π― New AI models and detection algorithms
- π± Mobile app enhancements
- π Additional notification channels
- π Analytics and reporting features
- π³ Container and deployment improvements
Development Setup: docs/SETUP_GUIDE.md#manual-installation-advanced-users
This project is licensed under the MIT License - see the LICENSE file for details.
- Google: Gemma model family
- Ollama: Model serving platform
π Links: GitHub β’ Issues β’ Discussions