AdaptCode
AI-powered adaptive programming practice platform that personalizes problem difficulty using Bayesian Knowledge Tracing, LinUCB contextual bandits, and LLM tutoring.
Report Bug * Request Feature
+-----------------------------------------------------------------------------+
| AdaptCode Adaptive Learning Loop |
| |
| +-----------------------+ +-----------------------+ |
| | Monaco Code Editor | | Multi-Language Code | |
| | (Python/Java/C++) | | Submission Payload | |
| +----------+------------+ +----------+------------+ |
| | | |
| +--------------------------+------------------------+ |
| v v |
| +-----------------------------------------------------------------------+ |
| | Piston Code Execution Sandbox (HTTP POST to :2000) | |
| +-------------------------------------+---------------------------------+ |
| v |
| +-----------------------------------------------------------------------+ |
| | Bayesian Knowledge Tracing (BKT) ---> LinUCB Contextual Bandit Selector| |
| +-------------------------------------+---------------------------------+ |
| v |
| +-----------------------------------------------------------------------+ |
| | LLM Diagnostic Tutoring Hint <--- Next Optimal Challenge (ZPD) | |
| +-----------------------------------------------------------------------+ |
+-----------------------------------------------------------------------------+
Standard coding practice platforms rely on static difficulty tags and rigid problem sets, leaving students either stuck on difficult concepts or bored with repetitive questions.
AdaptCode models each learner's mastery in real-time across a prerequisite graph of 12 algorithmic concepts, applying Bayesian Knowledge Tracing (P(L0), P(T), P(G), P(S)) and LinUCB contextual multi-armed bandits to serve challenges in the Zone of Proximal Development while providing instant LLM diagnostic feedback on failed test cases.
Features
- Dynamic Knowledge Tracing -- Models concept mastery across 12 algorithmic topics in real time using Bayesian Knowledge Tracing (BKT).
- Contextual Bandit Selection -- Recommends optimal practice problems dynamically via LinUCB multi-armed bandit algorithms with ridge regression.
- Piston Sandbox -- Executes and evaluates multi-language submissions securely inside a standalone Piston container with strict timeouts.
- Monaco In-Browser IDE -- Delivers a complete in-browser coding environment with syntax highlighting, custom themes, and instant execution telemetry.
- AI Diagnostic Tutoring -- Generates targeted explanations and remediation hints automatically upon test case failures using Google Gemini integration.
- Curriculum Prerequisite Graph -- Visualizes concept progression and dependencies across data structures and algorithms.
How It Works
graph TD
A[Student Submits Code] --> B[FastAPI Backend Endpoint: /api/submit]
B --> C[Piston Execution Sandbox :2000]
C -->|Execution Telemetry| D[BKT Engine Updates Mastery State]
D --> E[LinUCB Contextual Bandit]
E --> F[Next Optimal Problem Selected]
C -->|On Failure| G[LLM Diagnostic Tutor: /api/explanation/{event_id}]
G --> H[Contextual Hint & Remediation Plan]
Quick Start
Prerequisites
| Requirement | Version | Notes |
|---|
| Node.js | 18+ | Frontend runtime |
| Python | 3.10+ | Backend runtime |
| Supabase | Cloud / Local | PostgreSQL database and authentication |
| Docker | 20+ | Required for Piston Code Runner |
Installation
-
Clone the repository:
git clone https://github.com/Justinvcj/Adapt_Code.git
cd Adapt_Code
-
Set up the backend:
cd backend
python -m venv venv
source venv/bin/activate # Or `venv\Scripts\activate` on Windows
pip install -r requirements.txt
cp .env.example .env
-
Set up the frontend:
cd ../frontend
npm install
cp .env.example .env.local
-
Launch services via Docker Compose:
docker-compose up -d
-
CRITICAL: Launch Piston Sandbox:
The docker-compose.yml does not currently include Piston. You must launch it manually:
docker run -d -p 2000:2000 --privileged --tmpfs /tmp:exec --name piston ghcr.io/engineer-man/piston
Usage
Open http://localhost:3000 in your browser, select a topic from the curriculum graph, and begin solving adaptive challenges with real-time feedback.
Configuration
Backend (backend/.env)
| Variable | Required | Default | Description |
|---|
SUPABASE_URL | Yes | -- | Supabase project URL |
SUPABASE_KEY | Yes | -- | Supabase service role or anon API key |
GEMINI_API_KEY | Yes | -- | API key for Google Gemini LLM tutoring explanations |
FRONTEND_URL | No | http://localhost:3000 | Allowed CORS origin |
PISTON_URL | No | http://localhost:2000/api/v2/execute | Piston execution endpoint |
DEBUG | No | false | Enable verbose logging |
TEST_MODE | No | false | Enable test mode (bypasses auth for development) |
Frontend (frontend/.env.local)
| Variable | Required | Default | Description |
|---|
NEXT_PUBLIC_API_URL | No | http://localhost:8000 | FastAPI backend URL |
Tech Stack
| Layer | Technology |
|---|
| Frontend | Next.js 14, React 18, TypeScript, Tailwind CSS, Monaco Editor, Framer Motion, Lucide React |
| Backend | FastAPI, Uvicorn, Pydantic, Supabase Python SDK, NumPy, SlowAPI |
| Execution Sandbox | Piston API (Docker) |
| AI & Adaptive Engine | Google Gemini LLM, Bayesian Knowledge Tracing (BKT), LinUCB Bandit |
| Testing | Pytest, Jest |
Testing (Requires Maintenance)
Warning: The backend test suite currently suffers from import debt due to structural refactoring and requires updates before passing.
# Run backend test suite
cd backend && venv/bin/pytest tests/
# Run frontend unit tests
cd ../frontend && npm test
Contributing
Contributions are welcome. Please open an issue first to discuss the changes you would like to make.
- Fork the Project
- Create your Feature Branch (
git checkout -b feat/AmazingFeature)
- Commit your Changes (
git commit -m 'feat: add amazing feature')
- Push to the Branch (
git push origin feat/AmazingFeature)
- Open a Pull Request
License
Distributed under the MIT License. See LICENSE for details.
