🏠 HomeGuard - AI-Powered Residential Face Recognition System

Advanced face recognition and stranger detection for residential security

Features • Tech Stack • Installation • Deployment • API Documentation

📋 Overview

HomeGuard is an intelligent security system designed to protect residential properties by detecting and alerting homeowners of unknown individuals at their doorstep. Using cutting-edge AI models and real-time processing, HomeGuard provides instant notifications and detailed analysis of potential security threats.

Key Capabilities

✅ Real-time Face Detection - Detect faces in video streams with MTCNN
✅ Face Recognition - Identify known residents using FaceNet embeddings
✅ Stranger Detection - Automatically flag unrecognized individuals
✅ Email Alerts - Instant notifications with photo snapshots
✅ AI Analysis - LLM-powered threat assessment and recommendations
✅ Event Logging - SQLite database with complete audit trail
✅ Web Dashboard - Beautiful UI for monitoring and configuration

👥 Development Team

Member	Role
Ankit	Lead Developer
Sujal	AI/ML Engineer
Ashish	Full Stack Developer

🛠️ Tech Stack

Backend

FastAPI (v0.135.2) - High-performance web framework
Python (3.10+) - Core language
Uvicorn (v0.42.0) - ASGI server

ML/AI Models

PyTorch (v2.11.0) - Deep learning framework
MTCNN (facenet-pytorch) - Face detection
FaceNet (InceptionResnetV1) - Face embedding/recognition
OpenRouter API - LLM for threat analysis (meta-llama 3.2)

Computer Vision

OpenCV (v4.11.0.86) - Image processing
Pillow (v12.1.1) - Image operations
scikit-learn (v1.8.0) - ML utilities (cosine similarity)

Database & Storage

SQLite3 - Event logging and history
pickle - Model serialization

Frontend

HTML5/CSS3/JavaScript - Responsive web UI
Real-time MJPEG streaming - Live video feed

Email Integration

smtplib + MIME - Secure email alerts with attachments
Gmail/Custom SMTP support - Flexible email backends

Deployment

Render - Cloud hosting platform
Docker-compatible - Containerization ready

⚡ Features

🎥 Real-Time Video Processing

Multi-threaded camera capture (67 FPS)
GPU acceleration (CUDA/CPU fallback)
Optimized batch processing for multiple faces

🔍 Intelligence

Cosine Similarity Matching - Compare face embeddings with known residents
Configurable Threshold - Default 0.65 for recognition
Stranger Classification - Automatic detection of unknown individuals
LLM Integration - AI generates security recommendations

📧 Smart Alerts

Email Notifications - Beautiful HTML-formatted alerts
Cooldown System - Prevent alert spam (configurable)
Photo Attachments - Captured snapshot of detected face
SMTP Support - Gmail, Office 365, or custom SMTP servers

📊 Monitoring & Analytics

Event Database - Complete audit trail with timestamps
Detection History - Last 1000 detections in memory
Threat Levels - AI-assigned risk scores (0-10)
AI Chat Interface - Query security events naturally

🔐 Security

API Key Authentication - Protect sensitive endpoints
CORS Configuration - Restrict access by origin
Environment Variables - Secure credential management
No Exposed Credentials - .gitignore prevents leaks

📱 Web Dashboard

Live Video Feed - Real-time MJPEG stream
Detection Stats - Current and historical data
Alert Configuration - Update email settings on-the-fly
Test Email - Verify SMTP connectivity
Event Explorer - Browse and analyze past detections

🚀 Installation

Prerequisites

- Python 3.10 or higher
- pip (Python package manager)
- CUDA 11.8+ (optional, for GPU acceleration)
- 4GB RAM minimum (8GB+ recommended)

Local Setup

Clone the repository

git clone https://github.com/yourusername/homeguard.git
cd homeguard

Create virtual environment

python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # macOS/Linux

Install dependencies

pip install -r requirements.txt

Create .env file

# .env
API_KEY=your_secure_api_key_here
OPENROUTER_API_KEY=your_openrouter_key
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_FROM_ADDRESS=your_email@gmail.com
MAIL_FROM_NAME=Home Guard Security
SITE_URL=http://localhost:8000
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:8000

Prepare face embeddings
- Place your embedding_db.pkl file in the project root
- Create facenet_model.pth if needed (auto-downloaded by facenet-pytorch)
Run the application

python -m uvicorn api:app --host 0.0.0.0 --port 8000 --reload

Access the dashboard at: http://localhost:8000

📦 Deployment on Render

Step 1: Prepare Repository

# Ensure all required files are present
- Procfile ✅
- requirements.txt ✅
- build.sh ✅
- render.yaml ✅
- api.py ✅
- index.html ✅

Step 2: Upload to GitHub

git add .
git commit -m "Prepare for Render deployment"
git push origin main

Step 3: Connect to Render

Go to render.com
Click New + → Web Service
Connect your GitHub repository
Configure:
- Name: homeguard-api
- Environment: Python 3.10
- Build Command: bash build.sh
- Start Command: uvicorn api:app --host 0.0.0.0 --port $PORT

Step 4: Set Environment Variables

In Render Dashboard → Environment:

API_KEY=your_secure_api_key
OPENROUTER_API_KEY=your_key
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your_email@gmail.com
MAIL_PASSWORD=your_app_password
MAIL_FROM_ADDRESS=your_email@gmail.com
ALLOWED_ORIGINS=your_domain.render.com,yourdomain.com

Step 5: Deploy

Click Create Web Service
Monitor logs in real-time
Visit your deployed app at https://your-service-name.onrender.com

📡 API Documentation

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2026-03-29T10:30:00"
}

Start Recognition

POST /start
Authorization: X-API-Key: your_api_key

Stop Recognition

POST /stop
Authorization: X-API-Key: your_api_key

Process Frame

POST /process_frame
Content-Type: multipart/form-data

Upload: JPEG image file

Get Detection History

GET /alert/history?limit=100

Get Stranger History

GET /alert/strangers?limit=50

Chat with Events

POST /api/chat
Content-Type: application/json

{
  "query": "How many strangers detected today?"
}

Configure Alerts

POST /alert/config
Authorization: X-API-Key: your_api_key
Content-Type: application/json

{
  "enabled": true,
  "smtp_server": "smtp.gmail.com",
  "smtp_port": 587,
  "email_address": "your_email@gmail.com",
  "email_password": "app_password",
  "recipient_email": "alert@example.com",
  "alert_cooldown": 60
}

Test Email

POST /alert/test-email
Authorization: X-API-Key: your_api_key

📊 Database Schema

Events Table

CREATE TABLE events (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  timestamp TEXT,              -- ISO format timestamp
  name TEXT,                    -- "Unknown" or resident name
  confidence REAL,              -- 0.0 to 1.0 similarity score
  is_stranger BOOLEAN,          -- 1 if unknown, 0 if recognized
  description TEXT,             -- AI-generated analysis
  threat_level INTEGER          -- 0-10 risk score
)

🔧 Configuration

Environment Variables

Variable	Purpose	Required
`API_KEY`	Endpoint authentication	Optional but recommended
`OPENROUTER_API_KEY`	LLM threat analysis	For AI features
`MAIL_HOST`	SMTP server	For email alerts
`MAIL_PORT`	SMTP port	For email alerts
`MAIL_USERNAME`	Email account	For email alerts
`MAIL_PASSWORD`	Email password/app token	For email alerts
`MAIL_FROM_ADDRESS`	Sender email	For email alerts
`MAIL_FROM_NAME`	Display name in emails	For email alerts
`ALLOWED_ORIGINS`	CORS origins	Comma-separated
`SITE_URL`	Application URL	For OpenRouter headers

Recognition Threshold

Edit in api.py:

THRESHOLD = 0.65  # Adjust sensitivity (higher = stricter)

🎯 Use Cases

Residential Security

Monitor entry points 24/7
Get instant alerts when strangers arrive
Review footage and AI insights later

Property Management

Track authorized visitors
Manage access logs
Generate security reports

Smart Home Integration

Integrate with existing systems
Trigger actions on stranger detection
Multi-property monitoring

📈 Performance

Metric	Value
Face Detection Speed	~50ms per frame (GPU)
Recognition Accuracy	~95% (cosine similarity @ 0.65 threshold)
Video Streaming FPS	67 FPS (configurable)
Memory Usage	~2GB (models + cache)
Database Scalability	100,000+ events without issue

🐛 Troubleshooting

Issue: "embedding_db.pkl not found"

Solution: Ensure the file exists in the project root or generate embeddings from your known residents.

Issue: "No webcam detected"

Solution: Backend automatically falls back to processing frames from frontend only. Use the web dashboard to upload images.

Issue: "LLM rate limited"

Solution: Free tier has 8 requests/minute. System automatically throttles queries. Upgrade to paid OpenRouter tier for unlimited access.

Issue: "SMTP authentication failed"

Solution: Use Gmail app passwords, not regular password. Enable "Less secure app access" for other providers.

Issue: Deployment fails on Render

Solution:

Check Procfile syntax
Ensure build.sh is executable: git update-index --chmod=+x build.sh
Verify all dependencies are in requirements.txt
Check build logs in Render dashboard

📝 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

📞 Support

For issues, questions, or suggestions:

📧 Email: support@homeguard-security.com
🐛 GitHub Issues: Report a bug
💬 Discussions: Ask a question

🙏 Acknowledgments

FaceNet - Face recognition research by Google
MTCNN - Multi-task Cascaded Convolutional Networks for face detection
FastAPI - Modern Python web framework
OpenRouter - LLM API infrastructure
Render - Cloud hosting platform

Built with ❤️ by Ankit, Sujal & Ashish

HomeGuard - Protecting Homes, Powered by AI

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
.gitattributes		.gitattributes
.gitignore		.gitignore
Procfile		Procfile
README.md		README.md
api.py		api.py
build.sh		build.sh
index.html		index.html
realtime_recognition.py		realtime_recognition.py
render.yaml		render.yaml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation