| --- |
| title: TalentPulse AI Candidate Matching |
| emoji: ⚡ |
| colorFrom: purple |
| colorTo: indigo |
| sdk: docker |
| pinned: false |
| app_port: 7860 |
| --- |
| |
|
|
| # TalentPulse: AI-Powered Candidate Matching System |
|
|
|
|
| ## Overview |
|
|
| TalentPulse is a production-grade, full-stack AI system for matching job descriptions against large candidate pools. It replaces manual resume screening with semantic retrieval, neural reranking, structured gap analysis, and LLM-generated explanations. |
|
|
| The platform is built for recruiters and hiring teams who need fast, explainable, and configurable candidate matching. It supports session-based candidate batches, dynamic scoring weights, trajectory analysis, and reusable matching workflows for A/B testing and precision hiring. |
|
|
| ## Key Features |
|
|
| ### Session-based Candidate Management |
| Group candidates into named sessions for isolated workflows and repeatable matching experiments. |
|
|
| ### Two-stage AI Matching Pipeline |
| - **Stage 1: Retrieval** — Fast vector search in Qdrant with structured scoring for skills, experience, and other signals. |
| - **Stage 2: Reranking** — Cross-encoder reranking of the shortlist, fused with Reciprocal Rank Fusion. |
|
|
| ### Live Weight Sliders |
| Adjust matching priorities in real time and rerank results in memory without running new model inference. |
|
|
| ### Structured Gap Analysis |
| Detect missing skills, experience gaps, and mismatches to generate grounded candidate explanations. |
|
|
| ### LLM-generated Explanations |
| Use Groq-powered LLM responses based on the precomputed gap analysis. |
|
|
| ### Trajectory Scoring |
| Estimate career growth velocity from work history and reward strong advancement patterns. |
|
|
| ### JD Quality Feedback |
| Evaluate job descriptions for clarity, breadth, and missing signals. |
|
|
| ## Tech Stack |
|
|
| | Layer | Technology | |
| |------|------------| |
| | Frontend | Next.js 16, React, Tailwind CSS v4 | |
| | Backend | FastAPI, Uvicorn | |
| | Database | Neon Postgres, Asyncpg, SQLAlchemy, Alembic | |
| | Vector Search | Qdrant Cloud | |
| | Async Jobs | Celery | |
| | Cache | Redis Cloud | |
| | Embeddings | BAAI/bge-small-en-v1.5 via SentenceTransformers | |
| | Reranking | BAAI/bge-reranker-v2-m3 via FlagEmbedding | |
| | LLM Provider | Groq (llama-3.3-70b-versatile) | |
| | Deployment | Docker, Nginx, Supervisord, HuggingFace Spaces | |
|
|
| ## Architecture Overview |
|
|
| ```mermaid |
| graph TD |
| UI[Next.js Frontend] -->|REST API| Proxy[Nginx Reverse Proxy] |
| Proxy --> API[FastAPI Backend] |
| |
| API -->|Async Tasks| Queue[Redis / Celery Queue] |
| Queue --> Worker[Celery Workers] |
| |
| API -->|Read / Write| DB[(Neon Postgres)] |
| Worker -->|Persist Metadata| DB |
| |
| API -->|Vector Search| VectorDB[(Qdrant Cloud)] |
| Worker -->|Store Embeddings| VectorDB |
| |
| API -->|In-Memory Rerank| LocalAI[Local Reranker Model] |
| API -->|LLM Explanations| LLM[Groq API] |
| Worker -->|LLM Jobs| LLM |
| ```` |
|
|
| ## Project Structure |
|
|
| ```text |
| / |
| ├── backend/ |
| │ ├── alembic/ |
| │ ├── src/ |
| │ │ ├── matching/ |
| │ │ ├── ml/ |
| │ │ ├── models/ |
| │ │ ├── routers/ |
| │ │ ├── schemas/ |
| │ │ └── workers/ |
| │ ├── main.py |
| │ └── requirements.txt |
| ├── frontend/ |
| │ ├── public/ |
| │ ├── src/ |
| │ │ ├── app/ |
| │ │ └── lib/ |
| │ ├── next.config.ts |
| │ └── globals.css |
| ├── docker-compose.yml |
| ├── Dockerfile |
| ├── supervisord.conf |
| └── nginx.conf |
| ``` |
|
|
| ## Core Modules & Responsibilities |
|
|
| ### Backend |
|
|
| * **backend/src/ml** |
| Handles model loading, text embedding, and feature extraction. |
|
|
| * **backend/src/matching** |
| Implements retrieval, reranking, weighted scoring, and explanation logic. |
|
|
| * **backend/src/workers** |
| Runs background jobs such as candidate ingestion and explanation generation. |
|
|
| * **backend/src/routers** |
| Exposes API endpoints for sessions, JDs, candidates, matching, and health checks. |
|
|
| ### Frontend |
|
|
| * **frontend/src/app** |
| Contains user-facing routes such as sessions, JD details, and pipeline orchestration. |
|
|
| * **frontend/src/lib** |
| Centralized API client wrappers. |
|
|
| ## Application Flows |
|
|
| ### Candidate Upload & Ingestion Flow |
|
|
| ```mermaid |
| sequenceDiagram |
| actor User |
| participant UI as Next.js UI |
| participant API as FastAPI Router |
| participant Queue as Redis / Celery Queue |
| participant Worker as Celery Worker |
| participant Store as Postgres + Qdrant |
| |
| User->>UI: Upload candidate CSV/JSON |
| UI->>API: POST /api/candidates/upload |
| API->>Queue: Dispatch ingest_candidates_batch |
| API-->>UI: Return task ID |
| UI->>API: Poll /api/candidates/status/{task_id} |
| Worker->>Queue: Fetch task |
| Worker->>Worker: Parse candidate data |
| Worker->>Worker: Compute embeddings and growth velocity |
| Worker->>Store: Save metadata and vector points |
| Worker-->>Queue: Mark task complete |
| API-->>UI: Return success status |
| ``` |
|
|
| ### Matching & Reranking Flow |
|
|
| ```mermaid |
| sequenceDiagram |
| actor User |
| participant UI as Next.js UI |
| participant API as FastAPI Router |
| participant Qdrant as Vector DB |
| participant Reranker as Local Reranker |
| participant Cache as Redis Cache |
| |
| User->>UI: Open JD and click Match |
| UI->>API: POST /api/match/{jd_id} |
| API->>Qdrant: Retrieve top candidates |
| Qdrant-->>API: Return top-K vectors |
| API->>Reranker: Cross-encoder reranking |
| Reranker-->>API: Return adjusted scores |
| API->>API: Apply rank fusion and weights |
| API->>Cache: Store result |
| API-->>UI: Return ranked candidates |
| |
| User->>UI: Adjust weight sliders |
| UI->>API: POST /api/match/{jd_id}/rerank |
| API->>API: Recompute ranking in memory |
| API-->>UI: Return updated ordering |
| ``` |
|
|
| ### Explain & Refine Flow |
|
|
| ```mermaid |
| sequenceDiagram |
| actor User |
| participant UI as Next.js UI |
| participant API as FastAPI Router |
| participant DB as Postgres |
| participant LLM as Groq API |
| |
| User->>UI: Open candidate match details |
| UI->>API: POST /api/match/{jd_id}/candidates/{candidate_id}/explain |
| API->>DB: Load match data and gap analysis |
| API->>LLM: Generate grounded explanation |
| LLM-->>API: Return explanation text |
| API-->>UI: Show explanation to user |
| ``` |
|
|
| ## API Documentation |
|
|
| | Method | Path | Purpose | |
| | ------ | ---------------------------------------------------- | -------------------------- | |
| | POST | /api/sessions | Create a candidate session | |
| | GET | /api/sessions | List sessions | |
| | POST | /api/jds | Create a job description | |
| | GET | /api/jds | List job descriptions | |
| | POST | /api/candidates/upload?session_id= | Upload candidate files | |
| | GET | /api/candidates/status/{task_id} | Check task progress | |
| | POST | /api/match/{jd_id}?session_id= | Run full matching pipeline | |
| | POST | /api/match/{jd_id}/rerank | Rerank in memory | |
| | POST | /api/match/{jd_id}/candidates/{candidate_id}/explain | Generate explanation | |
| | GET | /health | Health check | |
| |
| ## Database Models |
| |
| * **Session** — Candidate batch container |
| * **JobDescription** — Stores JD text and parsed requirements |
| * **Candidate** — Stores profile, skills, work history, embeddings |
| * **MatchResult** — Stores scores, gaps, explanations, weights |
| |
| ## Authentication & Security |
| |
| * No formal authentication yet |
| * CORS allows all origins |
| * Minimal admin utility route exists |
| |
| ## State Management |
| |
| * React Hooks (`useState`, `useEffect`, `useCallback`) |
| * Local storage for persistence |
| * Redis for backend caching |
| |
| ## Caching & Performance |
| |
| * Cached match results by `jd_id + session_id` |
| * Models pre-downloaded into Docker image |
| * SQLAlchemy cache tuned for Neon pooling |
| |
| ## Setup & Installation |
| |
| ### Run Locally |
| |
| ```bash |
| docker-compose up --build |
| ``` |
| |
| ### Database Migration |
| |
| ```bash |
| cd backend |
| alembic upgrade head |
| ``` |
| |
| ## Environment Variables |
| |
| ```env |
| DATABASE_URL= |
| QDRANT_URL= |
| QDRANT_API_KEY= |
| REDIS_URL= |
| GROQ_API_KEY= |
| GROQ_MODEL= |
| EMBEDDING_MODEL= |
| RERANKER_MODEL= |
| NEXT_PUBLIC_API_URL= |
| ``` |
| |
| ## Deployment |
| |
| * Multi-stage Docker build |
| * Runs FastAPI + Next.js + Celery + Nginx |
| * Optimized for HuggingFace Spaces |
| * Exposes port `7860` |
| |
| ## Improvement Recommendations |
| |
| * Add JWT auth + RBAC |
| * Replace polling with WebSockets / SSE |
| * Add object storage |
| * Add automated tests |
| * Add observability & metrics |
| |
| ## Quick Summary |
| |
| TalentPulse combines semantic search, reranking, and LLM reasoning to help recruiters identify the best candidates faster, with explainable AI-powered hiring workflows. |
| |
| |
