AIRA - AI Interview Recruitment Assistant

An interactive, real-time AI technical interviewer that conducts targeted interviews based on a candidate's Resume, Job Description, and GitHub portfolio. It features a fully animated 3D avatar with real-time lip-syncing for a highly immersive experience.

---

🚀 Overview

The AI Interview Platform is designed to simulate a professional technical interview. It uses a Vectorless Retrieval-Augmented Generation (RAG) pipeline to deeply understand the candidate's background by extracting text directly from their uploaded Resume and Job Description.

🧠 Why Vectorless RAG?

Traditional RAG systems slice documents into math vectors and store them in heavy databases (like ChromaDB or Pinecone). This "Vector RAG" approach often destroys the flow of chronological documents like resumes, uses hundreds of megabytes of RAM, and slows down deployments. By utilizing a Vectorless Architecture (LangGraph Map-Reduce), AIRA extracts the raw text and hands it directly to the LLM. This provides the AI with a perfect, holistic view of the candidate's entire career timeline, guarantees instant execution times, and allows the platform to run seamlessly on a 512MB RAM free-tier cloud server without crashing.

It leverages the blazing-fast Groq API (Llama-3.3-70B-Versatile) to generate highly specific, context-aware technical questions, and uses LangGraph to maintain a stateful interview loop. The responses are vocalized by a dynamic 3D Avatar using Sarvam AI Text-to-Speech and the Rhubarb Lip-Sync engine.

---

🏗️ System Architecture & Multi-Agent Workflow

Our architecture completely discards traditional, blocking LLM patterns. Instead, it leverages a sophisticated, decoupled LangGraph Multi-Agent Engine powered by dynamic agent spawning and a continuously replenishing background queue.

1. Phase 1: Dynamic Parallel Ingestion (Map-Reduce)

During document upload, the system does not process files sequentially. Instead, it utilizes the LangGraph Send API to perform dynamic, parallel agent orchestration.

• Dynamic Agent Spawning: The router intercepts the upload payload and instantly spawns exactly N specialized agents. If a user uploads 1 Resume, 1 JD, and 5 GitHub Repositories, the system instantly spawns 7 independent agents operating on distinct background threads.
• Asymmetric Execution: Network-bound agents (GitHub scrapers) and CPU-bound agents (PDF extractors) execute completely concurrently. The total ingestion latency is governed solely by the single slowest document, achieving a pure O(1) time complexity relative to the number of documents.
• Context Reduction (Vectorless): Once all spawned agents complete, a central Reducer node aggregates the multimodal text into a highly compressed, holistic semantic context summary, completely bypassing slow math embeddings and heavy vector databases.

2. Phase 2: The Continuous Adaptive Queue (Zero-Delay UI)

Traditional AI interviews suffer from a "stop-and-think" bottleneck where the UI freezes while the LLM generates the next question. We solved this by implementing a Hybrid, Non-Blocking Adaptive Queue.

• O(1) Instant UI Return: When a candidate submits an answer, the FastAPI endpoint bypasses the LLM entirely. It performs a simple pop() operation on a pre-populated MongoDB question queue and returns the next question instantly. User-facing latency is exactly 0.0 seconds.
• Background Orchestration (adaptive_graph.py): The moment the next question is dispatched to the user, FastAPI detaches the heavy LLM execution to a BackgroundTask. While the user is busy reading/answering the new question, an independent LangGraph workflow fires up in the background.
• Simultaneous Background Agents:
  1. Evaluator Agent: Retrieves the previous answer, grades it out of 10, identifies specific strengths, weaknesses, and flags hallucinated/AI-generated phrasing.
  2. Strategic Generator Agent: Receives the evaluation and dynamically shifts the interview strategy. If the candidate scored high, it increases technical complexity. If they scored poorly, it drops to foundational concepts.
  3. Queue Replenisher: The generator yields 1-2 new, hyper-tailored questions and pushes them into the active MongoDB queue, ensuring the pre-generated stack never runs dry.

graph TD
    %% Styling
    classDef ui fill:#4f46e5,stroke:#fff,stroke-width:2px,color:#fff;
    classDef db fill:#059669,stroke:#fff,stroke-width:2px,color:#fff;
    classDef agent fill:#db2777,stroke:#fff,stroke-width:2px,color:#fff;

    subgraph "Phase 1: Dynamic Parallel Ingestion"
        Upload([User Uploads Documents]) --> Router{Router: Dynamic Dispatch}
        
        Router -- "Send API (Parallel Thread 1)" --> A1[Extractor Agent: Resume]:::agent
        Router -- "Send API (Parallel Thread 2)" --> A2[Extractor Agent: JD]:::agent
        Router -- "Send API (Parallel Thread 3..N)" --> A3[Scraper Agent: GitHub 1..N]:::agent
        
        A1 & A2 & A3 --> Reducer[Reducer: Context Aggregation]
        Reducer --> Context[(In-Memory Context)]:::db
    end

    Context --> InitQueue

    subgraph "Phase 2: Hybrid Adaptive Queue (Zero-Delay Loop)"
        InitQueue[Generator Agent: Build Initial 5 Questions]:::agent --> QQueue[(MongoDB: Active Question Queue)]:::db
        
        UI((Frontend UI: Candidate Interface)):::ui -- "1. Submits Answer" --> FastPop
        
        FastPop{FastAPI Endpoint} -- "2. pop() 0.0s delay" --> QQueue
        QQueue -- "3. Returns Next Question" --> FastPop
        FastPop -- "4. Instantly Shows Next Question" --> UI
        
        FastPop -- "5. Spawns Detached Task" --> BackgroundTask[[FastAPI Background Task]]
        
        BackgroundTask --> EvalAns[Evaluator Agent: Grade Answer & Find Weaknesses]:::agent
        EvalAns --> GenAns[Generator Agent: Shift Strategy based on Score]:::agent
        GenAns -- "6. Replenishes 1-2 new Adaptive Questions" --> QQueue
    end
    
    UI -- "Interview Finished" --> FinalReport[Reporting Agent: 15-Parameter JSON Report]:::agent

Loading

---

🎯 Core Features

• Zero-Delay Interactions: Next-generation background queueing ensures the user never has to wait for an LLM to generate the next question.
• Multi-Agent Ingestion: Parallel processing of Resumes, JDs, and GitHub repositories using LangGraph.
• Context-Aware Interviewing: Hyper-personalized technical questions derived directly from the candidate's actual resume and GitHub code.
• Immersive 3D Avatar: Real-time rendering of an expressive 3D tutor/interviewer using Three.js and React.
• Automated Evaluation: 15-parameter feedback report (Confidence, AI Detection, Technical Depth, etc.) available on the dashboard.

---

💻 Tech Stack

Frontend

• React.js (Vite) - Core UI framework
• React Three Fiber / Drei - 3D model rendering and scene management
• Tailwind CSS - Styling and layout

Backend

• FastAPI (Python) - High-performance asynchronous API
• LangGraph - Complex state machine orchestration for the interview loop
• Rhubarb Lip Sync - Command-line tool to generate mouth cues from audio

AI Services

• Groq API (llama-3.3-70b-versatile) - LLM for reasoning and question generation
• Sarvam AI - High-quality regional text-to-speech generation

---

📦 Prerequisites

Before installing, ensure you have the following installed on your system:

• Python 3.10+ (Conda recommended)
• Node.js 18+ & npm
• FFmpeg (Required for audio conversion: sudo apt install ffmpeg)
• Rhubarb Lip Sync binary placed in backend/bin/rhubarb

---

🛠️ Installation & Setup

1. Clone the repository

git clone https://github.com/your-username/AI_Tutor.git
cd AI_Tutor

2. Environment Variables

Copy the example environment file and add your API keys:

cp example.env .env

Open .env and fill in:

• SARVAM_API_KEY: Get from Sarvam AI
• GROQ_API_KEY: Get from Groq Console

3. Backend Setup

Create a virtual environment, install dependencies, and start the FastAPI server:

cd backend
conda create -n ai-interview python=3.12
conda activate ai-interview
pip install -r requirements.txt
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

4. Frontend Setup

Open a new terminal window, install npm packages, and start the Vite dev server:

cd frontend
npm install
npm run dev

---

▶️ Usage Instructions

1. Open your browser and navigate to http://localhost:5174 (or the port Vite provides).
2. On the welcome screen, upload your Resume (PDF).
3. Paste the Job Description you are applying for in the text box.
4. (Optional) Provide a link to your GitHub profile for deeper context.
5. Click "Start Interview".
6. The backend will process your documents and the 3D Avatar will greet you and ask the first technical question!
7. Type your answers into the chat interface to progress through the interview rounds.

---

📂 Directory Structure

AI_Tutor/
├── backend/
│   ├── main.py                 # FastAPI application entry point
│   ├── routers/                # API route handlers (interview.py)
│   ├── services/               # Core business logic
│   │   ├── rag.py              # Document parsing and text extraction
│   │   ├── interview_graph.py  # LangGraph state machine definition
│   │   ├── ollama_client.py    # Groq LLM integration client
│   │   └── sarvam_tts.py       # Sarvam AI TTS and FFmpeg/Rhubarb sync
│   ├── bin/                    # Pre-compiled binaries (Rhubarb)
│   └── audios/                 # Temporary storage for generated TTS files
├── frontend/
│   ├── src/
│   │   ├── components/         # React components (Avatar.jsx, UI.jsx)
│   │   ├── hooks/              # Custom React hooks (useChat.jsx)
│   │   └── index.css           # Global Tailwind styles
│   └── public/                 # Static assets and 3D models
├── .env                        # Environment configurations
└── README.md

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📜 License

This project is licensed under the MIT License.