A real-time AI interviewer that conducts live coding interviews with voice interaction, intelligent feedback, and performance-based assessment.
- Real-time Voice Interview: Natural conversation with AI interviewer using WebRTC
- Live Code Editor: Monaco Editor with syntax highlighting and real-time code snapshots
- Intelligent Feedback: AI provides contextual hints without giving away solutions
- Performance Assessment: Agent evaluates and decides interview progression
- Real-Time Code Awareness: Implemented Chat Context Injection. The agent now "sees" every code change through explicit system updates, eliminating hallucinations.
- Dynamic Problem Agnosticism: Agent automatically adapts to any coding problem or asks the candidate for a description if missing.
- Selective Feedback: Only speaks when detecting bugs, approach changes, or when candidate is stuck.
- Socratic Method: Guides candidates through hints rather than giving answers.
- Approach & Complexity: Strict Big-O analysis of algorithms and space/time.
- Code Correctness: Line-by-line identifies EVERY bug with formatted fixes (Line X: [Issue] -> [Fix]).
- Communication Analysis: Cites exact quotes from the transcript to evaluate clarity and professional tone.
- Hallucination Check: Cross-references candidate claims (e.g., "this is O(n)") against actual code implementation.
- Visual Score Radar: Professional result page with dimensional mapping.
Socratis uses a unified python agent for seamless context and analysis:
| Component | Technology | Purpose |
|---|---|---|
| Socratis Agent | Python, LiveKit, Groq (70B) | Real-time voice conversation, Socratic questioning, and Post-interview forensic analysis |
┌─────────────────────────────────────────────────────────────────────────────┐
│ SOCRATIS PLATFORM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ WebSocket ┌──────────────┐ │
│ │ Frontend │◄──────────────────►│ Backend │ │
│ │ (Next.js) │ REST API │ (Express) │ │
│ │ Port 3000 │ │ Port 4000 │ │
│ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │
│ │ WebRTC │ MongoDB │
│ │ (Voice) ▼ │
│ │ ┌──────────────┐ │
│ ▼ │ Database │ │
│ ┌──────────────┐ │ MongoDB │ │
│ │ LiveKit │ └──────────────┘ │
│ │ Cloud │ │
│ └──────┬───────┘ │
│ │ │
│ │ LiveKit Protocol │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ PYTHON VOICE AGENT │ │
│ ├──────────────────────────────────────────────────────────────┤ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │
│ │ │ VAD │ │ STT │ │ LLM │ │ TTS │ │ │
│ │ │ Silero │ │Deepgram │ │ Groq │ │ Deepgram │ │ │
│ │ └─────────┘ └─────────┘ │Llama3.1 │ │ aura-helios │ │ │
│ │ └─────────┘ └─────────────────┘ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
| Component | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 14, React, TailwindCSS | Interview UI, Code Editor, Voice Controls |
| Backend | Express.js, TypeScript, MongoDB | Session Management, Evaluation API |
| Voice Agent | Python, LiveKit Agents SDK | Real-time voice conversation & Forensic Reporting |
| STT | Deepgram | Real-time speech-to-text |
| TTS | Deepgram (aura-helios-en) | Natural voice synthesis |
| LLM | Groq (Llama 3.3 70B) | High-intelligence inference for interviewing and reporting |
| VAD | Silero | Voice activity detection |
- Node.js 18+
- Python 3.8+
- MongoDB running locally or connection string
- API Keys: LiveKit, Groq, Deepgram
# Clone the repository
git clone https://github.com/your-username/socratis.git
cd socratis
# Install backend dependencies
cd server && npm install
# Install frontend dependencies
cd ../client && npm install
# Install Python agent dependencies
cd ../server/agent && pip install -r requirements.txtServer .env (server/.env):
MONGODB_URI=mongodb://localhost:27017/socratis
GROQ_API_KEY=your_groq_api_key
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
LIVEKIT_URL=wss://your-project.livekit.cloudAgent .env (server/agent/.env):
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=your_livekit_api_key
LIVEKIT_API_SECRET=your_livekit_api_secret
DEEPGRAM_API_KEY=your_deepgram_api_key
GROQ_API_KEY=your_groq_api_keyClient .env.local (client/.env.local):
NEXT_PUBLIC_LIVEKIT_URL=wss://your-project.livekit.cloud# From root directory - starts ALL services
python start.pyThis single command starts:
- ✅ Backend Server (Port 4000)
- ✅ Frontend (Port 3000)
- ✅ Voice Agent (LiveKit)
Since services run in the background via the orchestrator, real-time logs are auto-generated in the root directory:
backend.log: Express API and Database connection logs.frontend.log: Next.js compilation and routing logs.agent.log: LiveKit Agent events, LLM context injection, and voice pipeline details.
Note: These logs are essential for identifying port conflicts or API failures that occur without a visible console.
Press Ctrl+C to stop all services.
Navigate to http://localhost:3000 to access the dashboard and start your interview!
socratis/
├── client/ # Next.js Frontend
│ ├── app/ # App Router pages
│ │ ├── interview/[id]/ # Interview room & results
│ │ └── page.tsx # Landing page
│ ├── components/ # React components
│ │ ├── interview/ # Interview-specific components
│ │ │ ├── InterviewRoom.tsx
│ │ │ ├── CodeEditor.tsx
│ │ │ └── VoiceComponent.tsx
│ │ └── CustomIcons.tsx # SVG icons & score donut
│ └── hooks/ # Custom React hooks
│
├── server/ # Express.js Backend
│ ├── src/
│ │ ├── routes/
│ │ │ └── interview.ts # Interview API endpoints
│ │ ├── models/
│ │ │ └── Session.ts # MongoDB schema
│ │ └── services/ # Business logic
│ └── agent/ # Python Voice Agent
│ ├── agent.py # Main agent entrypoint
│ ├── deepgram_patch.py # TTS compatibility fix
│ └── requirements.txt
│
└── README.md
| Endpoint | Method | Description |
|---|---|---|
/api/start |
POST | Create new interview session |
/api/session/:id |
GET | Get session details |
/api/submit |
POST | Submit code for final evaluation |
/api/submit-question |
POST | Submit current question, advance to next |
/api/advance-question |
POST | Agent-triggered question advancement |
/api/token |
GET | Get LiveKit access token |
Start Session:
POST /api/start
Response: {
"sessionId": "socratis-interview",
"question": { "title": "Two Sum", "description": "...", "examples": [...] },
"totalQuestions": 1,
"currentQuestionIndex": 0
}Submit for Evaluation:
POST /api/submit
Body: { "sessionId": "...", "code": "...", "transcript": [...] }
Response: {
"status": "completed",
"message": "Session submitted. Analysis pending."
}Note: The actual feedback is generated asynchronously by the agent and saved to the session. The frontend polls /api/session/:id to display results.
The AI agent follows a structured interview approach:
- Greeting: Introduces itself and the problem
- Clarification: Ensures candidate understands requirements
- Approach Discussion: Asks about planned algorithm & complexity
- Code Review: Watches for bugs and approach changes
- Completion: Reviews solution, asks follow-up questions
| Condition | Agent Action |
|---|---|
| Bug Detected | Asks guiding question about the issue |
| Approach Change | Acknowledges and asks about reasoning |
| 60s Silent | Offers gentle hint |
| Code Complete | Asks about complexity & edge cases |
Based on candidate performance, the agent decides:
- Strong Performance → Ends interview, no second question needed
- Mixed Performance → Advances to second question for fuller picture
- Weak Performance → Gives another chance with different problem
- Go to cloud.livekit.io
- Create a new project
- Copy
API Key,API Secret, andWebSocket URL
- Go to console.groq.com
- Generate an API key
- Free tier includes generous limits
- Go to console.deepgram.com
- Create a new API key
- Free tier includes $200 credit
- Brivio Light Theme: Clean, professional design with cobalt blue accents
- Responsive Layout: Resizable panels for problem description and code editor
- Real-time Indicators: Speaking/listening status, question progress
- Score Visualization: Radar chart for multi-dimensional performance view
# Backend tests
cd server && npm test
# Frontend tests
cd client && npm test# Build frontend
cd client && npm run build
# Build backend
cd server && npm run buildMIT License - See LICENSE for details.
Built with ❤️ by Vasu-devs