README.md

---
title: ATS Resume Intelligence Engine
emoji: 📄
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: mit
suggested_hardware: cpu-upgrade
---

# ATS Intelligence Engine

<p align="center">
  <b>An AI-powered Applicant Tracking System that scores resumes against job descriptions using semantic similarity.</b><br>
  Built with FastAPI, LangChain, and Hugging Face — deployable as a Docker Space.
</p>

---

## Features

* Upload resume & job description (PDF or text)
* Extract text using PyMuPDF
* Semantic similarity via Sentence Transformers
* Keyword matching for skill overlap
* Final ATS score with LangChain + Hugging Face LLM feedback
* REST API built with FastAPI
* Docker Space ready (port **7860**)

---

## Tech Stack

| Layer            | Technology                          |
| ---------------- | ----------------------------------- |
| Backend          | FastAPI, Uvicorn                    |
| ML / Embeddings  | Sentence Transformers, Scikit-learn |
| LLM / Feedback   | LangChain, Hugging Face Inference API |
| PDF Parsing      | PyMuPDF                             |
| Frontend         | HTML / JS (served by FastAPI)       |
| Deployment       | Docker, Hugging Face Spaces         |

---

## Deploy on Hugging Face Spaces (Docker)

### 1. Create a new Space

1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
2. Choose **Docker** as the SDK
3. Pick a name (e.g. `ats-resume-intelligence`)
4. Hardware: **CPU upgrade** (recommended for Sentence Transformers)

### 2. Push this repository

```bash
git remote add space https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
git push space main
```

Or clone the empty Space repo and copy these files into it, then commit and push.

### 3. Add your Hugging Face token (required for AI feedback)

In the Space → **Settings** → **Repository secrets**, add:

| Secret name | Value |
| ----------- | ----- |
| `HF_TOKEN`  | Your Hugging Face access token ([create one](https://huggingface.co/settings/tokens)) with **Inference** permission |

The Space will rebuild automatically after you push or add secrets.

### 4. Open your live app

Your Space URL will be:

`https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`

The UI and API run on the same origin (port 7860), so no CORS or proxy setup is needed.

---

## Run locally with Docker

### Prerequisites

* Docker
* Hugging Face API token

### Setup

Create a `.env` file:

```env
HF_TOKEN=your_huggingface_token_here
```

### Start

```bash
docker compose up --build
```

Open **http://localhost:7860**

---

## API Endpoints

### `POST /predict/ats` — JSON

```json
{
  "resume_text": "...",
  "job_description": "..."
}
```

### `POST /predict/ats/upload` — multipart

| Field           | Type   | Description          |
| --------------- | ------ | -------------------- |
| resume_pdf      | File   | Resume PDF           |
| resume_text     | string | Resume text          |
| jd_pdf          | File   | Job description PDF  |
| job_description | string | Job description text |

### Response

```json
{
  "semantic_score": 0.82,
  "keyword_score": 0.74,
  "final_ats_score": 0.79,
  "summary": "..."
}
```

### `GET /health` — health check

---

## Development (without Docker)

```bash
pip install -r requirements.txt
set HF_TOKEN=your_token_here
uvicorn main:app --reload --port 7860
```

For local dev without the Space URL, in `Frontend/app.js` set:

```js
const API = 'http://localhost:7860';
```

---

## Environment variables

| Variable | Description |
| -------- | ----------- |
| `HF_TOKEN` | Hugging Face API token (Space secret or `.env`) |

---

## License

MIT License