README.md

metadata

title: Recruitment Copilot
emoji: 🎯
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Agentic recruitment copilot for HR teams.

Recruitment Copilot

An end-to-end agentic recruitment workspace built on Google ADK + FastMCP, with a Next.js chat UI rendered through the free Crayon UI components from the Thesys SDK.

It lets a recruiter:

• 🔍 Find candidates by natural-language queries ("give me top AI engineers", "anyone with NLP background").
• 📄 Ingest scanned or text PDFs — Gemini OCR is used as a fallback when pypdf returns nothing.
• 📋 Pull all company HR policies in one click, rendered as a tabbed infographic with a donut chart.
• 📝 Draft a structured job posting from a chat brief — full markdown post + skill-weighting bar chart.
• 📅 Schedule interviews — auto-generates a Google Meet link, builds an .ics, and emails both attendees via SMTP.
• ✉️ Compose follow-up emails: the agent returns three tonal drafts (formal / casual / polite); pick one, give a recipient, and the email goes out via SMTP.

Architecture

┌──────────────┐    ┌────────────────────┐    ┌─────────────────┐
│   Netlify    │───▶│  HF Spaces (Docker)│───▶│  Gemini API     │
│   Next.js    │    │  FastAPI + ADK +   │    │  (LLM + OCR)    │
│   frontend   │    │  MCP server        │    └─────────────────┘
└──────────────┘    └────────────────────┘    ┌─────────────────┐
                              ├─────────────▶│  Qdrant Cloud   │
                              │              │  (vector index) │
                              │              └─────────────────┘
                              │              ┌─────────────────┐
                              ├─────────────▶│  Supabase       │
                              │              │  Storage (PDFs) │
                              │              └─────────────────┘
                              │              ┌─────────────────┐
                              └─────────────▶│  Gmail SMTP     │
                                             │  (app password) │
                                             └─────────────────┘

Backend

• FastAPI serves the chat SSE stream and proxies tool calls.

• Google ADK agent (gemini-2.5-pro) orchestrates 10 MCP tools.

• FastMCP exposes those tools over /mcp-server/sse:

  Tool	Purpose
  ingest_resume_pdf	Parse a PDF (pypdf → Gemini OCR fallback) and persist to SQLite + Qdrant
  semantic_candidate_search	Vector search via Qdrant Cloud
  candidate_metadata_query	Keyword search over local SQLite, role-aware filtering
  compute_job_match_score	Score a single candidate against a JD
  get_policy_info	Return company HR policies (donut + tabs UI)
  manage_application_status	Track candidate stages
  manage_interview_records	Schedule interviews + auto-email Google Meet invite
  generate_job_posting	Draft a job posting from natural-language fields
  bulk_ingest_reference_resumes	Bootstrap demo data
  email_compose	Draft 3 tone variants → send via SMTP

Frontend

• Next.js 14 (App Router) with a streaming chat UI.
• Crayon UI (@crayonai/react-ui) for cards, callouts, charts (bar/pie/donut/radar), tabs, tags, buttons.
• A small chart auto-picker chooses bar / donut / radar based on the shape of the data the backend returns, so visualisations adapt to the response.

Local development

Prerequisites

• Python 3.11+
• Node.js 18+
• A Gemini API key — https://aistudio.google.com/apikey

One-shot bring-up (Windows / PowerShell)

copy .env.example .env       # then fill in GEMINI_API_KEY at minimum
.\start-all.ps1

This installs dependencies, starts FastAPI on http://127.0.0.1:7860 and Next.js on http://127.0.0.1:3000. Use .\stop-all.ps1 to shut both down.

Manual

# backend
cd backend
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 7860

# frontend (in another shell)
cd frontend
npm install
npm run dev

Configuration

All runtime config is read from .env. See .env.example for the full list with inline links to where each credential is generated.

Group	Vars	Required for
Gemini	GEMINI_API_KEY, GEMINI_MODEL, GEMINI_EMBEDDING_MODEL	LLM, embeddings, scanned-PDF OCR
Qdrant	QDRANT_URL, QDRANT_API_KEY, QDRANT_COLLECTION	Semantic candidate search
Object storage	S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_REGION, optional S3_PUBLIC_BASE_URL	Persistent resume PDF storage (Supabase Storage / Backblaze / S3 / MinIO)
SMTP	SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM, SMTP_USE_TLS	Auto-email interview invites + composed emails
Misc	BACKEND_URL, CALENDLY_EVENT_URL, THESYS_API_KEY	Frontend → backend wiring (Netlify), optional integrations

Deployment (free tier)

GitHub repo  →  Netlify (frontend)  ──▶  HF Space Docker (backend)
                                         ├──▶ Qdrant Cloud
                                         ├──▶ Supabase Storage
                                         └──▶ Gmail SMTP

1. Backend on Hugging Face Spaces (Docker)

1. Create a new Space → choose Docker → Blank.
2. The repo's root Dockerfile is picked up automatically.
3. In Settings → Variables and secrets, add every key from .env.example (Gemini / Qdrant / S3 / SMTP). Set CORS_ORIGINS=https://<your-netlify-site>.netlify.app.
4. git push this repo to the Space remote — HF builds and exposes the API at https://<user>-recruitment-copilot.hf.space.

2. Frontend on Netlify

1. Import this repo in Netlify.
2. Set Base directory to frontend.
3. Add env var BACKEND_URL=https://<user>-recruitment-copilot.hf.space.
4. Deploy.

3. External services (all free, no card)

• Qdrant Cloud — https://cloud.qdrant.io → 1 GB free cluster.
• Supabase Storage — https://supabase.com → Free project → create private resumes bucket → Settings → Storage → S3 access keys.
• Gemini API — https://aistudio.google.com/apikey.
• Gmail SMTP — https://myaccount.google.com/apppasswords (requires 2-step verification).

API surface

Endpoint	Purpose
GET /health	Backend liveness
GET /mcp-health	List of registered MCP tools
GET /api/tooling/status	Reports which optional integrations are configured
POST /api/upload?session_id=…	Multipart PDF resume upload
POST /api/chat	SSE stream — chat with the agent
GET /api/candidates/{external_id}	Full candidate profile (markdown + card + chart)
POST /api/bootstrap/sync-reference-resumes	Copy sample PDFs into the project storage dir
POST /api/bootstrap/reference-resumes	Bulk-ingest the synced PDFs
GET /mcp-server/sse	MCP SSE stream endpoint
POST /mcp-server/messages/?session_id=…	MCP SSE message channel

SSE event contract (/api/chat)

Event	Payload
status	{ message }
token	{ delta } (incremental text)
genui	{ summary, markdown?, cards?, chart?, table?, tabs? }
done	{ message } (final text)
error	{ message }

Project layout

.
├── backend/
│   ├── agent/                # Google ADK runtime + agent definition
│   ├── core/                 # Settings, DB session, models, schemas, utils
│   ├── mcp_server/           # FastMCP server + 10 tool modules
│   │   └── tools/
│   ├── services/             # Candidate / search / ingestion / storage / notifications
│   ├── scripts/              # Reference-resume sync utilities
│   └── main.py               # FastAPI app + chat SSE stream
├── frontend/
│   └── src/
│       ├── app/api/          # Next.js API proxy routes (chat, upload, candidates)
│       └── components/       # Chat UI + Crayon-powered renderer
├── Dockerfile                # HF Spaces backend image
├── start-all.ps1 / stop-all.ps1
├── .env.example
├── LICENSE
└── README.md

License

MIT — see LICENSE.