README.md

metadata

title: ai-interview-coach
emoji: 🏆
colorFrom: purple
colorTo: red
sdk: gradio
sdk_version: 6.18.0
app_file: app.py
pinned: false
python_version: '3.10'
license: mit
short_description: AI Interview Coach
tags:
  - track:backyard
  - achievement:offbrand
  - achievement:fieldnotes
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/686f49a3a31e9a517952dd0c/HfuMUE233jLKwNgjefSmy.png

🎙️ Project Showcases

• Live Video Demonstration: Watch on YouTube
• Official Social Media Pitch (LinkedIn Post): View on LinkedIn
• Official Blog Post on the BuildSmall Organisation: View my Blog Post

🎙️ AI Interview Coach — Version Alpha

An AI-powered interview preparation tool built with Gradio 6 and Qwen 2.5 7B via the HuggingFace Inference API.

🏆 Built for the Gradio × Hugging Face Build Small Hackathon (June 2026).

---

Features

• 🔐 Two-stage job description validation — blocks spam and prompt injection
• 🎚️ 3 interview modes — Quick (3Q), Standard (5Q), Deep Dive (7Q)
• 🤖 Adaptive questions — tailored to industry, role level, and detected keywords
• 📊 Keyword-aware scoring — answers scored against job-specific expected terms
• 🔑 Keyword coverage badges — see exactly which terms you hit and missed
• 💡 AI-generated Prep Sheet — works for ANY industry (not just tech)
• 📄 Timestamped PDF report — downloadable session summary
• 🎨 Premium dark UI — glassmorphism, animated blobs, Inter font

---

Quick Start (Local)

1. Clone and set up environment

cd HF_Hackathon
python -m venv .venv
.venv\Scripts\activate       # Windows
# source .venv/bin/activate  # Mac/Linux
pip install -r requirements.txt

2. Set your HuggingFace token

# Copy the example and fill in your token
copy .env.example .env
# Edit .env and replace hf_PASTE_YOUR_TOKEN_HERE with your actual token

Get a free token at: https://huggingface.co/settings/tokens
Required permission: Inference (read)

3. Run

python interview_coach.py

Open http://localhost:7860

---

HuggingFace Spaces Deployment

1. Push this repo to your HF Space (Gradio SDK)
2. Go to Settings → Secrets and add HF_TOKEN = your token
3. The app starts automatically — no other changes needed

---

Architecture

interview_coach.py   ← Gradio UI (pure layout + event wiring)
engine.py            ← Orchestration (LLM client, session, PDF)
config.py            ← All constants, CSS design system
agents/
  validator.py       ← 3-stage JD validation + profile extraction
  question_gen.py    ← Adaptive question generation
  scorer.py          ← Keyword-aware answer scoring (Agenda #4)

---

Model

• Model: Qwen/Qwen2.5-7B-Instruct
• Parameters: 7B (within HF Hackathon ≤32B limit)
• Inference: HuggingFace Serverless Inference API (free tier)
• Local fallback: Ollama (mistral:7b) if no HF token is set

---

Scoring System

Score	Meaning
8–10	Excellent — strong STAR structure + good keyword coverage
5–7	Good — missing key terms or depth
1–4	Needs work — expand and use role-specific language
NIL	Irrelevant response

Keyword Coverage Rule: < 40% of expected keywords → score capped at 5/10.