AI-powered recruitment system that uses semantic matching to find the best-fit candidates using FAISS vector database and Gemini AI.

• 🎯 Semantic Resume Matching - Goes beyond keyword matching using AI embeddings
• 🚀 Fast Vector Search - Lightning-fast similarity search with FAISS
• 🤖 AI-Powered Explanations - Gemini AI generates detailed match explanations
• 📄 Multi-Format Support - Process PDF, DOCX, and TXT resume files
• 💡 Clean Architecture - Modular microservices design with FastAPI + Streamlit
• 📊 Analytics Dashboard - Comprehensive insights and matching analytics
• ⚡ Real-Time Processing - Instant resume processing and matching
• 🔍 Advanced Filtering - Filter by skills, experience, location, and more

ai_recruitr/
├── backend/              # FastAPI microservices
│   ├── services/         # Core business logic
│   ├── api/             # REST API endpoints
│   └── models/          # Pydantic schemas
├── frontend/            # Streamlit UI
│   ├── pages/           # UI pages
│   └── components/      # Reusable components
├── config/              # Configuration
├── data/                # Data storage
└── utils/               # Utilities

• Python 3.9 or higher
• Git
• Google Gemini API key

git clone https://github.com/yourusername/ai-recruitr.git
cd ai-recruitr

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your API keys:

# Required: Google Gemini API Key
GEMINI_API_KEY=your_gemini_api_key_here

# Optional: Customize settings
API_HOST=localhost
API_PORT=8000
STREAMLIT_HOST=localhost
STREAMLIT_PORT=8501
LOG_LEVEL=INFO

1. Go to Google AI Studio
2. Create a new API key
3. Copy and paste it into your .env file

# Terminal 1: Start FastAPI backend
python -m backend.main

# Terminal 2: Start Streamlit frontend
streamlit run frontend/app.py

# Start backend
start_backend.bat

# Start frontend  
start_frontend.bat

# Start backend
./start_backend.sh

# Start frontend
./start_frontend.sh

• Streamlit UI: http://localhost:8501
• FastAPI Docs: http://localhost:8000/docs
• API Health: http://localhost:8000/health

1. Navigate to "📄 Upload Resumes" page
2. Drag and drop PDF/DOCX resume files
3. Click "🚀 Process All Files"
4. Wait for processing to complete

1. Go to "🔍 Job Matching" page
2. Fill in the job description form:
   • Job title
   • Detailed job description
   • Required skills
   • Experience level
3. Click "🔍 Find Matching Resumes"
4. Review the matching results

1. Visit "📊 Results & Analytics" page
2. View current matching results
3. Explore analytics and insights
4. Export data in JSON/CSV format

The system uses:

• Embedding Model: mixedbread-ai/mxbai-embed-large-v1
• LLM: gemini-pro
• Vector Dimension: 1024
• Max Sequence Length: 512 tokens

curl -X POST "http://localhost:8000/api/v1/upload-resume" \
     -H "Content-Type: multipart/form-data" \
     -F "file=@resume.pdf"

curl -X POST "http://localhost:8000/api/v1/match-job" \
     -H "Content-Type: application/json" \
     -d '{
       "job_description": {
         "title": "Senior Python Developer",
         "description": "We are looking for...",
         "skills_required": ["Python", "Django", "PostgreSQL"]
       },
       "top_k": 10,
       "similarity_threshold": 0.7
     }'

curl "http://localhost:8000/api/v1/resumes/count"

ai_recruitr/
├── 📁 backend/
│   ├── __init__.py
│   ├── main.py                 # FastAPI application
│   ├── 📁 api/
│   │   ├── __init__.py
│   │   └── routes.py           # API endpoints
│   ├── 📁 models/
│   │   ├── __init__.py
│   │   └── schemas.py          # Pydantic models
│   └── 📁 services/
│       ├── __init__.py
│       ├── embedding_service.py # mxbai embeddings
│       ├── faiss_service.py    # Vector database
│       ├── gemini_service.py   # Gemini LLM
│       └── resume_parser.py    # Resume processing
├── 📁 frontend/
│   ├── __init__.py
│   ├── app.py                  # Streamlit main app
│   ├── 📁 pages/
│   │   ├── __init__.py
│   │   ├── upload_resume.py    # Upload interface
│   │   ├── job_matching.py     # Matching interface
│   │   └── results.py          # Analytics dashboard
│   └── 📁 components/
│       ├── __init__.py
│       └── ui_components.py    # Reusable UI components
├── 📁 config/
│   ├── __init__.py
│   └── settings.py             # Configuration
├── 📁 data/
│   ├── 📁 resumes/             # Uploaded resumes
│   ├── 📁 faiss_index/         # FAISS index files
│   └── 📁 processed/           # Processed data
├── 📁 utils/
│   ├── __init__.py
│   └── helpers.py              # Utility functions
├── requirements.txt            # Python dependencies
├── .env.example               # Environment template
├── .gitignore                 # Git ignore rules
└── README.md                  # This file

Problem: Missing or invalid Gemini API key.

Solution:

# Check your .env file
cat .env

# Ensure GEMINI_API_KEY is set
echo $GEMINI_API_KEY

Problem: FAISS installation fails on some systems.

Solution:

# Try installing CPU version specifically
pip install faiss-cpu==1.7.4

# On macOS with Apple Silicon:
conda install -c pytorch faiss-cpu

Problem: PDF text extraction returns empty content.

Solution:

• Ensure PDFs are text-based, not scanned images
• Try converting PDFs to text format first
• Check file permissions

Problem: Frontend can't connect to FastAPI backend.

Solution:

# Check if backend is running
curl http://localhost:8000/health

# Verify ports in .env file
grep -E "(API_PORT|STREAMLIT_PORT)" .env

Problem: Embedding generation takes too long.

Solution:

• Check if you have GPU available
• Reduce batch size in processing
• Consider using smaller embedding model for testing

Enable debug logging:

# Set in .env
LOG_LEVEL=DEBUG

# Or run with debug
python -m backend.main --log-level DEBUG

• Change default ports
• Set up proper CORS origins
• Use environment-specific API keys
• Enable HTTPS
• Implement rate limiting
• Add authentication
• Secure file uploads
• Monitor API usage

• Implement data retention policies
• Add resume deletion functionality
• Encrypt sensitive data
• Audit API access
• Comply with GDPR/privacy laws

• Database: Replace FAISS with Pinecone/Weaviate for production
• Caching: Add Redis for embedding caching
• Queue: Use Celery for async processing
• Load Balancing: Deploy with multiple API instances

• Multi-language Support: Add language detection
• Resume Scoring: Implement comprehensive scoring
• Bias Detection: Add fairness checking
• Integration: Connect with LinkedIn, ATS systems
• Real-time Updates: WebSocket for live updates

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Format code
black .
isort .

# Lint code
flake8 .

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

• Hugging Face for mxbai embeddings
• Google for Gemini LLM
• Facebook Research for FAISS
• FastAPI team
• Streamlit team

• 📧 Email: support@ai-recruitr.com
• 💬 Discord: AI Recruitr Community
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Full Docs

Made with ❤️ for smarter recruiting