updated readme

.gitignore

@@ -6,6 +6,7 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 lerna-debug.log*
+recordings/*
 
 .env
 node_modules
@@ -17,7 +18,7 @@ dist-ssr
 .vscode/*
 *.pyc
 *.wav
-*.md
+generated_questions.md
 !.vscode/extensions.json
 .idea
 .DS_Store
@@ -26,4 +27,4 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
-generated_questions.md
+

README.md

@@ -1,11 +1,223 @@
 ---
-title: AgenticInterviewHackathon
-emoji: 🏃
+title: Agentic Interview System - AI-Powered Voice Interview & Candidate Scoring
+emoji: 🎙️
 colorFrom: yellow
 colorTo: purple
 sdk: docker
 pinned: false
 license: apache-2.0
+tags:
+  - mcp-in-action-track-enterprise
+  - gradio
+  - crewai
+  - agentic-ai
+  - mcp tool to estimate sentiment
+  - enterprise
+  - hiring
+  - voice-interview
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🎙️ Agentic Interview System
+## AI-Powered Voice Interview & Candidate Scoring Platform
+
+**🏆 MCP's 1st Birthday Hackathon Submission | Track: Enterprise Applications**
+
+[![Hugging Face Space](https://img.shields.io/badge/🤗-Hugging%20Face%20Space-yellow)](https://huggingface.co/UQ)
+[![Demo Video](https://img.shields.io/badge/📹-Demo%20Video-red)](https://www.youtube.com/@UsmanQayyum/videos)
+[![Social Post](https://img.shields.io/badge/🐦-Social%20Post-blue)](https://x.com/usmanqayyum)
+
+---
+
+## 🚀 Overview
+
+**Agentic Interview System** is an enterprise-grade AI-powered interview platform that automates the entire hiring workflow—from question generation to candidate evaluation. Built with **Gradio**, **CrewAI**, **FASTRTC** **Gemini 2.5 Flash**, ** Tool Calling** and **MCP (Model Context Protocol) Tool**, this system leverages intelligent multi-agent collaboration to conduct realistic voice interviews and provide comprehensive candidate assessments.
+
+### 🎯 Key Features
+
+- **📄 Smart Question Generation**: AI analyzes CV and Job Description to create tailored technical + behavioral questions
+- **🎤 Live Voice Interviews**: Real-time voice conversation with AI interviewer using FastRTC
+- **🤖 Multi-Agent Evaluation**: Specialized AI agents evaluate technical skills, behavioral fit, and sentiment
+- **📊 Comprehensive Scorecards**: Detailed feedback with competency scores, strengths/weaknesses, and hire recommendations
+- **🔌 MCP Integration**: Uses MCP server for sentiment analysis during candidate evaluation
+- **🌐 Web Research**: Serper tool enables agents to fetch current best practices for interview questions
+
+---
+
+## 🏗️ Architecture & Technology Stack
+
+### Core Technologies
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| **UI Framework** | Gradio  | Modern, interactive web interface |
+| **Multi-Agent System** | CrewAI | Orchestrates specialized interview agents |
+| **LLM** | Gemini 2.5 Flash | Powers question generation and evaluation |
+| **Voice Communication** | FastRTC | Real-time audio streaming for interviews |
+| **MCP Integration** | MCP Client/SSE | Connects to sentiment analysis MCP server **MCP Server**: `uq-sentimentanalysismcpserver.hf.space` |
+| **Web Research** | Serper Dev Tool | Enables agents to fetch current interview best practices |
+| **PDF Processing** | PyPDF | Extracts text from CV and Job Description PDFs |
+
+
+### Agent Architecture
+
+#### Question Generation Crew
+1. **Technical Interviewer Agent**: Generates role-specific technical questions
+2. **Personality & Culture Fit Specialist**: Creates behavioral questions using Serper tool for best practices
+3. **Interview Director**: Compiles final interview plan with system instructions
+
+#### Evaluation Crew
+1. **Technical Skills Evaluator**: Scores technical competency (0-10) for each technical question
+2. **Behavioral & Culture Fit Evaluator**: Assesses soft skills using MCP sentiment analysis tool
+3. **Evaluation Director**: Synthesizes evaluations into comprehensive scorecard
+
+---
+
+## 📋 How It Works
+
+### Step 1: Upload Documents
+Upload the candidate's CV/Resume and Job Description (PDF format). The system extracts text and prepares for analysis.
+
+### Step 2: Generate Questions
+AI agents analyze both documents:
+- **Technical Agent** identifies required skills and generates technical questions
+- **Personality Agent** researches current best practices and creates behavioral questions
+- **Director Agent** compiles a balanced interview plan
+
+### Step 3: Conduct Voice Interview
+- Start the live voice interview session
+- AI interviewer (Alex) conducts the conversation naturally
+- Questions are asked one at a time with active listening
+- Real-time audio streaming via FastRTC
+
+### Step 4: Agentic Evaluation
+After the interview:
+- **Technical Evaluator** scores technical responses
+- **Behavioral Evaluator** assesses soft skills and uses MCP for sentiment analysis
+- **Evaluation Director** generates comprehensive scorecard with:
+  - Individual question scores
+  - Overall technical/behavioral averages
+  - Strengths and areas for improvement
+  - Final hiring recommendation (Strong Hire/Hire/No Hire)
+
+---
+
+## 💼 Enterprise Value Proposition
+
+### For HR Teams & Talent Acquisition
+
+✅ **Automates Early-Stage Screening**: Reduces manual interview scheduling and coordination  
+✅ **Standardizes Evaluation**: Consistent, unbiased assessment across all candidates  
+✅ **Reduces Manual Workload**: AI handles question generation, interview conduction, and evaluation  
+✅ **Cuts Time-to-Hire**: Faster screening process enables quicker hiring decisions  
+✅ **Scalable Pipeline**: Handle multiple interviews simultaneously without additional resources  
+✅ **Data-Driven Decisions**: Objective scoring and detailed feedback for informed hiring
+
+### For Candidates
+
+✅ **Realistic Practice**: AI-driven mock interviews simulate real interview experience  
+✅ **Role-Specific Questions**: Practice with questions tailored to the actual job  
+✅ **Actionable Feedback**: Receive detailed scores and improvement areas  
+✅ **24/7 Availability**: Practice interviews anytime, anywhere
+
+---
+
+## 🎯 Use Cases
+
+- **HR Departments**: Streamline recruitment workflows
+- **Talent Acquisition Teams**: Scale interview processes
+- **Startups**: Build recruitment tools with AI capabilities
+- **Candidates**: Practice and prepare for interviews
+- **Organizations**: Adopt AI-driven hiring automation
+
+---
+
+## 🛠️ Installation & Setup
+
+### Prerequisites
+
+- Python 3.8+
+- Docker (for containerized deployment)
+- API Keys (Already set as secret in HF Spaces):
+  - Google Gemini API key
+  - Serper API key (for web research)
+  - Huggingface Token
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd AgenticInterviewHackathon
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Set up environment variables
+export GEMINI_API_KEY="your-gemini-api-key"
+export SERPER_API_KEY="your-serper-api-key"
+export HF_Token="your-serper-api-key"
+
+# Run the application
+python app.py
+```
+
+### Docker Deployment
+
+```bash
+# Build the Docker image
+docker build -t agentic-interview .
+
+# Run the container
+docker run -p 7860:7860 \
+  -e GEMINI_API_KEY="your-key" \
+  -e SERPER_API_KEY="your-key" \
+  -e HF_Token="your-key" \
+  agentic-interview
+```
+
+---
+
+## 📸 Demo & Resources
+
+- **🚀 Live Demo**: [Hugging Face Space](https://huggingface.co/UQ)
+- **📹 Demo Video**: [YouTube Channel](https://www.youtube.com/@UsmanQayyum/videos)
+- **🐦 Social Media Post**: [Twitter/X](https://x.com/usmanqayyum)
+
+---
+
+## 🏆 Hackathon Submission Details
+
+**Event**: MCP's 1st Birthday Hackathon  
+**Track**: MCP in Action - Enterprise Applications  
+**Tag**: `mcp-in-action-track-enterprise`  
+**Submission Date**: 29 November 2025
+
+
+## 📄 License
+
+Apache 2.0 License - See LICENSE file for details
+---
+
+## 🙏 Acknowledgments
+
+- **Gradio Team** for the amazing Gradio framework
+- **Anthropic** for MCP protocol and hackathon organization
+- **CrewAI** for the powerful multi-agent framework
+- **Google** for Gemini 2.5 Flash API
+- **HuggingFace** for hosting and infrastructure
+
+---
+
+## 🔮 Future Enhancements
+
+- [ ] Interview Link Generation to can be forwarded automatically to interviewee
+- [ ] Video interview capabilities
+- [ ] Integration with ATS (Applicant Tracking Systems)
+- [ ] Advanced analytics dashboard
+- [ ] Customizable evaluation rubrics
+- [ ] Team collaboration features
+
+---
+
+**Built with ❤️ for the MCP's 1st Birthday Hackathon**
+