Skip to content

README.md

Latest commit

 

History

History
325 lines (246 loc) · 12 KB

README.md

File metadata and controls

325 lines (246 loc) · 12 KB
Raw

TalentScout : Intelligent Hiring Assistant

An AI-powered chatbot that conducts initial candidate screenings for TalentScout, a technology recruitment agency. Built with Streamlit and Llama 3 via Groq, the assistant collects candidate information and generates tailored technical interview questions based on the candidate's declared tech stack.

Table of Contents

Overview

TalentScout's Hiring Assistant ("Scout") automates the initial phase of candidate screening by:

  1. Greeting the candidate and explaining the process
  2. Collecting essential information (name, email, phone, experience, desired position, location, tech stack)
  3. Generating 3-5 tailored technical questions per technology in the candidate's stack
  4. Evaluating responses with professional, encouraging feedback
  5. Concluding the session with a summary and next-steps information

The chatbot maintains full conversation context, validates inputs, handles edge cases gracefully, and stores session data securely.

Features

Core

  • Conversational Screening — Natural, step-by-step information gathering
  • Dynamic Technical Questions — Generated based on candidate's tech stack & experience level
  • Input Validation — Email, phone, and field-specific validation with gentle correction prompts
  • Context Awareness — Full conversation history maintained for coherent follow-ups
  • Fallback Handling — Graceful redirect for off-topic or unexpected inputs
  • Exit Detection — Keywords like "bye", "quit", "exit" trigger graceful conclusion
  • Session Persistence — Candidate data saved as JSON for recruiter review

Bonus

  • Sentiment Analysis — Real-time candidate mood tracking displayed in the sidebar
  • Multilingual Support — Auto-detects non-English input and provides bilingual responses
  • Premium UI — Custom dark theme with glassmorphism, animations, and gradient accents

Architecture

graph TD
    A["👤 Candidate"] -->|interacts| B["Streamlit UI"]
    B -->|user message| C["Conversation Manager"]
    C -->|builds prompt| D["Prompt Engine"]
    D -->|API call| E["Llama 3 (Groq)"]
    E -->|response| C
    C -->|updates| F["Session State"]
    F -->|renders| B
    C -->|stores| G["Data Store (JSON)"]

    subgraph "Bonus Modules"
        H["Sentiment Analyzer"]
        I["Multilingual Detector"]
    end
    C --> H
    C --> I
Loading

Conversation State Machine

The conversation progresses through these ordered phases:

GREETING → NAME → EMAIL → PHONE → EXPERIENCE → POSITION → LOCATION → TECH STACK → QUESTIONS → ANSWERS → FAREWELL

Each phase has:

  • A tailored prompt template
  • Input validation rules
  • Automatic phase transition on valid input
  • Fallback handling for invalid input

Installation

Prerequisites

Steps

  1. Clone the repository

    git clone https://github.com/rishii100/talentscout.git
cd talentscout

  2. Create a virtual environment (recommended)

    python -m venv venv
source venv/bin/activate

  3. Install dependencies

    pip install -r requirements.txt

  4. Set up your API key

    cp .env.example .env

  5. Run the application

    streamlit run app.py

  6. Open in browser — Navigate to http://localhost:8501

Usage Guide

  1. Start — The assistant greets you and begins the screening
  2. Provide Information — Answer each question one at a time (name, email, phone, etc.)
  3. Declare Tech Stack — List the languages, frameworks, and tools you know
  4. Answer Questions — Respond to the generated technical questions
  5. Finish — The session ends with a summary and next-steps info

Tips

  • You can type "bye", "exit", or "quit" at any time to end the session
  • The sidebar shows your screening progress and collected information
  • If you make a mistake, the assistant will gently ask for correction

Technical Details

Libraries & Tools

Library Version Purpose
streamlit ≥1.30.0 Frontend UI framework
groq ≥0.4.0 Groq API SDK (Llama 3)
python-dotenv ≥1.0.0 Environment variable management

Model: Llama 3 via Groq

Why Groq & Llama?

  • Incredible Speed — Groq's LPU architecture provides instant, real-time responses
  • Quality — llama-3.3-70b-versatile offers top-tier instruction following and context retention
  • Efficiency — Uses the smaller llama-3.1-8b-instant model for quick auxiliary tasks (sentiment/language detection) to save API quota
  • Free tier — Generous free tier for development

Configuration:

  • Temperature: 0.7 (balanced creativity/consistency for conversations)
  • Max tokens: 2048 (sufficient for detailed technical questions)
  • Analytical tasks (sentiment, language): Temperature 0.3 for precision

Design Patterns

  • State Machine — ConversationManager drives the conversation through ordered phases
  • Template Method — Phase-specific prompts injected into a consistent prompt structure
  • Strategy Pattern — Validation rules differ per phase via _extract_and_validate()
  • Session State — Streamlit's st.session_state for conversation persistence across rerenders

Prompt Design

Philosophy

Prompts are crafted with three principles:

  1. Specificity — Each phase has a tailored prompt that tells the LLM exactly what to do
  2. Constraint — Clear rules prevent the LLM from going off-topic or revealing system details
  3. Context — Phase context is injected alongside user input so the LLM understands the current state

System Prompt

The system prompt defines "Scout's" persona, rules, and behavioral constraints:

  • Professional yet warm personality
  • Strict topic adherence (hiring/screening only)
  • One-field-at-a-time information gathering
  • Input validation with gentle correction
  • No code generation or tutoring — assessment only

Phase Prompts

Each conversation phase has a dedicated prompt that:

  • Tells the LLM what the candidate just provided
  • Specifies what to validate
  • Defines what to ask next
  • Handles edge cases (invalid input, off-topic responses)

Technical Question Generation

The tech question prompt dynamically adjusts based on:

  • Tech stack — Questions cover the specific technologies listed
  • Experience level — Difficulty scales with years of experience
  • Breadth — Questions cover debugging, architecture, best practices, and trade-offs

Fallback Prompt

When input doesn't match the expected phase:

  • Acknowledges the candidate's message politely
  • Redirects to the current screening step
  • Never dismisses or ignores the candidate

Data Privacy & GDPR

  • Local Storage — All data stored locally in data/candidates/ as JSON files
  • Anonymization — Email and phone are masked in stored data (original kept for recruiter access)
  • Right to Erasure — delete_candidate_session(session_id) function available
  • No External Transmission — Data never leaves the local system (except API calls to Groq for response generation)
  • Gitignored — The data/candidates/ directory is excluded from version control
  • Minimal Collection — Only essential screening information is gathered

Bonus Features

Sentiment Analysis

  • Each candidate message is analyzed for emotional tone
  • Categories: Positive, Neutral, Negative, Frustrated, Excited, Confused
  • Displayed as a color-coded badge in the sidebar
  • Logged in session data for recruiter insight

Multilingual Support

  • Auto-detects the candidate's language from their messages
  • Supports 20+ languages including Hindi, Spanish, French, German, and more
  • When non-English is detected, responses include bilingual translations
  • Language detection runs on early messages to minimize API calls

Premium UI

  • Custom dark theme with Inter font
  • Glassmorphism effects and gradient accents
  • Smooth message slide-in animations
  • Progress bar with gradient fill
  • Responsive chat bubble design
  • Custom scrollbar styling

Secure Admin Dashboard

  • Integrated directly into the Streamlit UI via a sidebar toggle
  • Protected by environment variable credentials (ADMIN_USERNAME and ADMIN_PASSWORD)
  • Allows recruiters to instantly view saved candidate JSON files and transcripts
  • Eliminates the need for external database setup during local development and cloud demos

Challenges & Solutions

1. Maintaining Context Across Phases

Challenge: The LLM needed to understand which phase the conversation was in without confusing past context. Solution: Phase-specific context is injected into each prompt call, then stripped from the stored history to keep it clean. The LLM sees [SYSTEM CONTEXT — phase: X] directives that are replaced with the user's actual message in the stored history.

2. Preventing Off-Topic Responses

Challenge: LLMs naturally want to be helpful with any question, even off-topic ones. Solution: The system prompt includes strict rules about topic adherence, and the fallback mechanism provides a polite redirect template that the LLM follows consistently.

3. Input Validation Without Being Annoying

Challenge: Validating email/phone formats while keeping the conversation natural. Solution: Two-layer validation — regex-based extraction in code, plus LLM-level validation prompts that ask for corrections conversationally rather than showing error messages.

4. Exit Keyword False Positives

Challenge: Phrases like "thank you for asking" would trigger exit detection. Solution: Exit detection only triggers on short messages (≤5 words) containing exit keywords, preventing false positives from longer contextual sentences.

5. Technical Question Quality

Challenge: Generating questions that are neither too easy nor too hard. Solution: The prompt includes the candidate's experience level and explicitly requests intermediate-to-advanced questions covering practical aspects (debugging, architecture, trade-offs), not just theoretical knowledge.

Project Structure

talentscout/
├── app.py                      # Streamlit entry point
├── config.py                   # API keys, constants, model configuration
├── requirements.txt            # Python dependencies
├── .env.example                # Environment variable template
├── .gitignore                  # Git ignore rules
├── README.md                   # This file
│
├── core/                       # Core business logic
│   ├── __init__.py
│   ├── conversation.py         # Conversation state machine
│   ├── prompts.py              # All prompt templates
│   ├── llm.py                  # Groq (Llama) API wrapper
│   └── data_store.py           # JSON data persistence
│
├── modules/                    # Bonus feature modules
│   ├── __init__.py
│   ├── sentiment.py            # Sentiment analysis
│   └── language.py             # Language detection & bilingual support
│
├── ui/                         # UI layer
│   ├── __init__.py
│   ├── components.py           # Reusable Streamlit components
│   └── styles.py               # Custom CSS injection
│
├── data/
│   └── candidates/             # Stored session data (gitignored)
│
└── assets/
    └── logo.png                # TalentScout branding

License

This project was built as part of an AI/ML internship assignment. All code is original and open for review.