😴 Sleep Debt Predictor

🔗 Live Demo

Check out the live application: https://sleep-debt-predictor.vercel.app/

Description

Sleep Debt Predictor is a web-based system designed to estimate how many additional hours of sleep a person may require to recover from accumulated sleep debt. The application uses a Linear Regression model trained on fatigue-related visual indicators, making the prediction process simple, explainable, and reliable for everyday use.

The system captures a short video through the browser and sends it to Google Gemini, which analyzes the user’s facial condition to extract three key features: eye redness level, dark-circle intensity, and yawn count. These indicators serve as measurable proxies for tiredness and are fed into the regression model to generate a clear, hour-based sleep requirement estimate.

The backend is built using FastAPI, providing a lightweight and efficient API layer, while the frontend uses HTML, CSS, and JavaScript for an intuitive user experience. The integration of AI-powered feature extraction with a classical machine learning model allows Sleep Debt Predictor to deliver practical and easy-to-understand insights that can help users monitor their rest patterns and make more informed decisions about their daily routine.

Local Development

Prerequisites

• Python 3.8+
• Webcam access
• Google API credentials

Setup

1. Clone the repository:

git clone https://github.com/AryanV-Coder/SleepDebtPredictor.git
cd SleepDebtPredictor

2. Create virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Download required model files:

python3 download_model.py

5. Set up environment variables: Create a .env file with:

GEMINI_API_KEY=your_gemini_api_key_here

6. Add Google Sheets credentials: Place your Google service account JSON file in the project root

7. Run the application:

uvicorn main:app --reload

8. Open index.html in your browser

Deployment on Render

Step 1: Prepare Repository

1. Ensure .gitignore excludes large files:

   • venv/ directory
   • *.dat model files
   • *.json credential files

2. Commit your code:

git add .
git commit -m "Add deployment configuration"
git push origin main

Step 2: Render Configuration

1. Service Type: Web Service
2. Build Command:

pip install -r requirements.txt && python3 download_model.py

3. Start Command:

uvicorn main:app --host 0.0.0.0 --port $PORT

Step 3: Environment Variables

Set these environment variables in Render:

• GEMINI_API_KEY: Your Google Gemini API key
• PYTHON_VERSION: 3.11.0 (or your preferred version)

Step 4: Add Secrets

• Upload your Google service account JSON as a secret file
• Update the file path in your code to match Render's file structure

File Structure

SleepDebtPredictor/
├── main.py                 # FastAPI backend
├── ai_analysis.py          # AI analysis logic
├── blink_counter.py        # Blink detection
├── google_sheets.py        # Google Sheets integration
├── download_model.py       # Model download script
├── start.sh               # Deployment startup script
├── requirements.txt       # Python dependencies
├── index.html            # Frontend HTML
├── script.js             # Frontend JavaScript
├── styles.css            # Frontend styling
├── .gitignore            # Git ignore rules
└── README.md             # This file

Model Files

The application uses the dlib 68-point facial landmark predictor:

• File: shape_predictor_68_face_landmarks.dat
• Size: ~95MB
• Downloaded automatically during deployment
• Source: http://dlib.net/files/shape_predictor_68_face_landmarks.dat.bz2

API Endpoints

• POST /analyze-sleep: Upload video for sleep debt analysis
• Returns JSON with sleep debt analysis results

Text-to-Speech (TTS) Details

• The web app uses the browser's Web Speech API for TTS feedback.
• TTS speed and pitch are set high for clarity and energy.
• You can test available voices in the browser console using testVoice('VoiceName').

Technologies Used

• Backend: FastAPI, Python
• Frontend: HTML, CSS, JavaScript (with Web Speech API for TTS)
• AI: Google Gemini API
• Computer Vision: OpenCV, dlib
• Storage: Google Sheets API
• Deployment: Render

Contributing

1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Create Pull Request