🚀 ScoutIQ

AI-Powered Recruitment Intelligence Platform

Note: 🚧 Project Status: MVP Prototype. Core architecture (FastAPI, Qdrant, Llama-3) is implemented. Currently optimizing deployment configurations for the live demo.

ScoutIQ is a production-ready SaaS platform that helps recruiters, founders, and job seekers generate high-quality, role-specific interview questions, analyze resumes against job descriptions, and rank candidates using AI-powered semantic search.

Built with Python, FastAPI, Streamlit, Firebase, Groq LLMs, and Qdrant vector database, ScoutIQ delivers fast, cost-efficient, and intelligent hiring solutions.

✨ Features

AI-Generated Interview Questions

Technical, behavioral, and red-flag/follow-up questions
Role-specific and resume-tailored
Batched generation for Pro users (40% cost reduction)
Smart caching for instant repeat queries

💎 Pro-Tier Features

Candidate Insights: Resume & JD summaries with strengths/weaknesses
Skill Gap Analysis: Identify missing skills and qualifications
Semantic Resume Search: Vector-powered candidate ranking with Qdrant
Job Seeker Mode: AI-powered resume improvement suggestions
Unlimited Generations: No monthly limits

📊 Analytics & Monitoring

Real-time request tracking and performance metrics
Feature usage analytics
Error monitoring dashboard
Token usage tracking for embeddings

🔐 Secure & Scalable

Firebase Authentication with custom claims (admin roles)
Tier-based access control (Free, Monthly, Yearly, Lifetime)
Rate limiting to prevent abuse
Retry logic with exponential backoff for 99.9% uptime

📄 PDF Export

Download generated questions as structured PDFs
Professional formatting for interview preparation

Tech Stack

Frontend

Streamlit - Multi-page application with dynamic navigation
Streamlit Feedback - User feedback collection

Backend

FastAPI - High-performance async API
Uvicorn + Gunicorn - Production ASGI server
Groq API - LLM inference (Llama 3.3 70B)
Voyage AI - Semantic embeddings (voyage-3.5-lite, 200M free tokens)
SlowAPI - Rate limiting middleware
Tenacity - Retry logic for resilience

Database & Storage

Firebase Firestore - User data, usage logs, analytics
Firebase Auth - Authentication with custom claims
Qdrant - Vector database for semantic resume search
Firestore Caching - 24-hour TTL for LLM responses

Payments

Gumroad - Payment processing with webhook integration

Deployment

Render - Backend hosting (FastAPI)
Streamlit Cloud - Frontend hosting
Docker-ready - Containerized deployment support

Project Structure

scoutiq/
├── app.py                      # Main Streamlit entry point with navigation
│
├── app/                        # Frontend core logic
│   ├── auth_functions.py       # Firebase authentication
│   ├── generator.py            # LLM API client
│   ├── ui.py                   # Main UI components
│   └── usage_tracker.py        # Daily usage tracking
│
├── app_pages/                  # Streamlit pages
│   ├── Admin_Dashboard.py      # Analytics dashboard (admin-only)
│   ├── Candidate_Database.py   # Semantic candidate search (Pro)
│   ├── Job_Seeker_Mode.py      # Resume improvement (Pro)
│   ├── Pricing.py              # Pricing & subscription info
│   └── Recruiter_Mode.py       # Main interview generator
│
├── llm_backend/                # FastAPI backend (modular architecture)
│   ├── main.py                 # API routes & app initialization
│   ├── models.py               # Pydantic models
│   ├── prompts.py              # LLM prompt templates
│   ├── security.py             # JWT authentication
│   ├── cache.py                # Response caching logic
│   ├── exceptions.py           # Custom error classes
│   ├── middleware.py           # Request tracking
│   ├── analytics.py            # Feature usage tracking
│   ├── dependencies.py         # FastAPI dependency injection
│   └── utils.py                # LLM retry logic & parsers
│
├── webhook.py                  # Gumroad payment webhook
├── requirements.txt            # Python dependencies
└── README.md                   # Documentation

🚀 Getting Started

Prerequisites

Python 3.9+
Firebase account (Firestore + Auth)
Groq API key (free tier available)
Voyage AI API key (200M free tokens/month)
Qdrant Cloud account (free tier available)

Installation

Clone the repository

git clone https://github.com/your-username/scoutiq.git
cd scoutiq

Install dependencies

pip install -r requirements.txt

Set up environment variables

Create a .env file in the root directory:

# Firebase
FIREBASE_WEB_API_KEY=your_firebase_web_api_key

# LLM & Embeddings
GROQ_API_KEY=your_groq_api_key
VOYAGEAI_API_KEY=your_voyage_api_key

# Vector Database
QDRANT_URL=your_qdrant_url
QDRANT_API_KEY=your_qdrant_api_key

# Email (for notifications)
GMAIL_USER=your_email@gmail.com
EMAIL_PASSWORD=your_app_password

# Payments
GUMROAD_SECRET=your_gumroad_webhook_secret

# Backend URL
BACKEND_URL=http://127.0.0.1:8000  # Local dev

Add Firebase service account key

Place firebase-service-key.json in the root directory.

Running Locally

Terminal 1 - Backend:

uvicorn llm_backend.main:app --reload --port 8000

Terminal 2 - Frontend:

streamlit run app.py

Visit http://localhost:8501 to access the app.

📖 API Documentation

Once the backend is running, visit:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Key Endpoints

Endpoint	Method	Description	Rate Limit
`/generate`	POST	Generate interview questions	10/min
`/parse-resume`	POST	Parse & store resume in vector DB	5/min
`/rank-candidates`	POST	Search & rank candidates	20/min
`/improve-resume`	POST	Job seeker resume feedback	10/min
`/admin/analytics/overview`	GET	Analytics dashboard	Admin only

💎 Pricing Tiers

Tier	Price	Features
Free	$0/month	3 generations/month, PDF export
Pro Monthly	$12/month	Unlimited generations, insights, candidate search
Pro Yearly	$120/year	All Pro features + 2 months free
Lifetime	$250 one-time	All current & future features forever

Subscribe on Gumroad

Usage Example

For Recruiters

Log in to your account
Paste a job description
Upload a candidate's resume (PDF/DOCX)
Click "Generate Questions"
Get tailored interview questions instantly
(Pro) View candidate insights & skill gaps
Export as PDF for your interview

For Job Seekers (Pro)

Navigate to Job Seeker Mode
Paste your resume and target job description
Get AI-powered improvement suggestions
Optimize your resume for ATS and recruiters

Architecture Highlights

Performance Optimizations

Batched LLM Calls: Pro users get all features in 1 API call (vs. 3)
Smart Caching: 24-hour Firestore cache for instant repeat queries
Retry Logic: 3 attempts with exponential backoff (99.9% uptime)
Rate Limiting: Prevents abuse and ensures fair usage

Cost Efficiency

40% cheaper Pro user generations (batched prompts)
43% faster response times (1 call vs. 3 sequential)
Free embeddings: Voyage AI 200M tokens/month
Free vector search: Qdrant free tier

Code Quality

Modular architecture: 6 focused modules vs. monolithic 850-line file
Type hints throughout: Better IDE support and fewer bugs
Comprehensive logging: Track every request and error
Custom exceptions: User-friendly error messages with suggestions

Roadmap

✅ Completed

🚧 In Progress

Multi-language support (ES, FR, DE)
Advanced resume scoring engine
Email notifications for Pro users
Bulk resume processing (CSV upload)

🔮 Future Features

Chrome extension for LinkedIn integration
Interview scheduling integration (Calendly)
Video interview question generator
Team collaboration features
API access for enterprises

🧪 Testing

Run Backend Tests

pytest llm_backend/tests/

🚀 Deployment

Backend (Render)

Start Command:

gunicorn -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:$PORT llm_backend.main:app

Environment Variables: Set all .env variables in Render dashboard.

Frontend (Streamlit Cloud)

Deploy directly from GitHub with app.py as the entry point.

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

Development Guidelines

Follow existing code structure (modular design)
Add type hints to all functions
Write docstrings for public APIs
Update README for new features

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Groq - Fast LLM inference
Voyage AI - High-quality semantic embeddings
Qdrant - Powerful vector database
Firebase - Authentication & database
Streamlit - Rapid frontend development

📧 Contact & Support

Email: interviewscoutiq@gmail.com
Issues: GitHub Issues
Feedback: Use the in-app feedback widget

Made with ❤️ by the ScoutIQ Team

⭐ Star us on GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 76 Commits
.devcontainer		.devcontainer
app		app
app_pages		app_pages
llm_backend		llm_backend
.gitignore		.gitignore
README.md		README.md
app.py		app.py
requirements.in		requirements.in
requirements.txt		requirements.txt
set_admin_claim.py		set_admin_claim.py
urls.txt		urls.txt
webhook.py		webhook.py

Folders and files

Latest commit

History

Repository files navigation

🚀 ScoutIQ

✨ Features

AI-Generated Interview Questions

💎 Pro-Tier Features

📊 Analytics & Monitoring

🔐 Secure & Scalable

📄 PDF Export

Tech Stack

Frontend

Backend

Database & Storage

Payments

Deployment

Project Structure

🚀 Getting Started

Prerequisites

Installation

Running Locally

📖 API Documentation

Key Endpoints

💎 Pricing Tiers

Usage Example

For Recruiters

For Job Seekers (Pro)

Architecture Highlights

Performance Optimizations

Cost Efficiency

Code Quality

Roadmap

✅ Completed

🚧 In Progress

🔮 Future Features

🧪 Testing

Run Backend Tests

🚀 Deployment

Backend (Render)

Frontend (Streamlit Cloud)

🤝 Contributing

Development Guidelines

📝 License

🙏 Acknowledgments

📧 Contact & Support

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages