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