Recruitment Copilot

.gitignore

@@ -0,0 +1,58 @@
+# =============================================================================
+# Recruitment Copilot — git ignore
+# =============================================================================
+
+# --- Secrets -----------------------------------------------------------------
+.env
+.env.*
+!.env.example
+frontend/.env.local
+backend/.env
+
+# --- Python ------------------------------------------------------------------
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+env/
+
+# --- Node / Next.js ----------------------------------------------------------
+node_modules/
+.next/
+out/
+.turbo/
+.swc/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# --- Local data (regenerated at runtime; do not commit user data) -----------
+backend/data/uploads/
+backend/data/candidates.db
+backend/data/*.sqlite*
+backend/data/job_postings.json
+backend/data/reference_resumes/
+
+# --- Build / runtime artefacts ----------------------------------------------
+logs/
+.local-dev-processes.json
+*.log
+adk-events.log
+
+# --- IDE / OS ----------------------------------------------------------------
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+*.swp
+
+# --- Internal design docs (not for the public repo) -------------------------
+GenUi_Recruitement_Agent.docx
+GenUi_Recruitement_Agent.pdf
+__req_copy.docx

Dockerfile

@@ -0,0 +1,34 @@
+# Hugging Face Space (Docker SDK) — backend only.
+# The frontend runs separately on Netlify (or Vercel). Netlify only needs
+# BACKEND_URL pointing at this Space's public URL.
+
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_HOME=/home/user/.cache/huggingface
+
+# HF Spaces runs containers as UID 1000. Create that user up-front so writes to
+# uploads/data/logs work without root.
+RUN useradd --create-home --uid 1000 user
+
+WORKDIR /home/user/app
+
+COPY --chown=user:user backend/requirements.txt requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user:user backend ./backend
+
+# Pre-create the writable directories the app expects. On the free Space tier
+# these are ephemeral (wiped on rebuild/sleep) — point S3_* at Supabase Storage
+# in your Space secrets to persist resume PDFs across restarts.
+RUN mkdir -p backend/data/uploads backend/data/reference_resumes logs && \
+    chown -R user:user backend/data logs
+
+USER user
+WORKDIR /home/user/app/backend
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashgen12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,185 @@
 ---
 title: Recruitment Copilot
-emoji: 📊
+emoji: 🎯
 colorFrom: green
-colorTo: pink
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
+short_description: Agentic recruitment copilot for HR teams.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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).

backend/Dockerfile

@@ -0,0 +1,17 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+COPY backend/requirements.txt /app/requirements.txt
+RUN pip install --no-cache-dir -r /app/requirements.txt
+
+COPY backend /app/backend
+
+WORKDIR /app/backend
+
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

backend/agent/__init__.py

@@ -0,0 +1 @@
+"""Google ADK root agent and runtime adapters."""

backend/agent/agent.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+
+from google.adk.agents import LlmAgent
+from google.adk.tools.mcp_tool.mcp_toolset import (
+    MCPToolset,
+    SseConnectionParams,
+)
+
+from core.config import get_settings
+
+
+def create_root_agent() -> LlmAgent:
+    settings = get_settings()
+
+    if settings.gemini_api_key and not os.environ.get("GOOGLE_API_KEY"):
+        os.environ["GOOGLE_API_KEY"] = settings.gemini_api_key
+
+    instruction = """
+You are a senior Recruitment Copilot built on Google ADK. You MUST drive every recruiter
+intent through MCP tool calls — never answer from your own knowledge when a tool exists.
+
+Available MCP tools and when to call them:
+
+1) get_policy_info(policy_name)
+   - ALWAYS call this when the user asks anything about company policies: leave, vacation,
+     work-from-home, hybrid/remote, referral, interview, code of conduct, conduct, ethics.
+   - For generic asks ("check company policies", "show me all policies"), pass
+     policy_name="all" so the tool returns every policy.
+
+2) generate_job_posting(title, location, experience_years, skills, employment_type, mode)
+   - Call as soon as you have enough fields. If the user provides a multi-line block with
+     "Job Title:", "Location:", "Required Skills:", "Experience Required:", parse those
+     directly and CALL THE TOOL on the next turn — do NOT ask for re-confirmation.
+   - skills must be a comma-separated string. experience_years is a single integer
+     (lower bound is fine if the user gives a range like "5-8").
+
+3) manage_interview_records(mode, ...)
+   - Call with mode="schedule" when the user gives candidate_name, candidate_email,
+     interviewer_name, interviewer_email, date (YYYY-MM-DD), and time. Parse the structured
+     block the user gives — do NOT ask again for fields already provided.
+   - Use mode="list" to show upcoming interviews.
+
+4) manage_application_status(mode, ...)
+   - Call with mode="upsert", "advance", "get", or "list" for application stage updates.
+
+5) semantic_candidate_search(query, top_k)
+   - Call when the user asks to FIND, SEARCH, RANK, or SHORTLIST candidates by skills,
+     role, or location.
+
+6) candidate_metadata_query(query, limit)
+   - Use as a fallback when semantic_candidate_search returns nothing, or for exact metadata.
+
+7) compute_job_match_score(candidate_summary, job_description)
+   - Use when a single candidate must be scored against a JD.
+
+8) ingest_resume_pdf(file_path)
+   - Use when the user attaches a resume.
+
+9) bulk_ingest_reference_resumes(limit)
+   - Use only if the candidate database appears empty.
+
+10) email_compose(mode, ...)
+    - When the user says "draft an email", "compose email", "write a follow-up", or
+      uses the Draft Email quick action, call email_compose(mode="draft", brief=<the
+      natural-language brief>, recipient_name=<optional>) — the tool returns three
+      tone variants (formal / casual / polite).
+    - Show all three tones to the user. When they pick one ("use formal", "send the
+      casual one", etc.) and provide an email address, call email_compose(
+      mode="send", recipient_email=<address>, subject=<from chosen draft>,
+      body=<from chosen draft>, tone=<chosen tone>) to actually deliver it.
+
+Conversation rules:
+- When a quick action like "Check company policies" arrives, immediately call
+  get_policy_info(policy_name="all") instead of asking the user which policy.
+- When a quick action like "Create job posting" arrives without details, ask once for the
+  required fields. As soon as the next user turn provides them, CALL generate_job_posting.
+- When a quick action like "Schedule interview" arrives without details, ask once for the
+  required fields. As soon as the next user turn provides them, CALL manage_interview_records.
+- After every successful tool call, write a short recruiter-facing markdown summary of the
+  result. Do NOT include any candidate-search JSON unless you actually called a search tool.
+- If a tool returns status "error" or "not_found", tell the user exactly what's missing.
+- Do not invent candidate facts that did not come from a tool result.
+""".strip()
+
+    return LlmAgent(
+        name="Recruitment_Root_Agent",
+        description="Root recruitment orchestrator using MCP tools",
+        model=settings.gemini_model,
+        instruction=instruction,
+        tools=[
+            MCPToolset(
+                connection_params=SseConnectionParams(
+                    url=settings.mcp_server_base_url,
+                ),
+                tool_filter=[
+                    "ingest_resume_pdf",
+                    "semantic_candidate_search",
+                    "candidate_metadata_query",
+                    "compute_job_match_score",
+                    "get_policy_info",
+                    "manage_application_status",
+                    "manage_interview_records",
+                    "generate_job_posting",
+                    "bulk_ingest_reference_resumes",
+                    "email_compose",
+                ],
+            )
+        ],
+    )
+
+
+root_agent = create_root_agent()

backend/agent/runtime.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from google.adk.runners import InMemoryRunner
+from google.genai import types
+
+from agent.agent import root_agent
+from core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SessionState:
+    runner: InMemoryRunner
+
+
+@dataclass
+class TurnResult:
+    text: str = ""
+    tool_calls: list[dict[str, Any]] = field(default_factory=list)
+
+
+class ADKRuntime:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self._sessions: dict[tuple[str, str], SessionState] = {}
+
+    async def run_turn(self, message: str, user_id: str, session_id: str) -> str:
+        result = await self.run_turn_detailed(
+            message=message,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        return result.text
+
+    async def run_turn_detailed(
+        self,
+        message: str,
+        user_id: str,
+        session_id: str,
+    ) -> TurnResult:
+        runner = await self._get_or_create_runner(user_id=user_id, session_id=session_id)
+
+        user_content = types.Content(
+            role="user",
+            parts=[types.Part.from_text(text=message)],
+        )
+
+        latest_text = ""
+        tool_calls: list[dict[str, Any]] = []
+        async for event in runner.run_async(
+            user_id=user_id,
+            session_id=session_id,
+            new_message=user_content,
+        ):
+            extracted = self._extract_text(event)
+            if extracted.strip():
+                latest_text = extracted
+
+            new_tool_responses = self._extract_tool_responses(event)
+            if new_tool_responses:
+                tool_calls.extend(new_tool_responses)
+
+        return TurnResult(text=latest_text.strip(), tool_calls=tool_calls)
+
+    async def _get_or_create_runner(self, user_id: str, session_id: str) -> InMemoryRunner:
+        key = (user_id, session_id)
+        existing = self._sessions.get(key)
+        if existing is not None:
+            return existing.runner
+
+        runner = InMemoryRunner(agent=root_agent, app_name=self.settings.app_name)
+        await runner.session_service.create_session(
+            app_name=self.settings.app_name,
+            user_id=user_id,
+            session_id=session_id,
+        )
+        self._sessions[key] = SessionState(runner=runner)
+        return runner
+
+    @staticmethod
+    def _extract_text(event: Any) -> str:
+        content = getattr(event, "content", None)
+        if content is None:
+            return ""
+
+        parts = getattr(content, "parts", None)
+        if not parts:
+            return ""
+
+        chunks: list[str] = []
+        for part in parts:
+            text = getattr(part, "text", None)
+            if isinstance(text, str) and text:
+                chunks.append(text)
+
+        return "\n".join(chunks)
+
+    @staticmethod
+    def _debug_dump_event(event: Any) -> None:
+        try:
+            import json
+            from pathlib import Path
+            payload: dict[str, Any] = {"type": type(event).__name__}
+            content = getattr(event, "content", None)
+            if content is not None:
+                payload["content_role"] = getattr(content, "role", None)
+                parts_info = []
+                for part in getattr(content, "parts", None) or []:
+                    fr = getattr(part, "function_response", None)
+                    info: dict[str, Any] = {
+                        "has_text": bool(getattr(part, "text", None)),
+                        "has_function_call": bool(getattr(part, "function_call", None)),
+                        "has_function_response": bool(fr),
+                    }
+                    if fr is not None:
+                        info["fr_name"] = getattr(fr, "name", None)
+                        resp = getattr(fr, "response", None)
+                        info["fr_response_type"] = type(resp).__name__
+                        info["fr_response_repr"] = repr(resp)[:1500]
+                        if isinstance(resp, dict):
+                            info["fr_response_keys"] = list(resp.keys())
+                    parts_info.append(info)
+                payload["parts"] = parts_info
+            log_path = Path(__file__).resolve().parents[1] / "logs" / "adk-events.log"
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            with log_path.open("a", encoding="utf-8") as fh:
+                fh.write(json.dumps(payload, default=str) + "\n")
+        except Exception as exc:
+            try:
+                from pathlib import Path
+                log_path = Path(__file__).resolve().parents[1] / "logs" / "adk-events.log"
+                with log_path.open("a", encoding="utf-8") as fh:
+                    fh.write(f"DUMP-ERR: {exc}\n")
+            except Exception:
+                pass
+
+    @staticmethod
+    def _extract_tool_responses(event: Any) -> list[dict[str, Any]]:
+        """Pull MCP tool responses out of an ADK event so we can render their UI payloads."""
+        content = getattr(event, "content", None)
+        if content is None:
+            return []
+        parts = getattr(content, "parts", None) or []
+
+        responses: list[dict[str, Any]] = []
+        for part in parts:
+            function_response = getattr(part, "function_response", None)
+            if function_response is None:
+                continue
+            name = getattr(function_response, "name", None) or ""
+            response = getattr(function_response, "response", None)
+            payload = ADKRuntime._coerce_tool_payload(response)
+            if payload is None:
+                continue
+            responses.append({"name": name, "response": payload})
+
+        # ADK sometimes surfaces tool results via convenience attributes on the
+        # event itself (e.g. event.actions.state_delta or event.tool_responses).
+        # Dig those up too so we don't miss the UI payload.
+        for attr in ("tool_responses", "function_responses"):
+            extra = getattr(event, attr, None)
+            if not extra:
+                continue
+            if isinstance(extra, list):
+                for item in extra:
+                    name = getattr(item, "name", None) or ""
+                    response = getattr(item, "response", None)
+                    payload = ADKRuntime._coerce_tool_payload(response)
+                    if payload is not None:
+                        responses.append({"name": name, "response": payload})
+
+        return responses
+
+    @staticmethod
+    def _coerce_tool_payload(value: Any) -> dict[str, Any] | None:
+        """Unwrap a tool response into a plain dict.
+
+        ADK + MCP delivers tool results as one of several shapes:
+          1. ``{"result": <plain dict>}``      — direct ADK function tool
+          2. ``{"result": CallToolResult(...)}``— MCP toolset wraps the response
+             into an ``mcp.types.CallToolResult`` whose ``content`` is a list of
+             ``TextContent`` items carrying JSON-encoded text.
+          3. ``CallToolResult(...)``           — same as above, unwrapped.
+          4. plain dict already.
+        """
+        import json
+
+        # Step 1: pull off the optional "result" wrapper.
+        if isinstance(value, dict) and "result" in value and len(value) == 1:
+            value = value["result"]
+
+        # Step 2: plain dict — done.
+        if isinstance(value, dict):
+            return value
+
+        # Step 3: MCP CallToolResult / TextContent. Detect by duck-typing the
+        # ``content`` attribute that holds a list of items with ``.text``.
+        content_items = getattr(value, "content", None)
+        if isinstance(content_items, list) and content_items:
+            for item in content_items:
+                text = getattr(item, "text", None)
+                if isinstance(text, str) and text.strip():
+                    try:
+                        parsed = json.loads(text)
+                        if isinstance(parsed, dict):
+                            return parsed
+                    except json.JSONDecodeError:
+                        continue
+
+        # Step 4: protobuf Struct fallback.
+        to_dict = getattr(value, "to_dict", None)
+        if callable(to_dict):
+            try:
+                converted = to_dict()
+                if isinstance(converted, dict):
+                    return converted.get("result", converted)
+            except Exception:
+                return None
+
+        return None

backend/core/__init__.py

@@ -0,0 +1 @@
+"""Core backend package for config, models, and shared utilities."""

backend/core/config.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+ROOT_DIR = Path(__file__).resolve().parents[2]
+
+
+class Settings(BaseSettings):
+    app_name: str = Field(default="Recruitment Agent API", validation_alias="APP_NAME")
+    environment: str = Field(default="development", validation_alias="APP_ENV")
+    host: str = Field(default="0.0.0.0", validation_alias="APP_HOST")
+    port: int = Field(default=7860, validation_alias="APP_PORT")
+    cors_origins: str = Field(default="*", validation_alias="CORS_ORIGINS")
+
+    gemini_api_key: str = Field(default="", validation_alias="GEMINI_API_KEY")
+    gemini_model: str = Field(default="gemini-2.5-flash", validation_alias="GEMINI_MODEL")
+    embedding_model: str = Field(
+        default="models/text-embedding-004",
+        validation_alias="GEMINI_EMBEDDING_MODEL",
+    )
+
+    qdrant_url: str | None = Field(default=None, validation_alias="QDRANT_URL")
+    qdrant_api_key: str | None = Field(default=None, validation_alias="QDRANT_API_KEY")
+    qdrant_collection: str = Field(
+        default="recruitment_candidates",
+        validation_alias="QDRANT_COLLECTION",
+    )
+
+    # Generic S3-compatible storage. Works with Supabase Storage, Backblaze B2,
+    # AWS S3, MinIO, etc. — just point S3_ENDPOINT at the provider's URL.
+    s3_endpoint: str | None = Field(default=None, validation_alias="S3_ENDPOINT")
+    s3_access_key_id: str | None = Field(default=None, validation_alias="S3_ACCESS_KEY_ID")
+    s3_secret_access_key: str | None = Field(
+        default=None,
+        validation_alias="S3_SECRET_ACCESS_KEY",
+    )
+    s3_bucket: str | None = Field(default=None, validation_alias="S3_BUCKET")
+    s3_region: str = Field(default="us-east-1", validation_alias="S3_REGION")
+    s3_public_base_url: str | None = Field(
+        default=None,
+        validation_alias="S3_PUBLIC_BASE_URL",
+    )
+
+    sqlite_db_path: str = Field(
+        default=str(ROOT_DIR / "backend" / "data" / "candidates.db"),
+        validation_alias="SQLITE_DB_PATH",
+    )
+    uploads_dir: str = Field(
+        default=str(ROOT_DIR / "backend" / "data" / "uploads"),
+        validation_alias="UPLOADS_DIR",
+    )
+
+    mcp_server_base_url: str = Field(
+        default="http://127.0.0.1:7860/mcp-server/sse",
+        validation_alias="MCP_SERVER_BASE_URL",
+    )
+
+    chunk_size: int = Field(default=1100, validation_alias="CHUNK_SIZE")
+    chunk_overlap: int = Field(default=150, validation_alias="CHUNK_OVERLAP")
+    max_chunks_per_document: int = Field(default=50, validation_alias="MAX_CHUNKS_PER_DOC")
+
+    smtp_host: str | None = Field(default=None, validation_alias="SMTP_HOST")
+    smtp_port: int = Field(default=587, validation_alias="SMTP_PORT")
+    smtp_user: str | None = Field(default=None, validation_alias="SMTP_USER")
+    smtp_password: str | None = Field(default=None, validation_alias="SMTP_PASSWORD")
+    smtp_from: str | None = Field(default=None, validation_alias="SMTP_FROM")
+    smtp_use_tls: bool = Field(default=True, validation_alias="SMTP_USE_TLS")
+    calendly_event_url: str | None = Field(default=None, validation_alias="CALENDLY_EVENT_URL")
+
+    model_config = SettingsConfigDict(
+        env_file=(str(ROOT_DIR / ".env"), str(ROOT_DIR.parent / ".env")),
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @property
+    def sqlite_url(self) -> str:
+        return f"sqlite:///{Path(self.sqlite_db_path).resolve()}"
+
+    @property
+    def cors_origin_list(self) -> list[str]:
+        if self.cors_origins.strip() == "*":
+            return ["*"]
+        return [item.strip() for item in self.cors_origins.split(",") if item.strip()]
+
+    @property
+    def has_qdrant_config(self) -> bool:
+        return bool(self.qdrant_url and self.qdrant_api_key)
+
+    @property
+    def has_s3_config(self) -> bool:
+        return bool(
+            self.s3_endpoint
+            and self.s3_access_key_id
+            and self.s3_secret_access_key
+            and self.s3_bucket
+        )
+
+    @property
+    def has_smtp_config(self) -> bool:
+        return bool(self.smtp_host and self.smtp_from)
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()

backend/core/db.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from core.config import get_settings
+from core.models import Base
+
+settings = get_settings()
+
+sqlite_path = Path(settings.sqlite_db_path)
+sqlite_path.parent.mkdir(parents=True, exist_ok=True)
+
+engine = create_engine(
+    settings.sqlite_url,
+    connect_args={"check_same_thread": False},
+)
+
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+def init_db() -> None:
+    Base.metadata.create_all(bind=engine)
+
+
+def get_db() -> Generator[Session, None, None]:
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

backend/core/models.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Float, Integer, String, Text
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Candidate(Base):
+    __tablename__ = "candidates"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    external_id: Mapped[str] = mapped_column(String(64), unique=True, index=True)
+
+    full_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    email: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    phone: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    location: Mapped[str | None] = mapped_column(String(255), nullable=True)
+
+    years_experience: Mapped[float | None] = mapped_column(Float, nullable=True)
+    skills_csv: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    summary: Mapped[str | None] = mapped_column(Text, nullable=True)
+    source_resume_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    source_resume_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        onupdate=datetime.utcnow,
+    )
+
+
+class QueryAudit(Base):
+    __tablename__ = "query_audit"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    session_id: Mapped[str] = mapped_column(String(128), index=True)
+    query: Mapped[str] = mapped_column(Text)
+    top_k: Mapped[int] = mapped_column(Integer, default=5)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+
+class ApplicationStatus(Base):
+    __tablename__ = "application_status"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    candidate_id: Mapped[str] = mapped_column(String(64), index=True)
+    candidate_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    role_applied: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    stage: Mapped[str] = mapped_column(String(128), default="Applied")
+    status: Mapped[str] = mapped_column(String(128), default="Open")
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        onupdate=datetime.utcnow,
+    )
+
+
+class InterviewRecord(Base):
+    __tablename__ = "interview_records"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    candidate_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
+    candidate_name: Mapped[str] = mapped_column(String(255))
+    candidate_email: Mapped[str] = mapped_column(String(255), index=True)
+
+    interviewer_name: Mapped[str] = mapped_column(String(255))
+    interviewer_email: Mapped[str] = mapped_column(String(255), index=True)
+    interview_round: Mapped[str] = mapped_column(String(128), default="Screening")
+
+    scheduled_on: Mapped[datetime] = mapped_column(DateTime)
+    end_time: Mapped[datetime] = mapped_column(DateTime)
+    duration_minutes: Mapped[int] = mapped_column(Integer, default=60)
+
+    meeting_link: Mapped[str | None] = mapped_column(String(1024), nullable=True)
+    status: Mapped[str] = mapped_column(String(64), default="Scheduled")
+    notes: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime,
+        default=datetime.utcnow,
+        onupdate=datetime.utcnow,
+    )

backend/core/schemas.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ChatRequest(BaseModel):
+    message: str = Field(min_length=1)
+    session_id: str = Field(default="web-session")
+    user_id: str = Field(default="web-user")
+    top_k: int = Field(default=5, ge=1, le=25)
+
+
+class CandidateCard(BaseModel):
+    title: str
+    subtitle: str | None = None
+    tags: list[str] = Field(default_factory=list)
+    meta: dict[str, Any] = Field(default_factory=dict)
+    actions: list[dict[str, str]] = Field(default_factory=list)
+
+
+class GenUiPayload(BaseModel):
+    summary: str | None = None
+    cards: list[CandidateCard] = Field(default_factory=list)
+    chart: dict[str, Any] | None = None
+    table: dict[str, Any] | None = None
+
+
+class UploadResponse(BaseModel):
+    candidate_id: str
+    file_name: str
+    message: str
+    chunks_indexed: int
+    r2_url: str | None = None
+
+
+class ToolStatusResponse(BaseModel):
+    gemini_configured: bool
+    qdrant_configured: bool
+    r2_configured: bool
+    mcp_url: str

backend/core/utils.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def chunk_text_for_stream(text: str, chunk_size: int = 36) -> list[str]:
+    if not text:
+        return []
+    chunks: list[str] = []
+    for idx in range(0, len(text), chunk_size):
+        chunks.append(text[idx : idx + chunk_size])
+    return chunks
+
+
+def format_sse(event: str, data: dict[str, Any]) -> str:
+    return f"event: {event}\ndata: {json.dumps(data, ensure_ascii=False)}\n\n"
+
+
+def extract_json_object(raw_text: str) -> dict[str, Any] | None:
+    stripped = raw_text.strip()
+    if not stripped:
+        return None
+
+    try:
+        loaded = json.loads(stripped)
+        if isinstance(loaded, dict):
+            return loaded
+    except json.JSONDecodeError:
+        pass
+
+    fenced = re.findall(r"```json\s*(\{.*?\})\s*```", stripped, flags=re.DOTALL)
+    for block in fenced:
+        try:
+            loaded = json.loads(block)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            continue
+
+    brace_match = re.search(r"(\{.*\})", stripped, flags=re.DOTALL)
+    if brace_match:
+        candidate = brace_match.group(1)
+        try:
+            loaded = json.loads(candidate)
+            if isinstance(loaded, dict):
+                return loaded
+        except json.JSONDecodeError:
+            return None
+
+    return None
+
+
+# Intent phrases — any one of these anywhere in the message indicates the user wants
+# the system to surface people. Designed to catch natural phrasing.
+_CANDIDATE_SEARCH_INTENTS = (
+    "give me",
+    "show me",
+    "find me",
+    "fetch me",
+    "get me",
+    "send me",
+    "bring me",
+    "i need",
+    "i want",
+    "i'm looking",
+    "im looking",
+    "looking for",
+    "looking to hire",
+    "want to hire",
+    "need to hire",
+    "who has",
+    "who knows",
+    "who can",
+    "anyone with",
+    "any candidate",
+    "any developer",
+    "any engineer",
+    "any profile",
+    "search ",
+    "find ",
+    "fetch ",
+    "rank ",
+    "shortlist",
+    "list ",
+    "show ",
+    "match ",
+    "filter ",
+    "top ",
+    "best ",
+    "candidate for",
+    "candidates for",
+    "candidate with",
+    "candidates with",
+    "candidate having",
+    "candidates having",
+    "candidate who",
+    "candidates who",
+    "engineer for",
+    "engineers for",
+    "developer for",
+    "developers for",
+)
+
+_CANDIDATE_ROLE_WORDS = (
+    "engineer",
+    "engineers",
+    "developer",
+    "developers",
+    "scientist",
+    "scientists",
+    "analyst",
+    "analysts",
+    "designer",
+    "designers",
+    "manager",
+    "managers",
+    "architect",
+    "architects",
+    "intern",
+    "interns",
+    "lead",
+    "leads",
+    "consultant",
+    "consultants",
+    "specialist",
+    "specialists",
+    "candidate",
+    "candidates",
+    "resume",
+    "resumes",
+    "profile",
+    "profiles",
+    "people",
+    "talent",
+    "experience",  # "candidate for AI experience"
+    "expertise",
+    "skill",
+    "skills",
+    "background",
+)
+
+_CANDIDATE_SEARCH_NEGATIVE_PHRASES = (
+    "this pdf",
+    "the pdf",
+    "this resume",
+    "the resume",
+    "this file",
+    "the file",
+    "uploaded pdf",
+    "uploaded resume",
+    "uploaded file",
+    "this candidate",
+    "the candidate",
+    "this person",
+    "the person",
+    "this applicant",
+    "the applicant",
+    "this profile",
+    "the profile",
+    "their resume",
+    "their profile",
+    "their experience",
+    "his resume",
+    "her resume",
+    "his profile",
+    "her profile",
+    "about him",
+    "about her",
+)
+
+
+def looks_like_candidate_search(query: str) -> bool:
+    """Heuristic: does the user's message ask the system to find people?
+
+    Accepts natural phrasing — "give me candidate for AI experience", "I need a
+    frontend developer", "anyone with NLP background", "looking for top python
+    engineers in Bangalore", etc. Requires both an *intent phrase* (give me / show
+    me / find / I need / looking for / etc.) and a *role/skill noun* (engineer /
+    developer / candidate / experience / skill / etc.).
+
+    Filters out chat actions and messages about a specific uploaded resume so we
+    don't hijack other flows.
+    """
+    lowered = (query or "").strip().lower()
+    if not lowered:
+        return False
+
+    if lowered.startswith(("open_profile", "shortlist:", "details:", "publish_job_posting", "edit_job_posting")):
+        return False
+
+    if any(neg in lowered for neg in _CANDIDATE_SEARCH_NEGATIVE_PHRASES):
+        return False
+
+    has_intent = any(intent in lowered for intent in _CANDIDATE_SEARCH_INTENTS)
+    has_role = any(role in lowered for role in _CANDIDATE_ROLE_WORDS)
+    return has_intent and has_role
+
+
+def parse_action_command(query: str) -> tuple[str, str] | None:
+    """Detect chat messages that look like card action commands such as ``open_profile:<id>``."""
+    if not query:
+        return None
+
+    cleaned = query.strip()
+    if ":" not in cleaned:
+        return None
+
+    head, _, tail = cleaned.partition(":")
+    head = head.strip().lower()
+    tail = tail.strip()
+    if not tail or " " in head:
+        return None
+
+    if head in {"open_profile", "details", "shortlist", "publish_job_posting", "edit_job_posting"}:
+        return head, tail
+    return None
+
+
+def looks_like_c1_response(text: str) -> bool:
+    lowered = text.lower()
+    has_content_root = "<content" in lowered and "</content>" in lowered
+    if not has_content_root:
+        return False
+    return (
+        "<custom_markdown" in lowered
+        or "<custommarkdown" in lowered
+        or "<artifact" in lowered
+    )
+
+
+def wrap_text_as_c1(text: str) -> str:
+    """Wrap plain markdown in the schema-stable C1 envelope.
+
+    Thesys's <C1Component> renders <custom_markdown> reliably without their
+    fine-tuned model — anything richer requires the API. Wrapping any agent
+    text in this envelope means every response renders through the SDK,
+    giving uniform typography/styling.
+    """
+    text = (text or "").strip()
+    if not text:
+        return ""
+    if looks_like_c1_response(text):
+        return text
+    safe = (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+    )
+    return f"<content><custom_markdown>{safe}</custom_markdown></content>"
+
+
+def build_c1_response(text: str, payload: dict[str, Any] | None = None) -> str:
+    clean_text = (text or "").strip()
+    if clean_text and looks_like_c1_response(clean_text):
+        return clean_text
+
+    if payload:
+        payload_c1 = payload.get("c1_response") or payload.get("c1Response")
+        if isinstance(payload_c1, str):
+            payload_c1 = payload_c1.strip()
+            if payload_c1 and looks_like_c1_response(payload_c1):
+                return payload_c1
+
+    return ""

backend/data/policies.json

@@ -0,0 +1,7 @@
+{
+  "leave policy": "Employees are eligible for 18 paid leave days per year, plus national holidays. Casual leave requests should be submitted at least 48 hours in advance whenever possible.",
+  "work from home policy": "Hybrid work is allowed for eligible roles up to 3 days per week with manager approval. Team-level coverage and client commitments take priority.",
+  "referral policy": "Employees can refer candidates through the recruitment portal. Referral bonuses are paid after the referred candidate completes the probation period.",
+  "interview policy": "Interview feedback must be submitted within 24 hours. Each candidate should be evaluated on role-specific rubrics and structured competency notes.",
+  "code of conduct": "All employees must maintain professional behavior, protect confidential data, and follow anti-harassment and equal opportunity policies."
+}

backend/data/seed_candidates.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import argparse
+import random
+import sys
+from pathlib import Path
+
+from faker import Faker
+
+BACKEND_ROOT = Path(__file__).resolve().parents[1]
+if str(BACKEND_ROOT) not in sys.path:
+    sys.path.insert(0, str(BACKEND_ROOT))
+
+from core.db import SessionLocal, init_db
+from services.ingestion_service import IngestionService
+
+faker = Faker()
+
+SKILL_POOLS = [
+    ["python", "fastapi", "sql", "docker"],
+    ["java", "spring", "kubernetes", "aws"],
+    ["react", "typescript", "next.js", "node"],
+    ["ml", "nlp", "llm", "python"],
+    ["data engineering", "airflow", "spark", "sql"],
+]
+
+
+def build_synthetic_resume(name: str, years: int, skills: list[str], location: str) -> str:
+    return (
+        f"{name}\n"
+        f"Location: {location}\n"
+        f"Experience: {years} years\n"
+        f"Skills: {', '.join(skills)}\n"
+        f"Summary: {faker.paragraph(nb_sentences=6)}\n"
+        f"Projects: {faker.paragraph(nb_sentences=4)}"
+    )
+
+
+def seed(count: int) -> None:
+    init_db()
+    ingestion = IngestionService()
+
+    inserted = 0
+    with SessionLocal() as db:
+        for _ in range(count):
+            name = faker.name()
+            years = random.randint(1, 14)
+            location = faker.city()
+            skills = random.choice(SKILL_POOLS)
+            resume_text = build_synthetic_resume(name=name, years=years, skills=skills, location=location)
+
+            ingestion.ingest_text_profile(
+                db,
+                candidate_name=name,
+                resume_text=resume_text,
+                location=location,
+                skills=skills,
+                years_experience=float(years),
+            )
+            inserted += 1
+
+    print(f"Seed complete. Inserted {inserted} synthetic candidates.")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Seed synthetic candidate profiles.")
+    parser.add_argument("--count", type=int, default=200, help="Number of synthetic candidates")
+    args = parser.parse_args()
+    seed(args.count)

backend/main.py

@@ -0,0 +1,439 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, File, HTTPException, Query, UploadFile
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+
+from agent.runtime import ADKRuntime
+from core.config import get_settings
+from core.db import SessionLocal, init_db
+from core.schemas import ChatRequest, ToolStatusResponse, UploadResponse
+from core.utils import (
+    build_c1_response,
+    chunk_text_for_stream,
+    extract_json_object,
+    format_sse,
+    looks_like_candidate_search,
+    parse_action_command,
+    wrap_text_as_c1,
+)
+from mcp_server.server import mcp_app
+from services.candidate_service import CandidateService
+from services.ingestion_service import IngestionService
+from services.reference_data_service import ingest_reference_resumes, sync_reference_resumes_to_local
+from services.search_service import QdrantSearchService
+
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+app = FastAPI(title=settings.app_name)
+app.mount("/mcp-server", mcp_app)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_origin_list,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+runtime = ADKRuntime()
+ingestion_service = IngestionService()
+search_service = QdrantSearchService()
+candidate_service = CandidateService()
+
+# Tracks the most recent resume uploads per session so the agent can answer
+# "tell me about the PDF" without the user pasting the candidate id back in.
+_session_recent_uploads: dict[str, dict[str, str]] = {}
+
+
+def _remember_upload(session_id: str | None, candidate_id: str, file_name: str) -> None:
+    if not session_id:
+        return
+    _session_recent_uploads[session_id] = {
+        "candidate_id": candidate_id,
+        "file_name": file_name,
+    }
+
+
+def _build_session_upload_hint(session_id: str) -> str:
+    info = _session_recent_uploads.get(session_id)
+    if not info:
+        return ""
+    return (
+        "\n\n[Recent upload context: the user just uploaded the resume "
+        f"`{info['file_name']}` and it has been ingested as candidate id "
+        f"`{info['candidate_id']}`. If their question refers to 'this pdf', "
+        "'the resume', 'the file', or similar, it means this candidate. "
+        "Call candidate_metadata_query with that candidate_id to fetch the "
+        "stored summary, or use open_profile via the standard action.]"
+    )
+
+
+@app.on_event("startup")
+def startup_event() -> None:
+    init_db()
+    Path(settings.uploads_dir).mkdir(parents=True, exist_ok=True)
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"ok": True, "service": settings.app_name}
+
+
+@app.get("/mcp-health")
+def mcp_health() -> dict:
+    return {
+        "ok": True,
+        "mcp_endpoint": settings.mcp_server_base_url,
+        "tools": [
+            "ingest_resume_pdf",
+            "semantic_candidate_search",
+            "candidate_metadata_query",
+            "compute_job_match_score",
+            "get_policy_info",
+            "manage_application_status",
+            "manage_interview_records",
+            "generate_job_posting",
+            "bulk_ingest_reference_resumes",
+            "email_compose",
+        ],
+    }
+
+
+@app.get("/api/tooling/status", response_model=ToolStatusResponse)
+def tooling_status() -> ToolStatusResponse:
+    return ToolStatusResponse(
+        gemini_configured=bool(settings.gemini_api_key),
+        qdrant_configured=settings.has_qdrant_config,
+        r2_configured=settings.has_s3_config,
+        mcp_url=settings.mcp_server_base_url,
+    )
+
+
+@app.post("/api/upload", response_model=UploadResponse)
+async def upload_resume(
+    file: UploadFile = File(...),
+    session_id: str | None = Query(default=None),
+) -> UploadResponse:
+    file_name = file.filename or "resume.pdf"
+    if not file_name.lower().endswith(".pdf"):
+        raise HTTPException(status_code=400, detail="Only PDF files are supported in this endpoint.")
+
+    file_bytes = await file.read()
+    if not file_bytes:
+        raise HTTPException(status_code=400, detail="Uploaded file is empty.")
+
+    save_path = Path(settings.uploads_dir) / file_name
+    save_path.write_bytes(file_bytes)
+
+    with SessionLocal() as db:
+        result = ingestion_service.ingest_pdf(
+            db,
+            file_name=file_name,
+            file_bytes=file_bytes,
+        )
+
+    _remember_upload(session_id, result.candidate_id, result.file_name)
+
+    return UploadResponse(
+        candidate_id=result.candidate_id,
+        file_name=result.file_name,
+        chunks_indexed=result.chunks_indexed,
+        r2_url=result.r2_url,
+        message="Resume ingested successfully.",
+    )
+
+
+@app.post("/api/bootstrap/reference-resumes")
+def bootstrap_reference_resumes(
+    limit: int = Query(default=20, ge=1, le=200),
+    source_dir: str | None = Query(default=None),
+    force_reingest: bool = Query(default=False),
+) -> dict:
+    summary = ingest_reference_resumes(
+        limit=limit,
+        source_dir=source_dir,
+        force_reingest=force_reingest,
+    )
+
+    return {
+        "status": "success",
+        "source_dir": summary.source_dir,
+        "requested_limit": summary.requested_limit,
+        "files_seen": summary.files_seen,
+        "ingested": summary.ingested,
+        "skipped": summary.skipped,
+        "failed": summary.failed,
+        "failures": summary.failures,
+    }
+
+
+@app.post("/api/bootstrap/sync-reference-resumes")
+def sync_reference_resumes(
+    max_files: int = Query(default=120, ge=1, le=1000),
+    source_dir: str | None = Query(default=None),
+) -> dict:
+    result = sync_reference_resumes_to_local(max_files=max_files, source_dir=source_dir)
+    return {
+        "status": "success",
+        **result,
+    }
+
+
+def _collect_tool_ui(tool_calls: list[dict]) -> dict:
+    """Merge UI payloads from MCP tool responses (cards, summary, chart, markdown, tabs)."""
+    merged: dict = {}
+    cards: list = []
+    for call in tool_calls:
+        response = call.get("response") or {}
+        ui = response.get("ui") if isinstance(response, dict) else None
+        if not isinstance(ui, dict):
+            continue
+
+        for key in ("summary", "c1_response", "chart", "table", "markdown", "tabs"):
+            value = ui.get(key)
+            if value and not merged.get(key):
+                merged[key] = value
+
+        ui_cards = ui.get("cards")
+        if isinstance(ui_cards, list):
+            cards.extend(ui_cards)
+
+    if cards:
+        merged["cards"] = cards
+    return merged
+
+
+def _handle_action_command(command: str, target_id: str) -> tuple[str, dict | None]:
+    """Resolve card actions like ``open_profile:<id>`` without invoking the LLM."""
+    if command == "open_profile" or command == "details":
+        with SessionLocal() as db:
+            candidate = candidate_service.get_candidate(db, target_id)
+            if candidate is None:
+                return (
+                    f"I could not find a candidate with id `{target_id}`.",
+                    None,
+                )
+            payload_json = candidate_service.build_profile_payload(candidate)
+        return payload_json["summary"], payload_json
+
+    if command == "shortlist":
+        with SessionLocal() as db:
+            candidate = candidate_service.get_candidate(db, target_id)
+            if candidate is None:
+                return f"Could not shortlist: candidate `{target_id}` not found.", None
+            payload_json = candidate_service.build_profile_payload(candidate)
+        message = (
+            f"Shortlisted **{candidate.full_name or candidate.external_id}** "
+            f"(id `{candidate.external_id}`). Track them in the application stages tool."
+        )
+        payload_json["summary"] = message
+        return message, payload_json
+
+    if command in {"publish_job_posting", "edit_job_posting"}:
+        verb = "publish" if command == "publish_job_posting" else "edit"
+        return (
+            f"Job posting `{target_id}` queued to {verb}. "
+            "Open the job postings file under backend/data to confirm.",
+            None,
+        )
+
+    return "", None
+
+
+@app.post("/api/chat")
+async def chat_stream(payload: ChatRequest) -> StreamingResponse:
+    async def event_generator():
+        try:
+            with SessionLocal() as db:
+                candidate_service.audit_query(
+                    db,
+                    session_id=payload.session_id,
+                    query=payload.message,
+                    top_k=payload.top_k,
+                )
+
+            # If the user's message contains a demonstrative pointer to the most recent
+            # upload ("this pdf", "the candidate", "their resume", etc.) and we have a
+            # recorded upload for this session, short-circuit to the profile lookup so
+            # the agent never has to guess at the candidate id.
+            action = parse_action_command(payload.message)
+            if action is None:
+                lowered = payload.message.lower()
+                pdf_phrases = (
+                    "this pdf",
+                    "the pdf",
+                    "this resume",
+                    "the resume",
+                    "this file",
+                    "the file",
+                    "uploaded pdf",
+                    "uploaded resume",
+                    "uploaded file",
+                    "this candidate",
+                    "the candidate",
+                    "this person",
+                    "the person",
+                    "this applicant",
+                    "the applicant",
+                    "this profile",
+                    "the profile",
+                    "their resume",
+                    "their profile",
+                    "their experience",
+                    "his resume",
+                    "her resume",
+                    "his profile",
+                    "her profile",
+                    "about him",
+                    "about her",
+                    "about them",
+                )
+                recent = _session_recent_uploads.get(payload.session_id) if payload.session_id else None
+                if recent and any(phrase in lowered for phrase in pdf_phrases):
+                    action = ("open_profile", recent["candidate_id"])
+
+            if action is not None:
+                command, target_id = action
+                yield format_sse("status", {"message": f"Resolving {command} action"})
+                final_text, action_payload = _handle_action_command(command, target_id)
+                for token in chunk_text_for_stream(final_text):
+                    yield format_sse("token", {"delta": token})
+                if action_payload is None:
+                    action_payload = {}
+                # Drop any c1_response — the Thesys SDK rejects hand-rolled XML and
+                # shows a red 'Error while generating response' message. The card +
+                # markdown pipeline already renders the response correctly.
+                action_payload.pop("c1_response", None)
+                action_payload.pop("c1Response", None)
+                if not action_payload.get("summary"):
+                    action_payload["summary"] = final_text
+                yield format_sse("genui", action_payload)
+                yield format_sse("done", {"message": final_text})
+                return
+
+            yield format_sse("status", {"message": "Running ADK recruitment agent"})
+
+            agent_message = payload.message
+            upload_hint = _build_session_upload_hint(payload.session_id)
+            if upload_hint:
+                agent_message = payload.message + upload_hint
+
+            turn = await runtime.run_turn_detailed(
+                message=agent_message,
+                user_id=payload.user_id,
+                session_id=payload.session_id,
+            )
+            final_text = turn.text or "I could not produce a response. Please retry with more detail."
+
+            for token in chunk_text_for_stream(final_text):
+                yield format_sse("token", {"delta": token})
+
+            payload_json = extract_json_object(final_text)
+
+            # Promote MCP tool UI payloads (e.g. job posting, interview invite) so the
+            # frontend can render rich Thesys C1 / cards even when the agent only emits
+            # plain markdown text.
+            tool_ui = _collect_tool_ui(turn.tool_calls)
+            if tool_ui:
+                if payload_json is None:
+                    payload_json = {}
+                for key, value in tool_ui.items():
+                    if value and not payload_json.get(key):
+                        payload_json[key] = value
+            # Run the candidate-search fallback when the user's message clearly asks for
+            # a search AND we don't already have cards. The semantic search tool always
+            # returns a `ui` block (even with empty cards), so we can't just check
+            # `payload_json is None` — we have to look at whether actual cards were
+            # produced.
+            existing_cards = (payload_json or {}).get("cards") if isinstance(payload_json, dict) else None
+            cards_empty = not existing_cards
+            if cards_empty and looks_like_candidate_search(payload.message):
+                fallback_payload: dict | None = None
+                rows = search_service.semantic_search(query=payload.message, top_k=payload.top_k)
+                if rows:
+                    fallback_payload = search_service.build_genui_payload(payload.message, rows)
+                else:
+                    with SessionLocal() as db:
+                        local_matches = candidate_service.search_candidates(
+                            db,
+                            query=payload.message,
+                            limit=payload.top_k,
+                        )
+                    if local_matches:
+                        fallback_payload = candidate_service.build_genui_payload(
+                            payload.message,
+                            local_matches,
+                        )
+
+                if fallback_payload:
+                    if payload_json is None:
+                        payload_json = fallback_payload
+                    else:
+                        for key, value in fallback_payload.items():
+                            # Overwrite anything from the agent's empty tool response.
+                            if value:
+                                payload_json[key] = value
+                    # Replace the agent's "no results" final text with our fallback summary
+                    # so the bubble matches the cards we surface.
+                    fb_summary = fallback_payload.get("summary")
+                    if isinstance(fb_summary, str) and fb_summary.strip():
+                        final_text = fb_summary
+
+            if payload_json is None:
+                payload_json = {}
+
+            # Strip any c1_response — Thesys C1Component shows 'Error while generating
+            # response' when handed XML it didn't generate itself. The markdown + cards
+            # + chart pipeline below already provides the interactive UI.
+            payload_json.pop("c1_response", None)
+            payload_json.pop("c1Response", None)
+
+            if payload_json and not payload_json.get("summary"):
+                payload_json["summary"] = final_text
+
+            yield format_sse("genui", payload_json)
+
+            done_message = final_text
+            summary = payload_json.get("summary") if isinstance(payload_json, dict) else None
+            if isinstance(summary, str) and summary.strip():
+                done_message = summary.strip()
+
+            yield format_sse("done", {"message": done_message})
+        except asyncio.CancelledError as exc:  # pragma: no cover
+            logger.exception("Chat stream cancelled")
+            yield format_sse("error", {"message": f"Agent run cancelled: {exc}"})
+        except Exception as exc:  # pragma: no cover
+            logger.exception("Chat stream failed")
+            yield format_sse("error", {"message": str(exc)})
+
+    return StreamingResponse(event_generator(), media_type="text/event-stream")
+
+
+@app.get("/api/candidates/{candidate_id}")
+def get_candidate_detail(candidate_id: str) -> dict:
+    with SessionLocal() as db:
+        candidate = candidate_service.get_candidate(db, candidate_id)
+        if candidate is None:
+            raise HTTPException(status_code=404, detail="Candidate not found.")
+        payload_json = candidate_service.build_profile_payload(candidate)
+
+    return {
+        "status": "success",
+        "candidate_id": candidate.external_id,
+        "profile": payload_json,
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run("main:app", host=settings.host, port=settings.port, reload=False)

backend/mcp_server/__init__.py

@@ -0,0 +1 @@
+"""MCP server package exposing recruitment tools."""

backend/mcp_server/router.py

@@ -0,0 +1,43 @@
+"""Modular MCP tool router for the recruitment backend."""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from fastmcp import FastMCP
+
+from mcp_server.tools.application_status import register as register_application_status
+from mcp_server.tools.candidate_query import register as register_candidate_query
+from mcp_server.tools.email_compose import register as register_email_compose
+from mcp_server.tools.interview_records import register as register_interview_records
+from mcp_server.tools.job_posting import register as register_job_posting
+from mcp_server.tools.job_matching import register as register_job_matching
+from mcp_server.tools.pdf_ingest import register as register_pdf_ingest
+from mcp_server.tools.policy_info import register as register_policy_info
+from mcp_server.tools.reference_resumes import register as register_reference_resumes
+from mcp_server.tools.vector_search import register as register_vector_search
+
+Registrar = Callable[[FastMCP], None]
+
+
+def _safe_register(mcp: FastMCP, registrar: Registrar, name: str) -> None:
+    try:
+        registrar(mcp)
+    except Exception as exc:  # pragma: no cover
+        print(f"Failed to register {name}: {exc}")
+
+
+def register_tools(mcp: FastMCP) -> None:
+    for name, registrar in (
+        ("ingest_resume_pdf", register_pdf_ingest),
+        ("semantic_candidate_search", register_vector_search),
+        ("candidate_metadata_query", register_candidate_query),
+        ("compute_job_match_score", register_job_matching),
+        ("get_policy_info", register_policy_info),
+        ("manage_application_status", register_application_status),
+        ("manage_interview_records", register_interview_records),
+        ("generate_job_posting", register_job_posting),
+        ("bulk_ingest_reference_resumes", register_reference_resumes),
+        ("email_compose", register_email_compose),
+    ):
+        _safe_register(mcp, registrar, name)

backend/mcp_server/server.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.responses import Response
+from starlette.applications import Starlette
+import uvicorn
+from starlette.routing import Mount, Route
+
+from core.config import get_settings
+from mcp_server.router import register_tools
+
+settings = get_settings()
+
+mcp = FastMCP("RecruitmentMCP")
+register_tools(mcp)
+
+transport = SseServerTransport("/messages/")
+
+
+async def sse_endpoint(request):
+    async with transport.connect_sse(request.scope, request.receive, request._send) as streams:
+        await mcp._mcp_server.run(
+            streams[0],
+            streams[1],
+            mcp._mcp_server.create_initialization_options(),
+        )
+    # Return a concrete response after client disconnect to avoid NoneType route errors.
+    return Response(status_code=204)
+
+
+mcp_app = Starlette(
+    routes=[
+        Route("/sse", endpoint=sse_endpoint),
+        Mount("/messages/", app=transport.handle_post_message),
+    ]
+)
+
+app = FastAPI(title="Recruitment MCP Server")
+app.mount("/mcp-server", mcp_app)
+
+for target in (app, mcp_app):
+    target.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origin_list,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+
+@app.get("/mcp-health")
+def mcp_health() -> dict:
+    return {
+        "ok": True,
+        "mcp_endpoint": "/mcp-server/sse",
+        "tools": [
+            "ingest_resume_pdf",
+            "semantic_candidate_search",
+            "candidate_metadata_query",
+            "compute_job_match_score",
+            "get_policy_info",
+            "manage_application_status",
+            "manage_interview_records",
+            "generate_job_posting",
+            "bulk_ingest_reference_resumes",
+        ],
+    }
+
+
+if __name__ == "__main__":
+    uvicorn.run("mcp_server.server:app", host=settings.host, port=9000, reload=False)

backend/mcp_server/tools/__init__.py

@@ -0,0 +1 @@
+"""Recruitment MCP tool modules."""

backend/mcp_server/tools/application_status.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+from fastmcp import FastMCP
+from sqlalchemy import select
+
+from core.db import SessionLocal
+from core.models import ApplicationStatus
+
+DEFAULT_STAGES = [
+    "Applied",
+    "Screening",
+    "Shortlisted",
+    "Interview Scheduled",
+    "Technical Round",
+    "Final Interview",
+    "Offered",
+    "Hired",
+    "Rejected",
+]
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def manage_application_status(
+        mode: str,
+        candidate_id: str | None = None,
+        candidate_name: str | None = None,
+        role_applied: str | None = None,
+        stage: str | None = None,
+        status: str | None = None,
+        notes: str | None = None,
+    ) -> dict:
+        """Create, update, and retrieve application statuses for candidates."""
+        normalized_mode = mode.strip().lower()
+
+        with SessionLocal() as db:
+            if normalized_mode in {"upsert", "update"}:
+                if not candidate_id:
+                    return {"status": "error", "message": "candidate_id is required for upsert."}
+
+                existing = db.execute(
+                    select(ApplicationStatus).where(ApplicationStatus.candidate_id == candidate_id)
+                ).scalar_one_or_none()
+
+                if existing is None:
+                    existing = ApplicationStatus(candidate_id=candidate_id)
+                    db.add(existing)
+
+                if candidate_name is not None:
+                    existing.candidate_name = candidate_name
+                if role_applied is not None:
+                    existing.role_applied = role_applied
+                if stage is not None:
+                    existing.stage = stage
+                if status is not None:
+                    existing.status = status
+                if notes is not None:
+                    existing.notes = notes
+
+                db.commit()
+                db.refresh(existing)
+                return {
+                    "status": "success",
+                    "message": "Application status upserted.",
+                    "record": {
+                        "candidate_id": existing.candidate_id,
+                        "candidate_name": existing.candidate_name,
+                        "role_applied": existing.role_applied,
+                        "stage": existing.stage,
+                        "status_text": existing.status,
+                        "notes": existing.notes,
+                    },
+                }
+
+            if normalized_mode == "advance":
+                if not candidate_id:
+                    return {"status": "error", "message": "candidate_id is required to advance stage."}
+
+                existing = db.execute(
+                    select(ApplicationStatus).where(ApplicationStatus.candidate_id == candidate_id)
+                ).scalar_one_or_none()
+                if existing is None:
+                    return {"status": "not_found", "message": "Candidate application not found."}
+
+                current_stage = existing.stage or "Applied"
+                if current_stage not in DEFAULT_STAGES:
+                    existing.stage = "Applied"
+                else:
+                    idx = DEFAULT_STAGES.index(current_stage)
+                    next_idx = min(idx + 1, len(DEFAULT_STAGES) - 1)
+                    existing.stage = DEFAULT_STAGES[next_idx]
+
+                if notes:
+                    existing.notes = notes
+
+                db.commit()
+                db.refresh(existing)
+                return {
+                    "status": "success",
+                    "message": "Application stage advanced.",
+                    "record": {
+                        "candidate_id": existing.candidate_id,
+                        "stage": existing.stage,
+                        "status_text": existing.status,
+                        "notes": existing.notes,
+                    },
+                }
+
+            if normalized_mode == "get":
+                if not candidate_id:
+                    return {"status": "error", "message": "candidate_id is required for get."}
+
+                existing = db.execute(
+                    select(ApplicationStatus).where(ApplicationStatus.candidate_id == candidate_id)
+                ).scalar_one_or_none()
+                if existing is None:
+                    return {"status": "not_found", "message": "Candidate application not found."}
+
+                return {
+                    "status": "success",
+                    "record": {
+                        "candidate_id": existing.candidate_id,
+                        "candidate_name": existing.candidate_name,
+                        "role_applied": existing.role_applied,
+                        "stage": existing.stage,
+                        "status_text": existing.status,
+                        "notes": existing.notes,
+                    },
+                }
+
+            if normalized_mode == "list":
+                rows = db.execute(
+                    select(ApplicationStatus).order_by(ApplicationStatus.updated_at.desc()).limit(50)
+                ).scalars().all()
+
+                records = [
+                    {
+                        "candidate_id": row.candidate_id,
+                        "candidate_name": row.candidate_name,
+                        "role_applied": row.role_applied,
+                        "stage": row.stage,
+                        "status_text": row.status,
+                    }
+                    for row in rows
+                ]
+                return {
+                    "status": "success",
+                    "count": len(records),
+                    "records": records,
+                }
+
+            return {
+                "status": "error",
+                "message": "Unsupported mode. Use upsert, update, advance, get, or list.",
+            }

backend/mcp_server/tools/candidate_query.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from core.db import SessionLocal
+from services.candidate_service import CandidateService
+
+
+def register(mcp: FastMCP) -> None:
+    candidate_service = CandidateService()
+
+    @mcp.tool()
+    def candidate_metadata_query(query: str, limit: int = 10) -> dict:
+        """Query candidate metadata from SQLite using keyword matching."""
+        with SessionLocal() as db:
+            rows = candidate_service.search_candidates(db=db, query=query, limit=limit)
+
+        if not rows:
+            return {
+                "status": "no_results",
+                "message": "No metadata matches found in SQLite.",
+                "results": [],
+            }
+
+        ui_payload = candidate_service.build_genui_payload(query=query, candidates=rows)
+        return {
+            "status": "success",
+            "count": len(ui_payload.get("cards") or []),
+            "results": ui_payload.get("cards") or [],
+            "ui": ui_payload,
+        }

backend/mcp_server/tools/email_compose.py

@@ -0,0 +1,243 @@
+"""Email drafting + sending MCP tool.
+
+Two modes:
+  * ``mode="draft"`` — given a free-form natural-language brief, returns three
+    tonal variants (formal / casual / polite) that the user can pick from.
+  * ``mode="send"`` — given a final subject + body + recipient(s), delivers the
+    email through the configured SMTP relay (reusing the same settings as the
+    interview-invite flow).
+
+The 3 tone variants are produced by Gemini using the project's ``GEMINI_API_KEY``.
+If Gemini isn't reachable we fall back to deterministic template wrappers so the
+flow still works for demos.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+
+from fastmcp import FastMCP
+
+from core.config import get_settings
+from services.notification_service import send_plain_email
+
+logger = logging.getLogger(__name__)
+
+_TONES: tuple[tuple[str, str], ...] = (
+    ("formal", "Polished, business-formal tone. No contractions. Address the recipient with their full name or title."),
+    ("casual", "Warm, conversational tone. First-name basis. Light contractions allowed but stay professional."),
+    ("polite", "Courteous, considerate, and explicit about respect for the recipient's time. Slightly more formal than casual but warmer than 'formal'."),
+)
+
+
+def _strip_code_fences(text: str) -> str:
+    fence = re.search(r"```(?:json)?\s*(\{[\s\S]*\})\s*```", text)
+    if fence:
+        return fence.group(1)
+    return text.strip()
+
+
+def _gemini_draft(brief: str, tone_label: str, tone_guide: str, recipient_name: str | None) -> dict:
+    """Ask Gemini to produce a single subject + body for the given tone."""
+    settings = get_settings()
+    if not settings.gemini_api_key:
+        raise RuntimeError("GEMINI_API_KEY not configured.")
+
+    from google import genai
+
+    client = genai.Client(api_key=settings.gemini_api_key)
+
+    addressee = recipient_name or "the recipient"
+    prompt = (
+        f"You are drafting a professional email on behalf of a recruiter. Use the "
+        f"{tone_label} tone described below.\n\n"
+        f"TONE GUIDE: {tone_guide}\n\n"
+        f"USER BRIEF (what the email is about):\n{brief}\n\n"
+        f"Addressee placeholder: {addressee}\n\n"
+        "Return strictly valid JSON with two keys:\n"
+        '  {"subject": "...", "body": "..."}\n'
+        "The body must end with a sign-off (best regards / thanks / etc.) on its own line."
+    )
+
+    response = client.models.generate_content(
+        model=settings.gemini_model or "gemini-2.5-pro",
+        contents=[prompt],
+    )
+    raw_text = (getattr(response, "text", None) or "").strip()
+    if not raw_text:
+        raise RuntimeError("Gemini returned an empty response.")
+
+    cleaned = _strip_code_fences(raw_text)
+    data = json.loads(cleaned)
+    if not isinstance(data, dict) or "subject" not in data or "body" not in data:
+        raise RuntimeError("Gemini response missing subject/body keys.")
+    return {"subject": str(data["subject"]).strip(), "body": str(data["body"]).strip()}
+
+
+def _fallback_draft(brief: str, tone_label: str, recipient_name: str | None) -> dict:
+    name = recipient_name or "there"
+    if tone_label == "formal":
+        opener = f"Dear {name},"
+        closer = "Best regards,\nRecruitment OS"
+    elif tone_label == "casual":
+        opener = f"Hi {name.split()[0] if recipient_name else 'there'},"
+        closer = "Cheers,\nRecruitment OS"
+    else:
+        opener = f"Hello {name},"
+        closer = "Thank you for your time,\nRecruitment OS"
+    subject = brief.strip().split("\n")[0][:90] or "Following up"
+    body = f"{opener}\n\n{brief.strip()}\n\n{closer}"
+    return {"subject": subject, "body": body}
+
+
+def _build_drafts(brief: str, recipient_name: str | None) -> list[dict]:
+    drafts: list[dict] = []
+    for tone_label, tone_guide in _TONES:
+        try:
+            drafted = _gemini_draft(brief, tone_label, tone_guide, recipient_name)
+        except Exception as exc:
+            logger.warning("Gemini email draft failed for tone=%s: %s", tone_label, exc)
+            drafted = _fallback_draft(brief, tone_label, recipient_name)
+        drafts.append(
+            {
+                "tone": tone_label,
+                "subject": drafted["subject"],
+                "body": drafted["body"],
+            }
+        )
+    return drafts
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def email_compose(
+        mode: str,
+        brief: str | None = None,
+        recipient_name: str | None = None,
+        recipient_email: str | None = None,
+        cc: str | None = None,
+        subject: str | None = None,
+        body: str | None = None,
+        tone: str | None = None,
+    ) -> dict:
+        """Draft or send recruiter emails.
+
+        ``mode="draft"`` requires ``brief``. Returns three tone variants
+        (formal / casual / polite) that the user can choose from.
+
+        ``mode="send"`` requires ``recipient_email`` (comma-separated allowed),
+        ``subject`` and ``body`` and delivers the message via SMTP.
+        """
+        normalized = (mode or "").strip().lower()
+
+        if normalized == "draft":
+            text = (brief or "").strip()
+            if not text:
+                return {
+                    "status": "error",
+                    "message": "brief is required when mode='draft'.",
+                }
+
+            drafts = _build_drafts(text, recipient_name)
+
+            cards = []
+            for draft in drafts:
+                preview = draft["body"][:200] + ("…" if len(draft["body"]) > 200 else "")
+                cards.append(
+                    {
+                        "title": f"{draft['tone'].title()} draft",
+                        "subtitle": f"Subject: {draft['subject']}",
+                        "tags": [draft["tone"].title()],
+                        "meta": {"preview": preview},
+                        "actions": [
+                            {
+                                "label": f"Use {draft['tone']} tone",
+                                "action": (
+                                    f"Use the {draft['tone']} tone draft. "
+                                    "What's the recipient's email address?"
+                                ),
+                            }
+                        ],
+                    }
+                )
+
+            markdown_sections = [f"# Email drafts for: {text[:90]}\n"]
+            for draft in drafts:
+                markdown_sections.append(
+                    f"## {draft['tone'].title()} tone\n"
+                    f"**Subject:** {draft['subject']}\n\n"
+                    f"{draft['body']}\n"
+                )
+            markdown_body = "\n---\n".join(markdown_sections)
+
+            return {
+                "status": "success",
+                "drafts": drafts,
+                "ui": {
+                    "summary": (
+                        "Three tone variants ready. Reply with your choice — "
+                        "'use formal', 'use casual', or 'use polite' — and the "
+                        "recipient email to send."
+                    ),
+                    "cards": cards,
+                    "markdown": markdown_body,
+                },
+            }
+
+        if normalized == "send":
+            if not recipient_email or not subject or not body:
+                return {
+                    "status": "error",
+                    "message": "recipient_email, subject, and body are required when mode='send'.",
+                }
+
+            to_list = [addr.strip() for addr in recipient_email.split(",") if addr.strip()]
+            cc_list = [addr.strip() for addr in (cc or "").split(",") if addr.strip()]
+
+            result = send_plain_email(
+                to=to_list,
+                subject=subject,
+                body=body,
+                cc=cc_list,
+            )
+
+            tone_label = (tone or "selected").lower()
+            return {
+                "status": "success" if result.sent else "error",
+                "delivery": result.delivery,
+                "message": result.detail,
+                "ui": {
+                    "summary": (
+                        f"Email ({tone_label} tone) {'sent' if result.sent else 'NOT sent'} — "
+                        f"{result.detail}"
+                    ),
+                    "cards": [
+                        {
+                            "title": "Email delivery",
+                            "subtitle": result.detail,
+                            "tags": [
+                                tone_label.title() or "Email",
+                                "Delivered" if result.sent else "Failed",
+                            ],
+                            "meta": {
+                                "to": ", ".join(to_list),
+                                "cc": ", ".join(cc_list) if cc_list else "—",
+                                "subject": subject,
+                            },
+                            "actions": [],
+                        }
+                    ],
+                    "markdown": (
+                        f"# {subject}\n\n"
+                        f"**To:** {', '.join(to_list)}  \n"
+                        f"**Cc:** {', '.join(cc_list) if cc_list else '—'}\n\n"
+                        f"{body}"
+                    ),
+                },
+            }
+
+        return {
+            "status": "error",
+            "message": "mode must be 'draft' or 'send'.",
+        }

backend/mcp_server/tools/interview_records.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import base64
+import urllib.parse
+from datetime import datetime, timedelta
+
+from fastmcp import FastMCP
+from sqlalchemy import select
+
+from core.db import SessionLocal
+from core.models import InterviewRecord
+from services.notification_service import generate_meet_url, send_interview_invite
+
+VALID_STATUSES = {"Scheduled", "Completed", "Cancelled", "Rescheduled"}
+
+
+def _parse_datetime(date_str: str, time_str: str | None = None) -> datetime:
+    if not date_str:
+        raise ValueError("date is required.")
+
+    t = (time_str or "09:00").strip()
+    if any(token in t.lower() for token in ("am", "pm")):
+        return datetime.strptime(f"{date_str} {t}", "%Y-%m-%d %I:%M %p")
+    return datetime.strptime(f"{date_str} {t}", "%Y-%m-%d %H:%M")
+
+
+def _format_for_calendar(dt: datetime) -> str:
+    return dt.strftime("%Y%m%dT%H%M%S")
+
+
+def _build_invite_artifacts(
+    *,
+    candidate_name: str,
+    candidate_email: str,
+    interviewer_name: str,
+    interviewer_email: str,
+    interview_round: str,
+    scheduled_on: datetime,
+    end_time: datetime,
+    notes: str | None,
+    meet_url: str,
+) -> dict:
+    """Generate Google Calendar URL, ICS payload (with Jitsi link), and mailto fallback."""
+    title = f"{interview_round} interview: {candidate_name}"
+    description_lines = [
+        f"Candidate: {candidate_name} <{candidate_email}>",
+        f"Interviewer: {interviewer_name} <{interviewer_email}>",
+        f"Round: {interview_round}",
+        f"Join: {meet_url}",
+    ]
+    if notes:
+        description_lines.append(f"Notes: {notes}")
+    description = "\n".join(description_lines)
+
+    start_str = _format_for_calendar(scheduled_on)
+    end_str = _format_for_calendar(end_time)
+
+    google_calendar_url = (
+        "https://calendar.google.com/calendar/render?"
+        + urllib.parse.urlencode(
+            {
+                "action": "TEMPLATE",
+                "text": title,
+                "dates": f"{start_str}/{end_str}",
+                "details": description,
+                "location": meet_url,
+                "add": f"{candidate_email},{interviewer_email}",
+            }
+        )
+    )
+
+    ics_lines = [
+        "BEGIN:VCALENDAR",
+        "VERSION:2.0",
+        "PRODID:-//Recruitment OS//Interview//EN",
+        "METHOD:REQUEST",
+        "BEGIN:VEVENT",
+        f"UID:interview-{int(scheduled_on.timestamp())}@recruitment-os",
+        f"DTSTAMP:{_format_for_calendar(datetime.utcnow())}Z",
+        f"DTSTART:{start_str}",
+        f"DTEND:{end_str}",
+        f"SUMMARY:{title}",
+        f"DESCRIPTION:{description.replace(chr(10), chr(92) + 'n')}",
+        f"LOCATION:{meet_url}",
+        f"ORGANIZER;CN={interviewer_name}:mailto:{interviewer_email}",
+        f"ATTENDEE;CN={candidate_name};RSVP=TRUE:mailto:{candidate_email}",
+        f"ATTENDEE;CN={interviewer_name};RSVP=TRUE:mailto:{interviewer_email}",
+        "STATUS:CONFIRMED",
+        "END:VEVENT",
+        "END:VCALENDAR",
+    ]
+    ics_content = "\r\n".join(ics_lines)
+    ics_data_url = "data:text/calendar;base64," + base64.b64encode(ics_content.encode("utf-8")).decode("ascii")
+
+    mail_body = (
+        f"Hi {candidate_name.split()[0] if candidate_name else 'there'},%0D%0A%0D%0A"
+        f"Your {interview_round} interview with {interviewer_name} is on "
+        f"{scheduled_on.strftime('%A, %d %B %Y')} at {scheduled_on.strftime('%I:%M %p')}.%0D%0A%0D%0A"
+        f"Join here: {urllib.parse.quote(meet_url)}%0D%0A%0D%0A"
+        "Reply to this email if you need to reschedule.%0D%0A%0D%0A"
+        "— Recruitment OS"
+    )
+    mailto_url = (
+        f"mailto:{candidate_email}?cc={urllib.parse.quote(interviewer_email)}"
+        f"&subject={urllib.parse.quote(title)}&body={mail_body}"
+    )
+
+    return {
+        "google_calendar_url": google_calendar_url,
+        "ics_data_url": ics_data_url,
+        "ics_content": ics_content,
+        "mailto_url": mailto_url,
+        "meet_url": meet_url,
+        "title": title,
+        "description": description,
+        "starts_at": scheduled_on.isoformat(sep=" ", timespec="minutes"),
+        "ends_at": end_time.isoformat(sep=" ", timespec="minutes"),
+    }
+
+
+def _build_interview_c1(
+    invite: dict,
+    interview_id: int,
+    delivery_channel: str,
+    auto_sent: bool,
+    candidate_name: str,
+    candidate_email: str,
+    interviewer_name: str,
+    interviewer_email: str,
+    interview_round: str,
+) -> str:
+    """Build a Thesys C1 payload using <custom_markdown> (the schema-stable wrapper)."""
+    delivery_text = (
+        f"✅ Auto-emailed via {delivery_channel}. Invite, `.ics` file, and Google Meet "
+        "link were sent to both attendees."
+        if auto_sent
+        else (
+            "⚠️ SMTP is not configured yet, so no email was sent. Set `SMTP_HOST`, "
+            "`SMTP_USER`, `SMTP_PASSWORD`, and `SMTP_FROM` in `.env` to enable auto-send."
+        )
+    )
+
+    markdown_body = (
+        f"# {invite['title']}\n\n"
+        f"**When:** {invite['starts_at']} → {invite['ends_at']}  \n"
+        f"**Interview ID:** `{interview_id}`  \n"
+        f"**Round:** {interview_round}\n\n"
+        "### Attendees\n"
+        f"- **Candidate:** {candidate_name} ({candidate_email})\n"
+        f"- **Interviewer:** {interviewer_name} ({interviewer_email})\n\n"
+        "### Meeting\n"
+        f"[Join Google Meet]({invite['meet_url']})\n\n"
+        f"### Delivery\n{delivery_text}\n\n"
+        f"[Add to Google Calendar]({invite['google_calendar_url']}) · "
+        f"[Download .ics]({invite['ics_data_url']}) · "
+        f"[Email both attendees]({invite['mailto_url']})"
+    )
+    safe_md = (
+        markdown_body.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    )
+    return f"<content><custom_markdown>{safe_md}</custom_markdown></content>"
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def manage_interview_records(
+        mode: str,
+        interview_id: int | None = None,
+        candidate_id: str | None = None,
+        candidate_name: str | None = None,
+        candidate_email: str | None = None,
+        interviewer_name: str | None = None,
+        interviewer_email: str | None = None,
+        interview_round: str = "Screening",
+        date: str | None = None,
+        time: str | None = None,
+        duration_minutes: int = 60,
+        status: str | None = None,
+        meeting_link: str | None = None,
+        notes: str | None = None,
+    ) -> dict:
+        """Schedule, update, and list interview records in local SQLite."""
+        normalized_mode = mode.strip().lower()
+
+        with SessionLocal() as db:
+            if normalized_mode in {"schedule", "insert"}:
+                if not all([candidate_name, candidate_email, interviewer_name, interviewer_email, date]):
+                    return {
+                        "status": "error",
+                        "message": "candidate_name, candidate_email, interviewer_name, interviewer_email, and date are required.",
+                    }
+
+                scheduled_on = _parse_datetime(date, time)
+                end_time = scheduled_on + timedelta(minutes=max(15, duration_minutes))
+
+                meet_url = meeting_link or generate_meet_url()
+
+                record = InterviewRecord(
+                    candidate_id=candidate_id,
+                    candidate_name=candidate_name,
+                    candidate_email=candidate_email,
+                    interviewer_name=interviewer_name,
+                    interviewer_email=interviewer_email,
+                    interview_round=interview_round,
+                    scheduled_on=scheduled_on,
+                    end_time=end_time,
+                    duration_minutes=max(15, duration_minutes),
+                    status=status or "Scheduled",
+                    meeting_link=meet_url,
+                    notes=notes,
+                )
+                db.add(record)
+                db.commit()
+                db.refresh(record)
+
+                invite = _build_invite_artifacts(
+                    candidate_name=candidate_name,
+                    candidate_email=candidate_email,
+                    interviewer_name=interviewer_name,
+                    interviewer_email=interviewer_email,
+                    interview_round=interview_round,
+                    scheduled_on=scheduled_on,
+                    end_time=end_time,
+                    notes=notes,
+                    meet_url=meet_url,
+                )
+
+                send_result = send_interview_invite(
+                    candidate_name=candidate_name,
+                    candidate_email=candidate_email,
+                    interviewer_name=interviewer_name,
+                    interviewer_email=interviewer_email,
+                    interview_round=interview_round,
+                    scheduled_on=scheduled_on,
+                    end_time=end_time,
+                    notes=notes,
+                    ics_content=invite["ics_content"],
+                    meet_url=meet_url,
+                )
+
+                if send_result.sent:
+                    delivery_line = (
+                        f"Email + .ics + Google Meet link auto-sent to "
+                        f"{', '.join(send_result.recipients)}."
+                    )
+                else:
+                    delivery_line = send_result.detail
+
+                summary = (
+                    f"Scheduled **{interview_round}** interview for **{candidate_name}** with "
+                    f"**{interviewer_name}** on {scheduled_on.strftime('%A, %d %B %Y at %I:%M %p')}. "
+                    f"Meet link: {meet_url}\n\n{delivery_line}"
+                )
+                cards = [
+                    {
+                        "title": invite["title"],
+                        "subtitle": f"{invite['starts_at']} → {invite['ends_at']}",
+                        "tags": [interview_round, "Auto-emailed" if send_result.sent else "Manual send"],
+                        "meta": {
+                            "interview_id": record.id,
+                            "candidate_email": candidate_email,
+                            "interviewer_email": interviewer_email,
+                            "meet_url": meet_url,
+                        },
+                        "actions": [
+                            {"label": "Join meeting", "action": meet_url},
+                            {"label": "Add to Google Calendar", "action": invite["google_calendar_url"]},
+                        ],
+                    }
+                ]
+                return {
+                    "status": "success",
+                    "message": "Interview scheduled successfully.",
+                    "interview_id": record.id,
+                    "invite": invite,
+                    "delivery": {
+                        "sent": send_result.sent,
+                        "channel": send_result.delivery,
+                        "detail": send_result.detail,
+                        "recipients": send_result.recipients,
+                    },
+                    "ui": {
+                        "summary": summary,
+                        "cards": cards,
+                        "c1_response": _build_interview_c1(
+                            invite,
+                            record.id,
+                            send_result.delivery,
+                            send_result.sent,
+                            candidate_name,
+                            candidate_email,
+                            interviewer_name,
+                            interviewer_email,
+                            interview_round,
+                        ),
+                    },
+                }
+
+            if normalized_mode in {"reschedule", "update"}:
+                if not interview_id:
+                    return {"status": "error", "message": "interview_id is required for update."}
+
+                record = db.execute(
+                    select(InterviewRecord).where(InterviewRecord.id == interview_id)
+                ).scalar_one_or_none()
+                if record is None:
+                    return {"status": "not_found", "message": "Interview record not found."}
+
+                if date:
+                    scheduled_on = _parse_datetime(date, time)
+                    record.scheduled_on = scheduled_on
+                    record.end_time = scheduled_on + timedelta(minutes=max(15, duration_minutes))
+                    record.duration_minutes = max(15, duration_minutes)
+
+                if status:
+                    if status not in VALID_STATUSES:
+                        return {
+                            "status": "error",
+                            "message": f"Invalid status. Allowed: {', '.join(sorted(VALID_STATUSES))}",
+                        }
+                    record.status = status
+
+                if interviewer_name:
+                    record.interviewer_name = interviewer_name
+                if interviewer_email:
+                    record.interviewer_email = interviewer_email
+                if interview_round:
+                    record.interview_round = interview_round
+                if meeting_link is not None:
+                    record.meeting_link = meeting_link
+                if notes is not None:
+                    record.notes = notes
+
+                db.commit()
+                db.refresh(record)
+                return {
+                    "status": "success",
+                    "message": "Interview updated successfully.",
+                    "interview_id": record.id,
+                }
+
+            if normalized_mode == "get":
+                if not interview_id:
+                    return {"status": "error", "message": "interview_id is required for get."}
+
+                record = db.execute(
+                    select(InterviewRecord).where(InterviewRecord.id == interview_id)
+                ).scalar_one_or_none()
+                if record is None:
+                    return {"status": "not_found", "message": "Interview record not found."}
+
+                return {
+                    "status": "success",
+                    "record": {
+                        "interview_id": record.id,
+                        "candidate_name": record.candidate_name,
+                        "candidate_email": record.candidate_email,
+                        "interviewer_name": record.interviewer_name,
+                        "interviewer_email": record.interviewer_email,
+                        "interview_round": record.interview_round,
+                        "scheduled_on": record.scheduled_on.isoformat(sep=" ", timespec="seconds"),
+                        "end_time": record.end_time.isoformat(sep=" ", timespec="seconds"),
+                        "status": record.status,
+                        "meeting_link": record.meeting_link,
+                        "notes": record.notes,
+                    },
+                }
+
+            if normalized_mode == "list":
+                rows = db.execute(
+                    select(InterviewRecord).order_by(InterviewRecord.scheduled_on.asc()).limit(100)
+                ).scalars().all()
+
+                records = [
+                    {
+                        "interview_id": row.id,
+                        "candidate_name": row.candidate_name,
+                        "interviewer_name": row.interviewer_name,
+                        "round": row.interview_round,
+                        "scheduled_on": row.scheduled_on.isoformat(sep=" ", timespec="seconds"),
+                        "status": row.status,
+                    }
+                    for row in rows
+                ]
+                return {
+                    "status": "success",
+                    "count": len(records),
+                    "records": records,
+                }
+
+            return {
+                "status": "error",
+                "message": "Unsupported mode. Use schedule, insert, reschedule, update, get, or list.",
+            }

backend/mcp_server/tools/job_matching.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from services.search_service import QdrantSearchService
+
+
+def _normalize_skills(skills_csv: str) -> set[str]:
+    return {token.strip().lower() for token in skills_csv.split(",") if token.strip()}
+
+
+def register(mcp: FastMCP) -> None:
+    search_service = QdrantSearchService()
+
+    @mcp.tool()
+    def compute_job_match_score(
+        job_description: str,
+        required_skills: str = "",
+        min_years_experience: float = 0.0,
+        top_k: int = 5,
+    ) -> dict:
+        """Compute ranked candidate fit scores for a job description."""
+        rows = search_service.semantic_search(query=job_description, top_k=max(top_k * 2, 10))
+        if not rows:
+            return {
+                "status": "no_results",
+                "message": "No candidate vectors found for this job description.",
+                "matches": [],
+            }
+
+        required = _normalize_skills(required_skills)
+        scored = []
+        for row in rows:
+            semantic_score = float(row.get("score") or 0.0)
+            candidate_skills = _normalize_skills(str(row.get("skills") or ""))
+            skill_overlap = (
+                len(required.intersection(candidate_skills)) / len(required)
+                if required
+                else 1.0
+            )
+
+            years_exp = float(row.get("years_experience") or 0.0)
+            experience_factor = 1.0 if years_exp >= min_years_experience else 0.5
+
+            final_score = (semantic_score * 0.6) + (skill_overlap * 0.3) + (experience_factor * 0.1)
+            row_copy = dict(row)
+            row_copy["final_match_score"] = round(final_score, 4)
+            scored.append(row_copy)
+
+        scored.sort(key=lambda item: item["final_match_score"], reverse=True)
+        best = scored[:top_k]
+
+        return {
+            "status": "success",
+            "count": len(best),
+            "matches": best,
+            "ui": search_service.build_genui_payload(query=job_description, rows=best),
+        }

backend/mcp_server/tools/job_posting.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+JOB_POSTINGS_FILE = Path(__file__).resolve().parents[2] / "data" / "job_postings.json"
+
+
+def _parse_years(value: object) -> int:
+    """Parse experience_years which may arrive as int or string ("5-8", "5+")."""
+    if isinstance(value, int):
+        return max(0, value)
+    if isinstance(value, float):
+        return max(0, int(value))
+    if isinstance(value, str):
+        match = re.search(r"\d+", value)
+        if match:
+            return max(0, int(match.group(0)))
+    return 0
+
+
+def _build_posting_text(
+    *,
+    title: str,
+    company: str,
+    location: str,
+    employment_type: str,
+    mode: str,
+    years: int,
+    salary_range: str,
+    skills: list[str],
+) -> str:
+    skill_lines = "\n".join(f"- {skill}" for skill in skills)
+    return (
+        f"# {title}\n\n"
+        f"**Company:** {company}\n"
+        f"**Location:** {location}\n"
+        f"**Type:** {employment_type} | {mode}\n"
+        f"**Experience:** {years}+ years\n"
+        f"**Salary:** {salary_range}\n\n"
+        "---\n\n"
+        "## About the Role\n\n"
+        f"We are hiring a {title} to join {company} in {location}. "
+        f"This {employment_type.lower()} {mode.lower()} role requires "
+        f"approximately {years}+ years of experience.\n\n"
+        "## Key Responsibilities\n\n"
+        "- Design, develop, and ship production-grade features\n"
+        "- Collaborate with product, design, and engineering stakeholders\n"
+        "- Write maintainable, testable, and well-documented code\n"
+        "- Drive code reviews, mentorship, and continuous improvement\n\n"
+        "## Required Skills\n\n"
+        f"{skill_lines}\n"
+        f"- {years}+ years of professional experience\n\n"
+        "## Selection Process\n\n"
+        "1. Resume screening\n"
+        "2. Technical interview\n"
+        "3. Hiring manager discussion\n"
+        "4. Offer\n"
+    )
+
+
+def _persist_posting(record: dict) -> None:
+    JOB_POSTINGS_FILE.parent.mkdir(parents=True, exist_ok=True)
+    existing: list[dict] = []
+    if JOB_POSTINGS_FILE.exists():
+        try:
+            existing = json.loads(JOB_POSTINGS_FILE.read_text(encoding="utf-8"))
+            if not isinstance(existing, list):
+                existing = []
+        except json.JSONDecodeError:
+            existing = []
+    existing.append(record)
+    JOB_POSTINGS_FILE.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def generate_job_posting(
+        title: str,
+        location: str,
+        experience_years: int | str,
+        skills: str,
+        employment_type: str = "Full-time",
+        mode: str = "Hybrid",
+        salary_range: str = "Competitive",
+        company_name: str = "Recruitment OS",
+    ) -> dict:
+        """Draft a structured job posting and persist it under backend/data/job_postings.json.
+
+        Pass ``experience_years`` as an integer or a string range like "5-8" (the lower
+        bound is used). ``skills`` is a comma-separated string.
+        """
+        clean_title = (title or "").strip()
+        clean_location = (location or "").strip()
+        clean_skills = [token.strip() for token in (skills or "").split(",") if token.strip()]
+        years = _parse_years(experience_years)
+
+        if not clean_title or not clean_location or not clean_skills:
+            return {
+                "status": "error",
+                "message": "title, location and comma-separated skills are required.",
+            }
+
+        posting_text = _build_posting_text(
+            title=clean_title,
+            company=company_name,
+            location=clean_location,
+            employment_type=employment_type,
+            mode=mode,
+            years=years,
+            salary_range=salary_range,
+            skills=clean_skills,
+        )
+
+        record = {
+            "job_id": int(time.time() * 1000),
+            "title": clean_title,
+            "company_name": company_name,
+            "location": clean_location,
+            "employment_type": employment_type,
+            "work_mode": mode,
+            "experience_years": years,
+            "salary_range": salary_range,
+            "skills": clean_skills,
+            "posting_text": posting_text,
+            "posted_on": datetime.now(timezone.utc).isoformat(),
+        }
+
+        _persist_posting(record)
+
+        summary = (
+            f"Drafted **{clean_title}** ({employment_type} · {mode}) in {clean_location}. "
+            f"Saved as job id `{record['job_id']}`."
+        )
+
+        skill_chart_data = [
+            {"name": skill, "weight": max(1, len(clean_skills) - idx)}
+            for idx, skill in enumerate(clean_skills)
+        ]
+        skill_chart = {
+            "type": "bar",
+            "title": "Skill weighting",
+            "xKey": "name",
+            "yKey": "weight",
+            "data": skill_chart_data,
+        }
+
+        skills_chips = " ".join(f"`{skill}`" for skill in clean_skills)
+        markdown_body = (
+            f"# {clean_title}\n\n"
+            f"**Company:** {company_name}  \n"
+            f"**Location:** {clean_location}  \n"
+            f"**Type:** {employment_type} · {mode}  \n"
+            f"**Experience:** {years}+ years  \n"
+            f"**Salary:** {salary_range}  \n"
+            f"**Job ID:** `{record['job_id']}`\n\n"
+            "### Required skills\n"
+            f"{skills_chips}\n\n"
+            "### Responsibilities\n"
+            "- Design, develop, and ship production-grade features\n"
+            "- Collaborate with product, design, and engineering stakeholders\n"
+            "- Write maintainable, testable, and well-documented code\n"
+            "- Drive code reviews, mentorship, and continuous improvement\n\n"
+            "### Selection process\n"
+            "1. Resume screening\n"
+            "2. Technical interview\n"
+            "3. Hiring manager discussion\n"
+            "4. Offer\n"
+        )
+        safe_md = (
+            markdown_body.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        )
+        c1_response = f"<content><custom_markdown>{safe_md}</custom_markdown></content>"
+
+        return {
+            "status": "success",
+            "job_posting": record,
+            "ui": {
+                "summary": summary,
+                "cards": [
+                    {
+                        "title": clean_title,
+                        "subtitle": f"{employment_type} | {mode} | {clean_location}",
+                        "tags": clean_skills[:6],
+                        "meta": {
+                            "experience_years": years,
+                            "salary_range": salary_range,
+                        },
+                        "actions": [],
+                    }
+                ],
+                "chart": skill_chart,
+                "markdown": posting_text,
+                "c1_response": c1_response,
+            },
+            "posting_text": posting_text,
+        }

backend/mcp_server/tools/pdf_ingest.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+from core.db import SessionLocal
+from services.ingestion_service import IngestionService
+
+
+def register(mcp: FastMCP) -> None:
+    ingestion_service = IngestionService()
+
+    @mcp.tool()
+    def ingest_resume_pdf(path: str) -> dict:
+        """Ingest a local PDF file into SQLite metadata and Qdrant vectors."""
+        file_path = Path(path).expanduser().resolve()
+        if not file_path.exists():
+            return {"status": "error", "message": f"File does not exist: {file_path}"}
+
+        if file_path.suffix.lower() != ".pdf":
+            return {"status": "error", "message": "Only PDF files are supported."}
+
+        data = file_path.read_bytes()
+
+        with SessionLocal() as db:
+            result = ingestion_service.ingest_pdf(
+                db,
+                file_name=file_path.name,
+                file_bytes=data,
+            )
+
+        return {
+            "status": "success",
+            "candidate_id": result.candidate_id,
+            "file_name": result.file_name,
+            "chunks_indexed": result.chunks_indexed,
+            "r2_url": result.r2_url,
+            "message": "Resume ingested successfully.",
+        }

backend/mcp_server/tools/policy_info.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from fastmcp import FastMCP
+
+POLICY_FILE = Path(__file__).resolve().parents[2] / "data" / "policies.json"
+
+POLICY_ALIASES = {
+    "leave policy": ["leave", "vacation", "holiday", "attendance"],
+    "work from home policy": ["wfh", "remote", "hybrid", "home"],
+    "referral policy": ["referral", "employee referral", "bonus"],
+    "interview policy": ["interview", "panel", "feedback"],
+    "code of conduct": ["conduct", "ethics", "behavior", "harassment"],
+}
+
+
+def _load_policies() -> dict[str, str]:
+    if not POLICY_FILE.exists():
+        return {}
+
+    try:
+        payload = json.loads(POLICY_FILE.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+    result: dict[str, str] = {}
+    for key, value in payload.items():
+        if isinstance(key, str) and isinstance(value, str):
+            result[key.strip().lower()] = value.strip()
+    return result
+
+
+_GENERIC_QUERY_TOKENS = {
+    "all",
+    "any",
+    "company",
+    "company policies",
+    "company policy",
+    "check company policies",
+    "policies",
+    "policy",
+    "hr",
+    "hr policies",
+    "show me",
+}
+
+
+def _wrap_markdown_as_c1(text: str) -> str:
+    safe = (text or "").replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+    return f"<content><custom_markdown>{safe}</custom_markdown></content>"
+
+
+def _build_policies_markdown(policies: dict[str, str]) -> str:
+    if not policies:
+        return "_No policies are currently configured._"
+    sections = ["# Company policies\n"]
+    for name, text in policies.items():
+        sections.append(f"### {name.title()}\n{text}\n")
+    return "\n".join(sections)
+
+
+# Visual icon + chart-weight per policy so the infographic conveys relative coverage.
+_POLICY_META = {
+    "leave policy": {"icon": "🌴", "weight": 18, "tag": "Leave"},
+    "work from home policy": {"icon": "🏠", "weight": 12, "tag": "WFH"},
+    "referral policy": {"icon": "🎁", "weight": 8, "tag": "Referral"},
+    "interview policy": {"icon": "🎯", "weight": 10, "tag": "Interview"},
+    "code of conduct": {"icon": "🛡️", "weight": 14, "tag": "Conduct"},
+}
+
+
+def _slug(name: str) -> str:
+    return name.replace(" ", "-").lower()
+
+
+def _policy_meta(name: str) -> dict:
+    return _POLICY_META.get(name.lower(), {"icon": "📄", "weight": 6, "tag": name.title()[:18]})
+
+
+def _format_all_policies(policies: dict[str, str]) -> dict:
+    if not policies:
+        return {
+            "status": "not_found",
+            "message": "No policies are configured.",
+            "available_policies": [],
+            "ui": {
+                "summary": "No policies configured.",
+                "c1_response": _wrap_markdown_as_c1("_No policies are currently configured._"),
+            },
+        }
+    markdown = _build_policies_markdown(policies)
+    tabs = [
+        {
+            "id": _slug(name),
+            "label": f"{_policy_meta(name)['icon']}  {name.title()}",
+            "icon": _policy_meta(name)["icon"],
+            "markdown": f"### {name.title()}\n\n{text}",
+        }
+        for name, text in policies.items()
+    ]
+    chart_data = [
+        {"name": _policy_meta(name)["tag"], "value": _policy_meta(name)["weight"]}
+        for name in policies.keys()
+    ]
+    return {
+        "status": "success",
+        "policy_name": "all",
+        "summary": "All currently configured company policies",
+        "policies": [
+            {"policy_name": name.title(), "policy_text": text}
+            for name, text in policies.items()
+        ],
+        "ui": {
+            "summary": "Here is the company policy stack — switch tabs to drill into each.",
+            "c1_response": _wrap_markdown_as_c1(markdown),
+            "tabs": tabs,
+            "chart": {
+                "type": "donut",
+                "title": "Policy coverage at a glance",
+                "xKey": "name",
+                "yKey": "value",
+                "data": chart_data,
+            },
+        },
+    }
+
+
+def _format_single_policy(name: str, text: str) -> dict:
+    markdown = f"# {name.title()}\n\n{text}"
+    return {
+        "status": "success",
+        "policy_name": name,
+        "policy_text": text,
+        "ui": {
+            "summary": f"{name.title()} summary",
+            "c1_response": _wrap_markdown_as_c1(markdown),
+            "cards": [
+                {
+                    "title": name.title(),
+                    "subtitle": text,
+                    "tags": ["Policy"],
+                    "actions": [],
+                }
+            ],
+        },
+    }
+
+
+def register(mcp: FastMCP) -> None:
+    policies = _load_policies()
+
+    @mcp.tool()
+    def get_policy_info(policy_name: str) -> dict:
+        """Lookup policy text by name or alias.
+
+        Pass ``policy_name="all"`` (or any generic phrase like "company policies") to
+        retrieve every configured policy at once.
+        """
+        query = (policy_name or "").strip().lower()
+        if not query or query in _GENERIC_QUERY_TOKENS:
+            return _format_all_policies(policies)
+
+        # Generic phrases that contain "polic" without naming a specific area also map
+        # to the all-policies summary so recruiters get something useful.
+        if "polic" in query and not any(
+            keyword in query
+            for keyword in ("leave", "vacation", "wfh", "remote", "hybrid", "home", "referral", "bonus", "interview", "feedback", "conduct", "ethics", "harassment")
+        ):
+            return _format_all_policies(policies)
+
+        for name, text in policies.items():
+            if query in name:
+                return _format_single_policy(name, text)
+
+        for canonical_name, aliases in POLICY_ALIASES.items():
+            if any(alias in query for alias in aliases):
+                text = policies.get(canonical_name)
+                if text:
+                    return _format_single_policy(canonical_name, text)
+
+        available = sorted(policies.keys())
+        return {
+            "status": "not_found",
+            "message": f"No matching policy found for '{policy_name}'.",
+            "available_policies": available,
+            "ui": {
+                "summary": f"No policy matched '{policy_name}'. Available: {', '.join(available)}.",
+                "c1_response": _wrap_markdown_as_c1(
+                    f"_No policy matched **{policy_name}**._\n\n"
+                    f"**Available policies:** {', '.join(available) or '_(none configured)_'}"
+                ),
+            },
+        }

backend/mcp_server/tools/reference_resumes.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from services.reference_data_service import ingest_reference_resumes, sync_reference_resumes_to_local
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool()
+    def bulk_ingest_reference_resumes(
+        limit: int = 20,
+        source_dir: str | None = None,
+        force_reingest: bool = False,
+        sync_to_local: bool = True,
+        sync_max_files: int = 150,
+    ) -> dict:
+        """Bulk ingest sample resumes from a local directory into SQLite and vector index."""
+        sync_result = None
+        ingest_source = source_dir
+
+        if sync_to_local:
+            sync_result = sync_reference_resumes_to_local(
+                max_files=max(1, min(sync_max_files, 1000)),
+                source_dir=source_dir,
+            )
+            ingest_source = str(sync_result.get("target_dir"))
+
+        summary = ingest_reference_resumes(
+            limit=max(1, min(limit, 200)),
+            source_dir=ingest_source,
+            force_reingest=force_reingest,
+        )
+        return {
+            "status": "success",
+            "sync": sync_result,
+            "summary": {
+                "source_dir": summary.source_dir,
+                "requested_limit": summary.requested_limit,
+                "files_seen": summary.files_seen,
+                "ingested": summary.ingested,
+                "skipped": summary.skipped,
+                "failed": summary.failed,
+            },
+            "failures": summary.failures[:20],
+        }

backend/mcp_server/tools/vector_search.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from fastmcp import FastMCP
+
+from services.search_service import QdrantSearchService
+
+
+def register(mcp: FastMCP) -> None:
+    search_service = QdrantSearchService()
+
+    @mcp.tool()
+    def semantic_candidate_search(query: str, top_k: int = 5) -> dict:
+        """Search candidates semantically from Qdrant and return GenUI-ready payloads."""
+        rows = search_service.semantic_search(query=query, top_k=top_k)
+        if not rows:
+            return {
+                "status": "no_results",
+                "message": "No semantic matches found. Ensure resumes are ingested and Qdrant is configured.",
+                "ui": {"summary": "No candidate results", "cards": []},
+            }
+
+        return {
+            "status": "success",
+            "count": len(rows),
+            "matches": rows,
+            "ui": search_service.build_genui_payload(query=query, rows=rows),
+        }

backend/requirements.txt

@@ -0,0 +1,14 @@
+fastapi==0.116.1
+uvicorn[standard]==0.34.2
+python-multipart==0.0.20
+python-dotenv==1.1.0
+pydantic-settings==2.10.1
+sqlalchemy==2.0.41
+pypdf==5.4.0
+qdrant-client==1.14.2
+boto3==1.38.9
+fastmcp==2.10.6
+google-adk==1.5.0
+google-generativeai==0.8.5
+google-genai>=1.21.1
+faker==37.1.0

backend/scripts/load_reference_resumes.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+BACKEND_ROOT = Path(__file__).resolve().parents[1]
+if str(BACKEND_ROOT) not in sys.path:
+    sys.path.insert(0, str(BACKEND_ROOT))
+
+from core.db import init_db
+from services.reference_data_service import ingest_reference_resumes
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Bulk ingest sample resumes into local database")
+    parser.add_argument("--limit", type=int, default=20, help="Maximum number of PDF files to ingest")
+    parser.add_argument(
+        "--source-dir",
+        type=str,
+        default=None,
+        help="Optional source directory containing resume PDFs",
+    )
+    parser.add_argument(
+        "--force-reingest",
+        action="store_true",
+        help="Reprocess files even if matching candidate IDs already exist",
+    )
+    args = parser.parse_args()
+
+    init_db()
+    summary = ingest_reference_resumes(
+        limit=max(1, min(args.limit, 500)),
+        source_dir=args.source_dir,
+        force_reingest=args.force_reingest,
+    )
+
+    print("Reference resume ingestion summary")
+    print(f"source_dir: {summary.source_dir}")
+    print(f"requested_limit: {summary.requested_limit}")
+    print(f"files_seen: {summary.files_seen}")
+    print(f"ingested: {summary.ingested}")
+    print(f"skipped: {summary.skipped}")
+    print(f"failed: {summary.failed}")
+
+    if summary.failures:
+        print("failures:")
+        for item in summary.failures:
+            print(f" - {item['file']}: {item['error']}")
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/sync_reference_resumes.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+BACKEND_ROOT = Path(__file__).resolve().parents[1]
+if str(BACKEND_ROOT) not in sys.path:
+    sys.path.insert(0, str(BACKEND_ROOT))
+
+from services.reference_data_service import sync_reference_resumes_to_local
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Copy reference resumes into local project storage")
+    parser.add_argument(
+        "--max-files",
+        type=int,
+        default=120,
+        help="Maximum number of PDF resumes to copy",
+    )
+    parser.add_argument(
+        "--source-dir",
+        type=str,
+        default=None,
+        help="Optional source directory containing PDF resumes",
+    )
+    args = parser.parse_args()
+
+    summary = sync_reference_resumes_to_local(
+        max_files=max(1, min(args.max_files, 1000)),
+        source_dir=args.source_dir,
+    )
+
+    print("Reference resume sync summary")
+    print(f"source_dir: {summary['source_dir']}")
+    print(f"target_dir: {summary['target_dir']}")
+    print(f"files_seen: {summary['files_seen']}")
+    print(f"copied: {summary['copied']}")
+    print(f"skipped: {summary['skipped']}")
+
+
+if __name__ == "__main__":
+    main()

backend/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer for ingestion, search, embeddings, and storage."""

backend/services/candidate_service.py

@@ -0,0 +1,414 @@
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any
+
+from sqlalchemy import or_, select
+from sqlalchemy.orm import Session
+
+from core.models import Candidate, QueryAudit
+
+
+class CandidateService:
+    def upsert_candidate(
+        self,
+        db: Session,
+        *,
+        external_id: str | None,
+        full_name: str | None,
+        email: str | None,
+        phone: str | None,
+        location: str | None,
+        years_experience: float | None,
+        skills: list[str],
+        summary: str,
+        source_resume_key: str | None,
+        source_resume_url: str | None,
+    ) -> Candidate:
+        candidate_id = external_id or str(uuid.uuid4())
+
+        existing = db.execute(
+            select(Candidate).where(Candidate.external_id == candidate_id)
+        ).scalar_one_or_none()
+
+        if existing is None:
+            existing = Candidate(external_id=candidate_id)
+            db.add(existing)
+
+        existing.full_name = full_name
+        existing.email = email
+        existing.phone = phone
+        existing.location = location
+        existing.years_experience = years_experience
+        existing.skills_csv = ", ".join([skill.strip() for skill in skills if skill.strip()])
+        existing.summary = summary
+        existing.source_resume_key = source_resume_key
+        existing.source_resume_url = source_resume_url
+
+        db.commit()
+        db.refresh(existing)
+        return existing
+
+    # Role-keyword aliases used to harden role-based filtering. When a recruiter
+    # searches for "AI engineers" we want only candidates whose skills/summary
+    # actually mention AI/ML/NLP — not the whole pool.
+    _ROLE_KEYWORDS: dict[str, tuple[str, ...]] = {
+        "ai": ("ai", "ml", "machine learning", "deep learning", "nlp", "llm", "tensorflow", "pytorch"),
+        "ml": ("ml", "machine learning", "deep learning", "nlp", "tensorflow", "pytorch", "scikit"),
+        "data": ("data", "analytics", "sql", "pandas", "spark", "hadoop", "warehouse"),
+        "backend": ("backend", "fastapi", "django", "node", "spring", "go", "microservice", "api"),
+        "frontend": ("frontend", "react", "next.js", "vue", "angular", "typescript", "javascript", "html", "css"),
+        "fullstack": ("full stack", "fullstack", "react", "node", "django", "fastapi", "typescript"),
+        "devops": ("devops", "kubernetes", "docker", "aws", "gcp", "azure", "terraform", "ci/cd"),
+        "security": ("security", "cyber", "siem", "soc", "penetration", "infosec", "iam"),
+        "cloud": ("cloud", "aws", "gcp", "azure", "kubernetes", "terraform"),
+        "mobile": ("mobile", "android", "ios", "kotlin", "swift", "react native", "flutter"),
+        "qa": ("qa", "test", "cypress", "playwright", "selenium", "automation"),
+    }
+
+    def _expand_role_tokens(self, tokens: list[str]) -> tuple[list[str], list[str]]:
+        """Return (required_keywords, role_anchors).
+
+        Required keywords are the at-least-one set the candidate must match.
+        Role anchors get stronger weighting in the scoring loop below.
+        """
+        required: set[str] = set()
+        anchors: list[str] = []
+        for tok in tokens:
+            for role, expansions in self._ROLE_KEYWORDS.items():
+                if tok == role or tok in expansions:
+                    anchors.append(role)
+                    required.update(expansions)
+        return sorted(required), anchors
+
+    def search_candidates(self, db: Session, query: str, limit: int = 10) -> list[Candidate]:
+        raw_query = query.strip()
+        if not raw_query:
+            return self.list_recent_candidates(db, limit=limit)
+
+        tokens = self._extract_tokens(raw_query)
+        required_keywords, role_anchors = self._expand_role_tokens(tokens)
+
+        # When the user asks role-specific ("AI engineers"), require the candidate to
+        # mention at least one related keyword. Falls back to the original token set
+        # when no role anchor is detected.
+        match_keywords = required_keywords if required_keywords else tokens
+        patterns = [f"%{token}%" for token in match_keywords] if match_keywords else [f"%{raw_query}%"]
+
+        conditions = []
+        for pattern in patterns:
+            conditions.extend(
+                [
+                    Candidate.full_name.ilike(pattern),
+                    Candidate.skills_csv.ilike(pattern),
+                    Candidate.location.ilike(pattern),
+                    Candidate.summary.ilike(pattern),
+                ]
+            )
+
+        stmt = (
+            select(Candidate)
+            .where(or_(*conditions))
+            .order_by(Candidate.updated_at.desc())
+            .limit(max(limit * 6, 40))
+        )
+        rows = list(db.execute(stmt).scalars().all())
+
+        if not rows:
+            return []
+
+        scored_rows: list[tuple[int, Candidate]] = []
+        for row in rows:
+            haystack = " ".join(
+                [
+                    row.full_name or "",
+                    row.skills_csv or "",
+                    row.location or "",
+                    row.summary or "",
+                ]
+            ).lower()
+
+            score = 0
+            for token in tokens:
+                if token in haystack:
+                    score += 3
+
+            # Strong boost when the candidate hits any keyword from the user's role.
+            if role_anchors:
+                role_hits = sum(1 for kw in required_keywords if kw in haystack)
+                score += role_hits * 6
+                # Hard gate: drop candidates that don't match the role at all.
+                if role_hits == 0:
+                    continue
+
+            if row.location and any(city in row.location.lower() for city in ("bangalore", "bengaluru")):
+                if any(city in tokens for city in ("bangalore", "bengaluru")):
+                    score += 4
+
+            scored_rows.append((score, row))
+
+        ranked = [item for item in sorted(scored_rows, key=lambda pair: pair[0], reverse=True) if item[0] > 0]
+        if not ranked:
+            return []  # honour the role gate even when no candidate scored
+
+        ranked_rows = [row for _, row in ranked]
+        return self._dedupe_candidates(ranked_rows, limit)
+
+    def list_recent_candidates(self, db: Session, limit: int = 10) -> list[Candidate]:
+        stmt = select(Candidate).order_by(Candidate.updated_at.desc()).limit(limit)
+        rows = list(db.execute(stmt).scalars().all())
+        return self._dedupe_candidates(rows, limit)
+
+    def get_candidate(self, db: Session, candidate_id: str) -> Candidate | None:
+        clean_id = (candidate_id or "").strip()
+        if not clean_id:
+            return None
+        return db.execute(
+            select(Candidate).where(Candidate.external_id == clean_id)
+        ).scalar_one_or_none()
+
+    def build_profile_payload(self, candidate: Candidate) -> dict[str, Any]:
+        skills = [token.strip() for token in (candidate.skills_csv or "").split(",") if token.strip()]
+        meta = {
+            "candidate_id": candidate.external_id,
+            "email": candidate.email,
+            "phone": candidate.phone,
+            "location": candidate.location,
+            "experience_years": candidate.years_experience,
+        }
+
+        display_name = candidate.full_name or candidate.external_id
+        meta_lines = [f"- **Name:** {display_name}"]
+        if candidate.email:
+            meta_lines.append(f"- **Email:** {candidate.email}")
+        if candidate.phone:
+            meta_lines.append(f"- **Phone:** {candidate.phone}")
+        if candidate.location:
+            meta_lines.append(f"- **Location:** {candidate.location}")
+        if candidate.years_experience is not None:
+            meta_lines.append(f"- **Experience:** {candidate.years_experience} years")
+        if skills:
+            meta_lines.append(f"- **Skills:** {', '.join(skills)}")
+        if candidate.source_resume_url:
+            meta_lines.append(f"- **Resume:** [Open PDF]({candidate.source_resume_url})")
+
+        summary_md = "\n".join(meta_lines)
+        if candidate.summary:
+            summary_md += "\n\n**Resume Summary**\n\n" + candidate.summary[:1200]
+
+        card = {
+            "title": display_name,
+            "subtitle": (candidate.summary or "")[:160] or "Candidate profile",
+            "tags": skills[:6],
+            "meta": meta,
+            "actions": [],
+        }
+
+        years = float(candidate.years_experience or 0)
+        skill_groups = self._classify_skills(skills)
+        chart = {
+            "type": "radar",
+            "title": "Skill profile",
+            "xKey": "name",
+            "yKey": "score",
+            "data": [
+                {"name": label, "score": value}
+                for label, value in [
+                    ("Backend", skill_groups.get("backend", 0)),
+                    ("Frontend", skill_groups.get("frontend", 0)),
+                    ("Cloud", skill_groups.get("cloud", 0)),
+                    ("Data/ML", skill_groups.get("data", 0)),
+                    ("Years", round(min(years, 10), 1)),
+                ]
+            ],
+        }
+
+        skills_chip_line = (
+            " ".join(f"`{skill}`" for skill in skills) if skills else "_No skills detected._"
+        )
+        contact_line = " · ".join(
+            line
+            for line in (
+                f"📧 {candidate.email}" if candidate.email else "",
+                f"📞 {candidate.phone}" if candidate.phone else "",
+                f"📍 {candidate.location}" if candidate.location else "",
+                f"🧭 {candidate.years_experience} yrs" if candidate.years_experience is not None else "",
+            )
+            if line
+        ) or "_Contact info unavailable._"
+        resume_md = (candidate.summary or "_Resume summary not available._")[:1500]
+        resume_link = (
+            f"\n\n[Open original PDF]({candidate.source_resume_url})"
+            if candidate.source_resume_url
+            else ""
+        )
+        markdown_body = (
+            f"# {display_name}\n\n"
+            f"{contact_line}\n\n"
+            f"### Skills\n{skills_chip_line}\n\n"
+            f"### Resume snapshot\n{resume_md}{resume_link}"
+        )
+        safe_md = (
+            markdown_body.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        )
+        c1_response = f"<content><custom_markdown>{safe_md}</custom_markdown></content>"
+
+        return {
+            "summary": summary_md,
+            "cards": [card],
+            "chart": chart,
+            "c1_response": c1_response,
+        }
+
+    def get_by_external_ids(self, db: Session, external_ids: list[str]) -> list[Candidate]:
+        if not external_ids:
+            return []
+        stmt = select(Candidate).where(Candidate.external_id.in_(external_ids))
+        return list(db.execute(stmt).scalars().all())
+
+    def audit_query(self, db: Session, session_id: str, query: str, top_k: int) -> None:
+        db.add(QueryAudit(session_id=session_id, query=query, top_k=top_k))
+        db.commit()
+
+    def build_genui_payload(self, query: str, candidates: list[Candidate]) -> dict[str, Any]:
+        cards = [self.to_card(candidate) for candidate in candidates]
+
+        # Chart 1: experience distribution per candidate (bar/auto).
+        chart_data = [
+            {
+                "name": candidate.full_name or candidate.external_id[:8],
+                "years": float(candidate.years_experience or 0),
+            }
+            for candidate in candidates
+        ]
+
+        # Chart 2: skill cluster across the matched pool — adapts to whoever shows up.
+        cluster_totals: dict[str, int] = {}
+        for c in candidates:
+            skills = [t.strip() for t in (c.skills_csv or "").split(",") if t.strip()]
+            buckets = self._classify_skills(skills)
+            for bucket, count in buckets.items():
+                cluster_totals[bucket] = cluster_totals.get(bucket, 0) + count
+        skill_chart = {
+            "type": "auto",  # let the frontend pick donut/radar based on shape
+            "title": f"Skill mix across {len(candidates)} match(es)",
+            "xKey": "name",
+            "yKey": "value",
+            "data": [
+                {"name": label.title(), "value": cluster_totals.get(label, 0)}
+                for label in ("backend", "frontend", "cloud", "data")
+                if cluster_totals.get(label, 0) > 0
+            ],
+        }
+
+        # Prefer the skill-mix chart when we actually have skill data; fall back to
+        # the experience overview otherwise. This is dynamic per query.
+        chart = (
+            skill_chart
+            if skill_chart["data"]
+            else {
+                "type": "bar",
+                "title": "Experience overview",
+                "xKey": "name",
+                "yKey": "years",
+                "data": chart_data,
+            }
+        )
+
+        return {
+            "summary": f"Found {len(candidates)} profile(s) matching '{query}' from local metadata.",
+            "cards": cards,
+            "chart": chart,
+        }
+
+    @staticmethod
+    def to_card(candidate: Candidate, score: float | None = None) -> dict[str, Any]:
+        tags = []
+        if candidate.skills_csv:
+            tags = [token.strip() for token in candidate.skills_csv.split(",") if token.strip()][:4]
+
+        return {
+            "candidate_id": candidate.external_id,
+            "title": candidate.full_name or candidate.external_id,
+            "subtitle": candidate.summary or "Candidate profile",
+            "tags": tags,
+            "meta": {
+                "experience": candidate.years_experience,
+                "location": candidate.location,
+                "score": round(score, 4) if score is not None else None,
+            },
+            "actions": [
+                {"label": "Open Profile", "action": f"open_profile:{candidate.external_id}"},
+            ],
+        }
+
+    @staticmethod
+    def _classify_skills(skills: list[str]) -> dict[str, int]:
+        """Bucket skills into broad categories for radar-chart axes."""
+        backend = {"python", "java", "go", "node", "fastapi", "django", "spring", "rails", "ruby", "c#", ".net", "scala"}
+        frontend = {"react", "next.js", "vue", "angular", "typescript", "javascript", "html", "css", "redux"}
+        cloud = {"aws", "gcp", "azure", "docker", "kubernetes", "terraform", "lambda"}
+        data = {"sql", "ml", "nlp", "llm", "tensorflow", "pytorch", "spark", "hadoop", "pandas", "numpy", "ai"}
+        buckets = {"backend": 0, "frontend": 0, "cloud": 0, "data": 0}
+        for raw in skills:
+            tok = raw.lower().strip()
+            if tok in backend:
+                buckets["backend"] += 1
+            if tok in frontend:
+                buckets["frontend"] += 1
+            if tok in cloud:
+                buckets["cloud"] += 1
+            if tok in data:
+                buckets["data"] += 1
+        return buckets
+
+    @staticmethod
+    def _extract_tokens(query: str) -> list[str]:
+        stopwords = {
+            "find",
+            "top",
+            "candidate",
+            "candidates",
+            "for",
+            "with",
+            "and",
+            "the",
+            "a",
+            "an",
+            "in",
+            "of",
+            "to",
+            "from",
+            "show",
+            "list",
+            "please",
+            "need",
+            "looking",
+            "senior",
+        }
+
+        raw_tokens = re.findall(r"[a-zA-Z0-9+#.]{2,}", query.lower())
+        deduped: list[str] = []
+        for token in raw_tokens:
+            if token in stopwords:
+                continue
+            if token not in deduped:
+                deduped.append(token)
+        return deduped
+
+    @staticmethod
+    def _dedupe_candidates(rows: list[Candidate], limit: int) -> list[Candidate]:
+        output: list[Candidate] = []
+        seen: set[str] = set()
+
+        for row in rows:
+            key = (row.full_name or "").strip().lower() or row.external_id
+            if key in seen:
+                continue
+            seen.add(key)
+            output.append(row)
+            if len(output) >= limit:
+                break
+
+        return output

backend/services/embedding_service.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import logging
+
+import google.generativeai as genai
+
+from core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class EmbeddingService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self._is_configured = False
+
+        if self.settings.gemini_api_key:
+            genai.configure(api_key=self.settings.gemini_api_key)
+            self._is_configured = True
+
+    @property
+    def is_ready(self) -> bool:
+        return self._is_configured
+
+    def embed_document(self, text: str) -> list[float]:
+        return self._embed(text=text, task_type="retrieval_document")
+
+    def embed_query(self, text: str) -> list[float]:
+        return self._embed(text=text, task_type="retrieval_query")
+
+    def _embed(self, text: str, task_type: str) -> list[float]:
+        if not self._is_configured:
+            raise RuntimeError("GEMINI_API_KEY is required to generate embeddings.")
+
+        response = genai.embed_content(
+            model=self.settings.embedding_model,
+            content=text,
+            task_type=task_type,
+        )
+        embedding = response.get("embedding")
+        if not embedding:
+            raise RuntimeError("Embedding response did not include an embedding vector.")
+        return embedding

backend/services/ingestion_service.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import io
+import logging
+import re
+import uuid
+from dataclasses import dataclass
+
+from pypdf import PdfReader
+from sqlalchemy.orm import Session
+
+from core.config import get_settings
+from services.candidate_service import CandidateService
+from services.search_service import QdrantSearchService
+from services.storage_service import ObjectStorageService
+
+logger = logging.getLogger(__name__)
+
+EMAIL_PATTERN = re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+PHONE_PATTERN = re.compile(r"(?:\+\d{1,3}[\s-]?)?(?:\(?\d{3}\)?[\s-]?)?\d{3}[\s-]?\d{4}")
+EXPERIENCE_PATTERN = re.compile(r"(\d+(?:\.\d+)?)\s*(?:\+)?\s*years?", flags=re.IGNORECASE)
+
+
+@dataclass
+class IngestionResult:
+    candidate_id: str
+    file_name: str
+    chunks_indexed: int
+    r2_url: str | None
+
+
+class IngestionService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self.candidate_service = CandidateService()
+        self.search_service = QdrantSearchService()
+        self.storage_service = ObjectStorageService()
+
+    def ingest_pdf(
+        self,
+        db: Session,
+        *,
+        file_name: str,
+        file_bytes: bytes,
+        external_id: str | None = None,
+    ) -> IngestionResult:
+        try:
+            text = self._extract_pdf_text(file_bytes)
+        except Exception:
+            text = ""
+
+        if not text.strip():
+            # pypdf failed (scanned / image-only PDF). Fall back to Gemini's native PDF
+            # support which OCRs the document.
+            try:
+                text = self._extract_with_gemini(file_bytes, file_name)
+            except Exception as exc:
+                logger.warning("Gemini PDF OCR failed for %s: %s", file_name, exc)
+                text = ""
+
+        if not text.strip():
+            # Last-resort: generate a minimal record from the filename so the candidate
+            # still appears in search.
+            text = self._fallback_text_from_name(file_name)
+
+        profile = self._extract_profile(text)
+        if not profile.get("full_name"):
+            profile["full_name"] = self._candidate_name_from_filename(file_name)
+
+        summary = text[:1500]
+
+        object_key, r2_url = self.storage_service.upload_resume(file_name=file_name, file_bytes=file_bytes)
+
+        candidate_id = external_id or str(uuid.uuid4())
+        candidate = self.candidate_service.upsert_candidate(
+            db,
+            external_id=candidate_id,
+            full_name=profile["full_name"],
+            email=profile["email"],
+            phone=profile["phone"],
+            location=profile["location"],
+            years_experience=profile["years_experience"],
+            skills=profile["skills"],
+            summary=summary,
+            source_resume_key=object_key,
+            source_resume_url=r2_url,
+        )
+
+        chunks = self._chunk_text(text)
+        metadata = {
+            "full_name": candidate.full_name,
+            "email": candidate.email,
+            "location": candidate.location,
+            "skills": candidate.skills_csv,
+            "years_experience": candidate.years_experience,
+            "source_resume_url": candidate.source_resume_url,
+            "file_name": file_name,
+        }
+        indexed_count = self.search_service.upsert_document_chunks(
+            candidate_id=candidate.external_id,
+            chunks=chunks,
+            metadata=metadata,
+        )
+
+        return IngestionResult(
+            candidate_id=candidate.external_id,
+            file_name=file_name,
+            chunks_indexed=indexed_count,
+            r2_url=r2_url,
+        )
+
+    def ingest_text_profile(
+        self,
+        db: Session,
+        *,
+        candidate_name: str,
+        resume_text: str,
+        location: str | None = None,
+        skills: list[str] | None = None,
+        years_experience: float | None = None,
+    ) -> IngestionResult:
+        if not resume_text.strip():
+            raise ValueError("resume_text cannot be empty.")
+
+        candidate_id = str(uuid.uuid4())
+        candidate = self.candidate_service.upsert_candidate(
+            db,
+            external_id=candidate_id,
+            full_name=candidate_name,
+            email=None,
+            phone=None,
+            location=location,
+            years_experience=years_experience,
+            skills=skills or [],
+            summary=resume_text[:800],
+            source_resume_key=None,
+            source_resume_url=None,
+        )
+
+        chunks = self._chunk_text(resume_text)
+        metadata = {
+            "full_name": candidate.full_name,
+            "location": candidate.location,
+            "skills": candidate.skills_csv,
+            "years_experience": candidate.years_experience,
+            "source_resume_url": candidate.source_resume_url,
+            "file_name": f"{candidate_name}.txt",
+        }
+        indexed_count = self.search_service.upsert_document_chunks(
+            candidate_id=candidate.external_id,
+            chunks=chunks,
+            metadata=metadata,
+        )
+
+        return IngestionResult(
+            candidate_id=candidate.external_id,
+            file_name=f"{candidate_name}.txt",
+            chunks_indexed=indexed_count,
+            r2_url=None,
+        )
+
+    def _extract_pdf_text(self, file_bytes: bytes) -> str:
+        reader = PdfReader(io.BytesIO(file_bytes))
+        pages = [page.extract_text() or "" for page in reader.pages]
+        return "\n".join(pages)
+
+    def _extract_with_gemini(self, file_bytes: bytes, file_name: str) -> str:
+        """Use Gemini's native PDF support to OCR scanned/image-only resumes.
+
+        Gemini 2.5 Pro accepts raw PDF bytes via inline parts and can read
+        text from scanned documents. This is our fallback when pypdf yields
+        nothing.
+        """
+        api_key = self.settings.gemini_api_key
+        if not api_key:
+            raise RuntimeError("GEMINI_API_KEY is not configured.")
+
+        from google import genai
+        from google.genai import types
+
+        client = genai.Client(api_key=api_key)
+        prompt = (
+            "You are reading a candidate resume PDF. Extract every piece of text "
+            "and structure it cleanly: name, contact (email/phone/location), "
+            "experience entries, education, skills, certifications, and a short "
+            "professional summary. Preserve dates and company names exactly. Return "
+            "plain text — no JSON, no markdown."
+        )
+        response = client.models.generate_content(
+            model=self.settings.gemini_model or "gemini-2.5-pro",
+            contents=[
+                types.Part.from_bytes(data=file_bytes, mime_type="application/pdf"),
+                prompt,
+            ],
+        )
+        text = getattr(response, "text", None) or ""
+        return text.strip()
+
+    @staticmethod
+    def _candidate_name_from_filename(file_name: str) -> str:
+        base = file_name.rsplit(".", 1)[0]
+        cleaned = re.sub(r"[_\-]+", " ", base).strip()
+        if not cleaned:
+            return file_name
+        return cleaned.title()
+
+    @classmethod
+    def _fallback_text_from_name(cls, file_name: str) -> str:
+        name = cls._candidate_name_from_filename(file_name)
+        return (
+            f"Candidate {name}. Resume PDF uploaded as {file_name}. "
+            "PDF text extraction was not possible (likely scanned or image-only). "
+            "Open the original file via the resume URL for full content."
+        )
+
+    def _extract_profile(self, text: str) -> dict[str, object]:
+        lines = [line.strip() for line in text.splitlines() if line.strip()]
+        first_line = lines[0] if lines else None
+
+        email_match = EMAIL_PATTERN.search(text)
+        phone_match = PHONE_PATTERN.search(text)
+        exp_match = EXPERIENCE_PATTERN.search(text)
+
+        lower_text = text.lower()
+        skill_candidates = [
+            "python",
+            "java",
+            "typescript",
+            "react",
+            "next.js",
+            "fastapi",
+            "sql",
+            "aws",
+            "gcp",
+            "docker",
+            "kubernetes",
+            "ml",
+            "nlp",
+            "llm",
+        ]
+        found_skills = [skill for skill in skill_candidates if skill in lower_text]
+
+        return {
+            "full_name": first_line,
+            "email": email_match.group(0) if email_match else None,
+            "phone": phone_match.group(0) if phone_match else None,
+            "location": None,
+            "years_experience": float(exp_match.group(1)) if exp_match else None,
+            "skills": found_skills,
+        }
+
+    def _chunk_text(self, text: str) -> list[str]:
+        cleaned = " ".join(text.split())
+        chunk_size = self.settings.chunk_size
+        overlap = self.settings.chunk_overlap
+        max_chunks = self.settings.max_chunks_per_document
+
+        if len(cleaned) <= chunk_size:
+            return [cleaned]
+
+        chunks: list[str] = []
+        start = 0
+        while start < len(cleaned) and len(chunks) < max_chunks:
+            end = min(start + chunk_size, len(cleaned))
+            chunks.append(cleaned[start:end])
+            if end == len(cleaned):
+                break
+            start = max(0, end - overlap)
+
+        return chunks

backend/services/notification_service.py

@@ -0,0 +1,248 @@
+"""Email + meeting-link helpers for interview scheduling.
+
+When SMTP credentials are configured (SMTP_HOST, SMTP_USER, SMTP_PASSWORD,
+SMTP_FROM in .env), sending an interview invite goes out automatically with the
+.ics calendar file attached and a Google Meet room URL embedded in the body.
+
+If SMTP is not configured the helper returns ``sent=False`` along with the same
+artefacts so the agent can degrade gracefully and tell the user how to configure
+auto-send.
+"""
+from __future__ import annotations
+
+import logging
+import smtplib
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from email.message import EmailMessage
+
+from core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class InviteSendResult:
+    sent: bool
+    delivery: str  # "smtp" | "skipped" | "failed"
+    detail: str
+    meet_url: str
+    recipients: list[str]
+
+
+def generate_meet_url() -> str:
+    """Generate a Google Meet URL using their canonical room-id pattern.
+
+    Google Meet room ids look like ``xxx-yyyy-zzz`` (3-4-3 lowercase letters). When
+    an authenticated Google user opens such a URL, Google Meet creates the room on
+    first access and both invited attendees land in the same meeting.
+    """
+    import secrets
+    import string
+
+    alphabet = string.ascii_lowercase
+    parts = (
+        "".join(secrets.choice(alphabet) for _ in range(3)),
+        "".join(secrets.choice(alphabet) for _ in range(4)),
+        "".join(secrets.choice(alphabet) for _ in range(3)),
+    )
+    return f"https://meet.google.com/{'-'.join(parts)}"
+
+
+def _build_message(
+    *,
+    sender: str,
+    candidate_name: str,
+    candidate_email: str,
+    interviewer_name: str,
+    interviewer_email: str,
+    interview_round: str,
+    scheduled_on: datetime,
+    end_time: datetime,
+    meet_url: str,
+    notes: str | None,
+    ics_content: str,
+) -> EmailMessage:
+    msg = EmailMessage()
+    msg["Subject"] = f"{interview_round} interview: {candidate_name}"
+    msg["From"] = sender
+    msg["To"] = candidate_email
+    msg["Cc"] = interviewer_email
+
+    body_lines = [
+        f"Hi {candidate_name.split()[0] if candidate_name else 'there'},",
+        "",
+        f"Your {interview_round} interview with {interviewer_name} is scheduled for "
+        f"{scheduled_on.strftime('%A, %d %B %Y at %I:%M %p')} "
+        f"(ends {end_time.strftime('%I:%M %p')}).",
+        "",
+        f"Join the meeting: {meet_url}",
+        "",
+        "The calendar invite is attached as an .ics file — just open it to add the",
+        "event to your calendar. Reply to this email if you need to reschedule.",
+    ]
+    if notes:
+        body_lines.extend(["", f"Notes from the recruiter: {notes}"])
+    body_lines.extend(["", "— Recruitment OS"])
+    msg.set_content("\n".join(body_lines))
+
+    msg.add_attachment(
+        ics_content.encode("utf-8"),
+        maintype="text",
+        subtype="calendar",
+        filename="interview.ics",
+    )
+    return msg
+
+
+def send_interview_invite(
+    *,
+    candidate_name: str,
+    candidate_email: str,
+    interviewer_name: str,
+    interviewer_email: str,
+    interview_round: str,
+    scheduled_on: datetime,
+    end_time: datetime,
+    notes: str | None,
+    ics_content: str,
+    meet_url: str | None = None,
+) -> InviteSendResult:
+    settings = get_settings()
+    recipients = [candidate_email, interviewer_email]
+    meet = meet_url or generate_meet_url()
+
+    if not settings.has_smtp_config or not settings.smtp_from:
+        return InviteSendResult(
+            sent=False,
+            delivery="skipped",
+            detail=(
+                "SMTP credentials are not configured (SMTP_HOST/SMTP_USER/SMTP_PASSWORD/"
+                "SMTP_FROM). The invite was prepared but no email was actually sent. "
+                "Add SMTP variables to .env and restart the backend to enable auto-send."
+            ),
+            meet_url=meet,
+            recipients=recipients,
+        )
+
+    try:
+        message = _build_message(
+            sender=settings.smtp_from,
+            candidate_name=candidate_name,
+            candidate_email=candidate_email,
+            interviewer_name=interviewer_name,
+            interviewer_email=interviewer_email,
+            interview_round=interview_round,
+            scheduled_on=scheduled_on,
+            end_time=end_time,
+            meet_url=meet,
+            notes=notes,
+            ics_content=ics_content,
+        )
+
+        if settings.smtp_use_tls:
+            with smtplib.SMTP(settings.smtp_host, settings.smtp_port, timeout=15) as server:
+                server.starttls()
+                if settings.smtp_user and settings.smtp_password:
+                    server.login(settings.smtp_user, settings.smtp_password)
+                server.send_message(message, to_addrs=recipients)
+        else:
+            with smtplib.SMTP_SSL(settings.smtp_host, settings.smtp_port, timeout=15) as server:
+                if settings.smtp_user and settings.smtp_password:
+                    server.login(settings.smtp_user, settings.smtp_password)
+                server.send_message(message, to_addrs=recipients)
+
+        return InviteSendResult(
+            sent=True,
+            delivery="smtp",
+            detail=f"Email + .ics + Google Meet link sent to {', '.join(recipients)}.",
+            meet_url=meet,
+            recipients=recipients,
+        )
+    except Exception as exc:
+        logger.exception("SMTP send failed")
+        return InviteSendResult(
+            sent=False,
+            delivery="failed",
+            detail=f"SMTP attempt failed: {exc}",
+            meet_url=meet,
+            recipients=recipients,
+        )
+
+
+@dataclass
+class GenericSendResult:
+    sent: bool
+    delivery: str
+    detail: str
+    recipients: list[str]
+
+
+def send_plain_email(
+    *,
+    to: list[str],
+    subject: str,
+    body: str,
+    cc: list[str] | None = None,
+) -> GenericSendResult:
+    """Send a plain-text email using the configured SMTP settings."""
+    settings = get_settings()
+    recipients = [addr for addr in (to or []) if addr]
+    cc_list = [addr for addr in (cc or []) if addr]
+    all_recipients = recipients + cc_list
+
+    if not all_recipients:
+        return GenericSendResult(
+            sent=False,
+            delivery="error",
+            detail="At least one recipient (to) is required.",
+            recipients=[],
+        )
+
+    if not settings.has_smtp_config or not settings.smtp_from:
+        return GenericSendResult(
+            sent=False,
+            delivery="skipped",
+            detail=(
+                "SMTP credentials are not configured. Add SMTP_HOST/SMTP_USER/"
+                "SMTP_PASSWORD/SMTP_FROM in .env and restart the backend."
+            ),
+            recipients=all_recipients,
+        )
+
+    try:
+        message = EmailMessage()
+        message["Subject"] = subject
+        message["From"] = settings.smtp_from
+        message["To"] = ", ".join(recipients)
+        if cc_list:
+            message["Cc"] = ", ".join(cc_list)
+        message.set_content(body)
+
+        if settings.smtp_use_tls:
+            with smtplib.SMTP(settings.smtp_host, settings.smtp_port, timeout=15) as server:
+                server.starttls()
+                if settings.smtp_user and settings.smtp_password:
+                    server.login(settings.smtp_user, settings.smtp_password)
+                server.send_message(message, to_addrs=all_recipients)
+        else:
+            with smtplib.SMTP_SSL(settings.smtp_host, settings.smtp_port, timeout=15) as server:
+                if settings.smtp_user and settings.smtp_password:
+                    server.login(settings.smtp_user, settings.smtp_password)
+                server.send_message(message, to_addrs=all_recipients)
+
+        return GenericSendResult(
+            sent=True,
+            delivery="smtp",
+            detail=f"Email delivered to {', '.join(all_recipients)}.",
+            recipients=all_recipients,
+        )
+    except Exception as exc:
+        logger.exception("SMTP send failed")
+        return GenericSendResult(
+            sent=False,
+            delivery="failed",
+            detail=f"SMTP attempt failed: {exc}",
+            recipients=all_recipients,
+        )

backend/services/reference_data_service.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from sqlalchemy import select
+
+from core.db import SessionLocal
+from core.models import Candidate
+from services.ingestion_service import IngestionService
+
+DEFAULT_REFERENCE_RESUMES_DIR = (
+    Path(__file__).resolve().parents[1]
+    / "data"
+    / "reference_resumes"
+)
+
+FALLBACK_REFERENCE_RESUME_DIRS = [
+    Path("E:/SaturnIQ/engazeiq-adk")
+    / "multiagent_platform_backend"
+    / "services"
+    / "agent_services"
+    / "mcp_tools"
+    / "organized_docs"
+    / "resumes",
+    Path("E:/SaturnIQ/engazeiq-adk")
+    / "multiagent_platform_backend"
+    / "services"
+    / "agent_services"
+    / "mcp_tools"
+    / "organized_docs"
+    / "resumes_",
+]
+
+
+@dataclass
+class ReferenceIngestionSummary:
+    source_dir: str
+    requested_limit: int
+    files_seen: int
+    ingested: int
+    skipped: int
+    failed: int
+    failures: list[dict[str, str]]
+
+
+def _resolve_source_dir(source_dir: str | None) -> Path:
+    if source_dir:
+        explicit = Path(source_dir)
+        if explicit.exists() and explicit.is_dir():
+            return explicit
+        raise FileNotFoundError(f"Reference resume directory not found: {explicit}")
+
+    candidate_dirs = [DEFAULT_REFERENCE_RESUMES_DIR, *FALLBACK_REFERENCE_RESUME_DIRS]
+    for directory in candidate_dirs:
+        if directory.exists() and directory.is_dir() and any(directory.rglob("*.pdf")):
+            return directory
+
+    checked = "\n".join(str(path) for path in candidate_dirs)
+    raise FileNotFoundError(f"No usable reference resume directory found. Checked:\n{checked}")
+
+
+def _normalize_external_id(file_path: Path) -> str:
+    normalized = re.sub(r"[^a-zA-Z0-9]+", "_", file_path.stem).strip("_")
+    if not normalized:
+        normalized = "resume"
+    return f"ref_{normalized.lower()}"
+
+
+def sync_reference_resumes_to_local(
+    *,
+    max_files: int = 120,
+    source_dir: str | None = None,
+) -> dict[str, object]:
+    resolved_source = _resolve_source_dir(source_dir)
+    DEFAULT_REFERENCE_RESUMES_DIR.mkdir(parents=True, exist_ok=True)
+
+    copied = 0
+    skipped = 0
+    seen_names: set[str] = set()
+
+    pdf_files = sorted(resolved_source.rglob("*.pdf"))[: max(1, max_files)]
+    for idx, file_path in enumerate(pdf_files, start=1):
+        base_name = file_path.name
+        target_name = base_name
+
+        same_name_target = DEFAULT_REFERENCE_RESUMES_DIR / base_name
+        if same_name_target.exists() and same_name_target.stat().st_size == file_path.stat().st_size:
+            skipped += 1
+            seen_names.add(base_name.lower())
+            continue
+
+        if target_name.lower() in seen_names or (DEFAULT_REFERENCE_RESUMES_DIR / target_name).exists():
+            target_name = f"{idx:04d}_{base_name}"
+
+        seen_names.add(target_name.lower())
+        target_path = DEFAULT_REFERENCE_RESUMES_DIR / target_name
+
+        if target_path.exists():
+            skipped += 1
+            continue
+
+        shutil.copy2(file_path, target_path)
+        copied += 1
+
+    return {
+        "source_dir": str(resolved_source),
+        "target_dir": str(DEFAULT_REFERENCE_RESUMES_DIR),
+        "files_seen": len(pdf_files),
+        "copied": copied,
+        "skipped": skipped,
+    }
+
+
+def ingest_reference_resumes(
+    *,
+    limit: int = 25,
+    source_dir: str | None = None,
+    force_reingest: bool = False,
+) -> ReferenceIngestionSummary:
+    base_dir = _resolve_source_dir(source_dir)
+
+    service = IngestionService()
+    pdf_files = sorted(base_dir.rglob("*.pdf"))[: max(1, limit)]
+
+    failures: list[dict[str, str]] = []
+    ingested = 0
+    skipped = 0
+
+    with SessionLocal() as db:
+        for pdf in pdf_files:
+            external_id = _normalize_external_id(pdf)
+
+            if not force_reingest:
+                exists = db.execute(
+                    select(Candidate.id).where(Candidate.external_id == external_id)
+                ).scalar_one_or_none()
+                if exists is not None:
+                    skipped += 1
+                    continue
+
+            try:
+                file_bytes = pdf.read_bytes()
+                service.ingest_pdf(
+                    db,
+                    file_name=pdf.name,
+                    file_bytes=file_bytes,
+                    external_id=external_id,
+                )
+                ingested += 1
+            except Exception as exc:
+                failures.append({"file": str(pdf), "error": str(exc)})
+
+    return ReferenceIngestionSummary(
+        source_dir=str(base_dir),
+        requested_limit=max(1, limit),
+        files_seen=len(pdf_files),
+        ingested=ingested,
+        skipped=skipped,
+        failed=len(failures),
+        failures=failures,
+    )

backend/services/search_service.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import logging
+import uuid
+from collections import defaultdict
+from typing import Any
+
+from qdrant_client import QdrantClient
+from qdrant_client.http.models import Distance, PointStruct, VectorParams
+
+from core.config import get_settings
+from services.embedding_service import EmbeddingService
+
+logger = logging.getLogger(__name__)
+
+
+class QdrantSearchService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self.embedding_service = EmbeddingService()
+        self._client: QdrantClient | None = None
+
+    @property
+    def is_ready(self) -> bool:
+        return self.settings.has_qdrant_config and self.embedding_service.is_ready
+
+    def upsert_document_chunks(
+        self,
+        *,
+        candidate_id: str,
+        chunks: list[str],
+        metadata: dict[str, Any],
+    ) -> int:
+        if not self.is_ready:
+            logger.warning("Skipping vector upsert because Qdrant or embeddings are not configured.")
+            return 0
+
+        vectors = [self.embedding_service.embed_document(chunk) for chunk in chunks]
+        vector_size = len(vectors[0]) if vectors else 0
+        if vector_size == 0:
+            return 0
+
+        self._ensure_collection(vector_size)
+
+        points: list[PointStruct] = []
+        for idx, (chunk, vector) in enumerate(zip(chunks, vectors, strict=False)):
+            payload = {
+                "candidate_id": candidate_id,
+                "chunk_text": chunk,
+                "chunk_index": idx,
+                **metadata,
+            }
+            points.append(
+                PointStruct(
+                    id=str(uuid.uuid4()),
+                    vector=vector,
+                    payload=payload,
+                )
+            )
+
+        client = self._get_client()
+        client.upsert(collection_name=self.settings.qdrant_collection, points=points)
+        return len(points)
+
+    def semantic_search(self, query: str, top_k: int = 5) -> list[dict[str, Any]]:
+        if not self.is_ready:
+            return []
+
+        query_vector = self.embedding_service.embed_query(query)
+        client = self._get_client()
+        hits = client.search(
+            collection_name=self.settings.qdrant_collection,
+            query_vector=query_vector,
+            limit=top_k,
+            with_payload=True,
+        )
+
+        grouped: dict[str, dict[str, Any]] = defaultdict(dict)
+        for hit in hits:
+            payload = hit.payload or {}
+            candidate_id = str(payload.get("candidate_id") or "")
+            if not candidate_id:
+                continue
+
+            previous = grouped.get(candidate_id)
+            chunk_text = str(payload.get("chunk_text") or "")
+            if not previous or hit.score > previous.get("score", 0.0):
+                grouped[candidate_id] = {
+                    "candidate_id": candidate_id,
+                    "score": float(hit.score),
+                    "best_chunk": chunk_text,
+                    "location": payload.get("location"),
+                    "skills": payload.get("skills"),
+                    "name": payload.get("full_name"),
+                    "years_experience": payload.get("years_experience"),
+                }
+
+        results = sorted(grouped.values(), key=lambda item: item["score"], reverse=True)
+        return results[:top_k]
+
+    def build_genui_payload(self, query: str, rows: list[dict[str, Any]]) -> dict[str, Any]:
+        cards = []
+        chart_data = []
+
+        for row in rows:
+            chart_data.append(
+                {
+                    "name": row.get("name") or row["candidate_id"][:8],
+                    "score": round(float(row.get("score") or 0.0) * 100, 2),
+                }
+            )
+            cards.append(
+                {
+                    "title": row.get("name") or row["candidate_id"],
+                    "subtitle": row.get("best_chunk", "")[:180],
+                    "tags": [
+                        token.strip()
+                        for token in str(row.get("skills") or "").split(",")
+                        if token.strip()
+                    ][:4],
+                    "meta": {
+                        "score": round(float(row.get("score") or 0.0) * 100, 2),
+                        "location": row.get("location"),
+                        "years_experience": row.get("years_experience"),
+                    },
+                    "actions": [
+                        {"label": "Open Profile", "action": f"open_profile:{row['candidate_id']}"},
+                    ],
+                }
+            )
+
+        return {
+            "summary": f"Found {len(rows)} candidate matches for query: {query}",
+            "cards": cards,
+            "chart": {
+                "type": "bar",
+                "title": "Match Scores",
+                "xKey": "name",
+                "yKey": "score",
+                "data": chart_data,
+            },
+        }
+
+    def _ensure_collection(self, vector_size: int) -> None:
+        client = self._get_client()
+        collection = self.settings.qdrant_collection
+        if client.collection_exists(collection_name=collection):
+            return
+
+        client.create_collection(
+            collection_name=collection,
+            vectors_config=VectorParams(size=vector_size, distance=Distance.COSINE),
+        )
+
+    def _get_client(self) -> QdrantClient:
+        if self._client is None:
+            self._client = QdrantClient(
+                url=self.settings.qdrant_url,
+                api_key=self.settings.qdrant_api_key,
+                timeout=30,
+            )
+        return self._client

backend/services/storage_service.py

@@ -0,0 +1,78 @@
+"""Generic S3-compatible object storage for resume PDFs.
+
+Drop-in support for any S3-compatible service:
+
+* **Supabase Storage** — set ``S3_ENDPOINT=https://<project>.supabase.co/storage/v1/s3``
+  and use the project's ``service_role`` key as both the access key id and the
+  secret key.
+* **Backblaze B2** — endpoint ``https://s3.<region>.backblazeb2.com``.
+* **AWS S3** — leave the endpoint blank (boto3 picks the default), set the
+  region to your bucket's region.
+* **MinIO** — point at your MinIO endpoint.
+
+All four drive the same code path; only the env vars change.
+"""
+from __future__ import annotations
+
+import logging
+from datetime import datetime
+from pathlib import PurePosixPath
+
+import boto3
+from botocore.client import BaseClient
+
+from core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class ObjectStorageService:
+    def __init__(self) -> None:
+        self.settings = get_settings()
+        self._client: BaseClient | None = None
+
+    @property
+    def is_ready(self) -> bool:
+        return self.settings.has_s3_config
+
+    def upload_resume(self, file_name: str, file_bytes: bytes) -> tuple[str | None, str | None]:
+        if not self.is_ready:
+            return None, None
+
+        object_key = self._build_object_key(file_name)
+        client = self._get_client()
+
+        client.put_object(
+            Bucket=self.settings.s3_bucket,
+            Key=object_key,
+            Body=file_bytes,
+            ContentType="application/pdf",
+        )
+
+        public_url = self._build_public_url(object_key)
+        return object_key, public_url
+
+    def _get_client(self) -> BaseClient:
+        if self._client is None:
+            kwargs: dict = {
+                "aws_access_key_id": self.settings.s3_access_key_id,
+                "aws_secret_access_key": self.settings.s3_secret_access_key,
+                "region_name": self.settings.s3_region,
+            }
+            if self.settings.s3_endpoint:
+                kwargs["endpoint_url"] = self.settings.s3_endpoint
+            self._client = boto3.client("s3", **kwargs)
+        return self._client
+
+    def _build_public_url(self, object_key: str) -> str:
+        # If the provider gives a separate public/CDN URL, prefer that.
+        if self.settings.s3_public_base_url:
+            return f"{self.settings.s3_public_base_url.rstrip('/')}/{object_key}"
+        if self.settings.s3_endpoint:
+            return f"{self.settings.s3_endpoint.rstrip('/')}/{self.settings.s3_bucket}/{object_key}"
+        return f"https://{self.settings.s3_bucket}.s3.amazonaws.com/{object_key}"
+
+    def _build_object_key(self, file_name: str) -> str:
+        stamp = datetime.utcnow().strftime("%Y%m%d%H%M%S")
+        safe_name = file_name.replace(" ", "_")
+        return str(PurePosixPath("resumes") / f"{stamp}_{safe_name}")

frontend/.env.example

@@ -0,0 +1 @@
+BACKEND_URL=http://127.0.0.1:7860

frontend/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

frontend/next.config.js

@@ -0,0 +1,11 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  experimental: {
+    serverActions: {
+      bodySizeLimit: "10mb"
+    }
+  }
+};
+
+module.exports = nextConfig;

frontend/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "recruitment-genui-frontend",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p 3000",
+    "build": "next build",
+    "start": "next start -p 3000",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@crayonai/react-core": "latest",
+    "@crayonai/react-ui": "latest",
+    "@crayonai/stream": "latest",
+    "@react-three/drei": "^9.122.0",
+    "@react-three/fiber": "^8.17.10",
+    "@thesysai/genui-sdk": "latest",
+    "next": "14.2.29",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "react-markdown": "^9.1.0",
+    "recharts": "2.15.3",
+    "remark-gfm": "^4.0.1",
+    "three": "^0.164.1"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.50",
+    "@types/react": "18.3.20",
+    "@types/react-dom": "18.3.7",
+    "eslint": "8.57.1",
+    "eslint-config-next": "14.2.29",
+    "typescript": "5.8.3"
+  }
+}

frontend/src/app/api/candidates/[id]/route.ts

@@ -0,0 +1,22 @@
+import { NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  const backendBaseUrl = process.env.BACKEND_URL ?? "http://127.0.0.1:7860";
+  const upstream = await fetch(
+    `${backendBaseUrl}/api/candidates/${encodeURIComponent(params.id)}`,
+    { cache: "no-store" }
+  );
+
+  const payload = await upstream.text();
+  return new Response(payload, {
+    status: upstream.status,
+    headers: {
+      "Content-Type": upstream.headers.get("content-type") ?? "application/json"
+    }
+  });
+}

frontend/src/app/api/chat/route.ts

@@ -0,0 +1,33 @@
+import { NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  const backendBaseUrl = process.env.BACKEND_URL ?? "http://127.0.0.1:7860";
+  const body = await request.text();
+
+  const upstream = await fetch(`${backendBaseUrl}/api/chat`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    },
+    body,
+    cache: "no-store"
+  });
+
+  if (!upstream.ok || !upstream.body) {
+    const text = await upstream.text();
+    return new Response(text || "Upstream chat request failed.", {
+      status: upstream.status || 500
+    });
+  }
+
+  return new Response(upstream.body, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive"
+    }
+  });
+}

frontend/src/app/api/upload/route.ts

@@ -0,0 +1,27 @@
+import { NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+
+export async function POST(request: NextRequest) {
+  const backendBaseUrl = process.env.BACKEND_URL ?? "http://127.0.0.1:7860";
+  const formData = await request.formData();
+  const sessionId = request.nextUrl.searchParams.get("session_id") ?? "";
+
+  const targetUrl = sessionId
+    ? `${backendBaseUrl}/api/upload?session_id=${encodeURIComponent(sessionId)}`
+    : `${backendBaseUrl}/api/upload`;
+
+  const upstream = await fetch(targetUrl, {
+    method: "POST",
+    body: formData,
+    cache: "no-store"
+  });
+
+  const payload = await upstream.text();
+  return new Response(payload, {
+    status: upstream.status,
+    headers: {
+      "Content-Type": upstream.headers.get("content-type") ?? "application/json"
+    }
+  });
+}