README.md

---
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)
```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
```bash
# 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`](.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`](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](LICENSE).