Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

AI Interviewer Agent

A structured AI interviewer web application built with Next.js, Gemini, and Supabase. The app conducts a technical interview through chat, enforces mandatory interview coverage, stores the full transcript, and generates a transcript-grounded hiring evaluation report.

This project is designed around the core assignment requirement: the important part is not just the chat interface, but the interview control logic, evidence tracking, and final evaluation quality.

What It Does

  • Starts a candidate interview session.
  • Accepts job descriptions and resumes by paste, .txt, or selectable-text PDF upload.
  • Opens with a consistent interview handshake.
  • Conducts the rest of the interview through Gemini-generated interviewer turns.
  • Maintains the conversation transcript and session state in Supabase.
  • Covers required interview areas:
    • candidate introduction
    • academic background
    • technical / coding background
    • programming languages known
    • 1-5 self-rating for each mentioned language
    • logical follow-up questions grounded in prior answers
  • Blocks final evaluation until mandatory coverage is complete.
  • Generates a structured evaluation report with score, recommendation, strengths, weaknesses, technical assessment, communication assessment, cultural fit, sentiment, risks, missing evidence, and next-round focus.

Important Note on Hardcoded Responses

The opening handshake is fixed by application code for consistency; all interview Q&A after the candidate's first reply is model-generated and transcript/context-driven. This avoids the model skipping the required introduction step while still keeping the actual interview dynamic.

Tech Stack

  • Next.js 16 App Router
  • TypeScript
  • React 19
  • Tailwind CSS 4
  • Google Gemini API via @google/generative-ai
  • Supabase PostgreSQL
  • Zod for response validation

Core Architecture

Browser UI
  -> /api/interview/start
  -> /api/interview/message
  -> /api/interview/end
  -> /api/interview/[id]

Next.js API Routes
  -> Supabase session/message storage
  -> Gemini interviewer generation
  -> coverage tracking
  -> final evaluation generation

Supabase
  -> interview_sessions
  -> messages
  -> evaluation_json
  -> agent_state_json

Interview Control Logic

The app does not rely only on a generic LLM prompt.

It uses three layers:

  1. Structured interviewer prompt Guides the model to stay in interviewer role, ask one question at a time, and cover the mandatory interview areas.

  2. Server-side coverage tracking src/lib/coverage-state.ts analyzes the transcript for required coverage. It tracks whether each mandatory area is missing, partial, or complete.

  3. Completion gating /api/interview/end refuses to generate the final report until required coverage is complete. If the candidate tries to end early, the API returns the missing areas and the next required question.

This makes the product more controlled than a simple chatbot wrapper.

Evaluation Report

The final evaluator receives:

  • full transcript
  • job description, if provided
  • resume text, if provided
  • per-turn rubric rollup
  • verified coverage summary

The evaluator must return validated JSON matching the application schema.

Report fields include:

  • overallScore
  • confidenceScore
  • strengths
  • weaknesses
  • riskFlags
  • hiringRecommendation
  • technicalAssessment
  • communicationAssessment
  • culturalFit
  • sentimentAnalysis
  • performanceSummary
  • detailedReasoning
  • missingEvidence
  • nextRoundFocus

Voice Mode

Voice interview mode extends the same structured interview engine used by typed chat.

Flow:

Candidate records answer
  -> /api/stt
  -> Deepgram speech-to-text
  -> /api/interview/message
  -> Gemini interviewer response
  -> /api/tts
  -> Deepgram Aura text-to-speech
  -> browser plays interviewer audio

The voice path keeps transcript storage, coverage tracking, completion gating, and final evaluation identical to the text path.

Implementation details:

  • Uses MediaRecorder in the browser for answer capture.
  • Uses Deepgram STT through /api/stt.
  • Uses Deepgram Aura TTS through /api/tts.
  • Shows both the transcribed answer and interviewer response in the chat.
  • Lets the candidate interrupt spoken interviewer audio by tapping the mic; current audio playback is cancelled before recording starts.
  • Keeps typed answers available as a fallback during voice sessions.

This is a batch recording flow, not a full duplex LiveKit stream. src/lib/audio/streaming-audio-placeholder.ts is reserved for a future LiveKit + streaming STT/TTS implementation.

Data Storage

Supabase stores:

  • interview session metadata
  • chat transcript
  • job description and resume text
  • agent/rubric state
  • final evaluation JSON

Schema:

supabase/schema.sql

RLS is enabled. The app uses the Supabase service role key only inside server routes.

Setup

1. Install Dependencies

npm install

2. Configure Supabase

Create a Supabase project and run:

supabase/schema.sql

If updating an older local schema, also apply:

supabase/migration_add_jd_resume.sql
supabase/migration_agent_state.sql

3. Configure Environment

Copy .env.example to .env.local and fill in:

GEMINI_API_KEY=
NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
GEMINI_MODEL=gemini-2.5-flash

Notes:

  • SUPABASE_SERVICE_ROLE_KEY must be a secret/service role key, not an anon or publishable key.
  • GEMINI_MODEL is optional. The default is gemini-2.5-flash.

4. Run Locally

npm run dev

Open:

http://localhost:3000

Available Scripts

npm run dev
npm run build
npm run start
npm run lint

API Routes

Method Route Purpose
POST /api/interview/start Creates a session and stores the fixed opening message
POST /api/interview/message Stores candidate answer, updates coverage, generates next interviewer turn
POST /api/interview/end Generates final evaluation only if required coverage is complete
GET /api/interview/[id] Returns session metadata, messages, and parsed evaluation
POST /api/resume/parse Extracts resume text from PDF or .txt uploads
POST /api/stt Transcribes recorded audio with Deepgram
POST /api/tts Synthesizes interviewer speech with Deepgram Aura
GET /api/dev/gemini-models Development helper for checking available Gemini models

Project Structure

src/app/                      Next.js routes and API handlers
src/components/               Chat, setup, voice, and report UI
src/lib/prompts.ts            Interviewer and evaluator prompts
src/lib/gemini.ts             Gemini calls and response parsing
src/lib/coverage-state.ts     Mandatory coverage extraction and gating logic
src/lib/evaluation.ts         Evaluation schema validation
src/lib/audio/                Deepgram STT/TTS service abstraction
src/lib/agent-state.ts        Per-turn rubric rollup state
src/lib/rubric.ts             Turn-level scoring schema
src/lib/supabase/admin.ts     Server-side Supabase client
supabase/schema.sql           Database schema

Resume Uploads

The setup form supports manual resume paste, plain .txt upload, and selectable-text PDF upload. PDF parsing runs on the server through /api/resume/parse; scanned/image-only PDFs are not OCR processed and should be pasted manually.

Security Notes

  • Gemini and Supabase secret keys are read only on the server.
  • The browser never receives GEMINI_API_KEY or SUPABASE_SERVICE_ROLE_KEY.
  • Supabase RLS is enabled. Direct browser access to tables is not used.
  • This assignment version does not include candidate authentication; session IDs are used as access tokens for the interview/report pages.

Known Limitations

  • Coverage detection is deterministic and heuristic. It is intentionally server-side, but a production version should use a stronger semantic extractor and tests against real transcripts.
  • Voice mode uses recorded audio chunks rather than full-duplex streaming; a future LiveKit version would reduce latency and support more natural overlapping speech.
  • There is no reviewer/admin dashboard yet.
  • There is no mock AI mode; reviewers need valid Gemini and Supabase credentials to run the full flow.

Verification

The project should pass:

npx tsc --noEmit
npm run lint
npm run build

On some Windows/sandboxed environments, Next.js may need permission to spawn build workers. The application code itself builds cleanly once worker spawning is allowed.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages