Masaar — AI Adaptive Assessment Platform

Sprints Internship · Round 1

An agentic assessment platform where the entire assessment runs as a single adaptive chat. A LangGraph examiner agent drives the session, invokes five specialised tools, adapts difficulty in real time, grades silently against rubrics, and delivers a verified five-dimension radar report.

---

Tech Stack

Layer	Technology
Backend API	FastAPI + WebSockets
Agent / Orchestration	LangGraph (LangChain)
LLM Abstraction	LiteLLM
Database	PostgreSQL 16 (async via SQLAlchemy + asyncpg)
Background Workers	Celery 5 + Redis 7
Vector Store	Qdrant
Speech-to-Text	Deepgram (via LiteLLM proxy)
Code Sandbox	E2B
Observability	Langfuse + Prometheus
Frontend	Next.js 15 (App Router) + React 19
Styling	Tailwind CSS 3.4 + Plus Jakarta Sans
State Management	Zustand 5
Charts	Recharts
Infrastructure	Docker + Docker Compose + Nginx

---

Getting Started

Prerequisites

• Docker Desktop (or Docker Engine + Compose)

Quick Start

# Clone the repo
git clone https://github.com/MoHatemTC/adaptive-assessment-internship-round-1.git
cd adaptive-assessment-internship-round-1

# Set up environment variables
cp .env.example .env
# Fill in API keys: LITELLM_API_KEY, DEEPGRAM_API_KEY, E2B_API_KEY, etc.

# Start all services with hot reload
docker compose -f docker-compose.yml -f docker-compose.dev.yml up

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health

Commands

# Start in background
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d

# Stop everything
docker compose down

# Run backend tests
docker compose exec backend pytest tests/ -v

# Run migrations
docker compose exec backend alembic upgrade head

# View logs
docker compose logs backend -f

# Rebuild after dependency changes
docker compose build

# Run Celery worker (separate profile)
docker compose --profile worker up

---

Project Structure

adaptive-assessment-internship-round-1/
├── backend/
│   ├── app/
│   │   ├── core/               # Kernel — READ ONLY
│   │   ├── features/
│   │   │   ├── voice/          # Voice interview with real-time STT
│   │   │   ├── mcq/            # MCQ protocol with adaptive generation
│   │   │   ├── diagram/        # SVG diagram interpretation
│   │   │   ├── camera/         # Camera interview (stub)
│   │   │   └── code/           # E2B sandbox code execution
│   │   ├── agent/              # LangGraph examiner orchestrator
│   │   ├── admin/              # Assessment CRUD + planner agent
│   │   ├── sessions/           # Learner sign-in + lifecycle
│   │   ├── proctoring/         # Multi-provider integrity monitoring
│   │   ├── reports/            # Radar report + PDF generation
│   │   ├── shared/             # Schemas, Qdrant, embedder, CV parser
│   │   ├── workers/            # Celery background tasks
│   │   └── evals/              # LLM-based G-Eval grading
│   ├── migrations/             # Alembic (20 migration scripts)
│   └── tests/
├── frontend/
│   └── src/
│       ├── app/                # App Router pages (landing, assessment, admin)
│       ├── components/         # Shared UI + tool widgets
│       ├── features/           # Per-tool drivers + chat framework
│       ├── hooks/              # useVoiceRecorder, useProctoring, etc.
│       ├── store/              # Zustand (chat, session, proctoring)
│       ├── lib/                # API clients + WebSocket manager
│       └── types/              # TypeScript definitions
├── docs/                       # Architecture, API, deployment docs
├── design/                     # Design system assets
├── nginx/                      # Reverse proxy config
├── docker-compose.yml          # Production compose
└── docker-compose.dev.yml      # Dev overrides (hot reload)

app/core/ is the kernel — READ ONLY. Build on top of it, never modify it.

---

Architecture Overview

The platform uses a routing-only examiner agent design:

1. Planner Agent converts an admin's free-text prompt into a structured Blueprint via LLM
2. Examiner Agent (LangGraph) tracks per-tool progress silently — it never grades or generates
3. Each tool grades itself through its own answer endpoint (silent grading — scores never exposed to the learner)
4. Adaptation Layer scores 5 skill dimensions (Thinking, Soft, Work, Digital/AI, Growth) and selects next difficulty
5. Memory Agent extracts evidence cards per question, persisted to Qdrant for recall
6. Session Judge aggregates all grade results post-completion into a holistic score
7. Radar Report generates a 5-dimension radar chart with PDF delivery via email

---

Feature Ownership

Feature	Branch	Owner
Voice interview	voice-agent	Karim
MCQ protocol	mcq-tool	Malak
Diagram / image	viz-tool	Abutaleb
Camera interview	avatar-tool	Sherif
Code execution	coding-tool	Nagah

Branch Strategy

main          ← demo-ready, receives PRs from all feature branches
  ├── voice-agent
  ├── mcq-tool
  ├── viz-tool
  ├── avatar-tool
  └── coding-tool

Each team member works on their assigned branch and opens a PR into main when complete.

---

Environment Variables

Copy .env.example to .env and fill in values. Never commit a real .env file.

Variable	Description
DATABASE_URL	PostgreSQL (Supabase) connection string
REDIS_URL	Redis connection string
LITELLM_API_KEY	LLM proxy key (Sprints proxy)
LITELLM_MODEL	Model name (default: openai/FW-Kimi-K2.6)
DEEPGRAM_API_KEY	Speech-to-text for voice tool
QDRANT_URL	Vector store URL (Qdrant Cloud)
QDRANT_API_KEY	Vector store API key
LANGFUSE_PUBLIC_KEY	Langfuse observability
E2B_API_KEY	Code sandbox API key
RESEND_API_KEY	Email delivery for PDF reports
ADMIN_USERNAME	Admin panel login
ADMIN_PASSWORD	Admin panel login
CELERY_PIPELINES	Enable async post-answer pipelines

---

Proctoring

The platform includes real-time proctoring with:

• Identity verification via national ID card image + live selfie (VLM / HuggingFace ArcFace / Azure)
• Camera analysis — VLM-driven frame analysis for violations
• Audio analysis — microphone signal metrics
• Event batching — frontend sends integrity events in batches
• Severity scoring — configurable thresholds per check type
• Session flagging — automatic when severity exceeds threshold

---

Contributing

See CONTRIBUTING.md for the full workflow, branch rules, and PR checklist.