README (2).md

# ⚡ AI Recruitment Agent

A production-grade hybrid candidate matching pipeline using **Groq LLM**, **Pinecone vector DB**, and a **Gradio 4.16.0** UI.

## Architecture

```
CSV Input → Stage 1: Normalize (Groq)
          → Stage 2: Embed + Match (Pinecone + SentenceTransformers) → Top 20
          → Stage 3: Deterministic Rerank (Groq) → Top 10
          → Stage 4: LLM Deep Review (Groq) → Top 5
          → Stage 5: Final Synthesis (Groq) → Shortlist
```

## Setup

### 1. Install dependencies

```bash
pip install -r requirements.txt
```

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env and fill in your API keys
```

### 3. Create Pinecone index

In your Pinecone console:
- Create an index named `recruitment-index` (or whatever you set in `PINECONE_INDEX`)
- Dimension: **1024** for `BAAI/bge-m3`, **768** for `bge-large-en`, **384** for `all-MiniLM-L6-v2`
- Metric: **cosine**

### 4. Run the Gradio UI

```bash
python gradio_app.py
```

Open http://localhost:7860 in your browser.

### 5. (Optional) Run the FastAPI backend

```bash
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
```

API docs at http://localhost:8000/docs

## CSV Format

Your CSV should have these columns (exact names or common variants):

| Column | Variants |
|--------|----------|
| `name` | `full_name`, `candidate_name` |
| `email` | `email_address` |
| `skills` | `parsed_skills`, `technical_skills` |
| `experience` | `parsed_work_experience`, `years_of_experience` |
| `education` | `parsed_metadata_education` |
| `resume_text` | `parsed_summary`, `summary` |

## Key Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `GROQ_API_KEYS` | Comma-separated keys for rotation | — |
| `GROQ_MODEL` | Model name | `llama3-70b-8192` |
| `PINECONE_API_KEY` | Pinecone API key | — |
| `PINECONE_INDEX` | Index name | `recruitment-index` |
| `EMBEDDING_MODEL` | SentenceTransformer model | `BAAI/bge-m3` |
| `STAGE2_TOP_K` | Candidates retrieved by embeddings | `20` |
| `GRADIO_PORT` | UI port | `7860` |
| `GRADIO_SHARE` | Enable public share link | `False` |

## Pipeline Stages

| Stage | Method | Input | Output |
|-------|--------|-------|--------|
| 1. Normalize | Groq LLM | All candidates | Structured features |
| 2. Embed & Match | Pinecone + BAAI/bge-m3 | All candidates | Top 20 by similarity |
| 3. Rerank | Groq LLM (deterministic scoring) | Top 20 | Top 10 with scores |
| 4. Deep Review | Groq LLM | Top 5 | Verdicts + signals |
| 5. Final Synthesis | Groq LLM | Top 5 reviews | Final ranked shortlist |