Adaptive Python Assessment for Students

This repository contains a terminal-based educational platform that assesses a student's Python level, estimates one of 15 curriculum levels, and then recommends a matching pack of coding tasks. The runtime app supports English and Russian, uses rich for a polished terminal interface, and loads quiz questions from encrypted files at runtime.

Features

• bilingual startup flow: English and Russian;
• adaptive quiz progression with a 4-mistake hard stop;
• immediate correct/incorrect feedback without revealing the answer;
• estimated level result with interpretation and next-step guidance;
• 15 curriculum levels with 10 student tasks each;
• encrypted question banks for en and ru;
• saved JSON and CSV assessment reports for later review;
• teacher-only notes and solution placeholders kept outside the student task folders;
• basic tests for crypto, localization, question loading, adaptive behavior, and curriculum structure.

Requirements

• Python 3.12+
• packages from requirements.txt

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run The App

python3 main.py

The app starts with language selection, asks for the student's name, runs the assessment, and finishes with a result summary plus the recommended task pack.

Each completed run also saves:

• a detailed JSON report in data/results/
• a CSV companion file in data/results/

The saved report includes timestamps, student name, summary metrics, per-level performance, and every answer given during the run. The JSON report is also signed by the app so a future reader tool can check whether the file still matches what the app originally generated.

Read Saved Reports

python3 read_reports.py

This shows a compact summary of the most recent saved assessment reports.

Content Workflow

Raw question banks are authored in:

• data/raw_questions/en_questions.json
• data/raw_questions/ru_questions.json

Encrypted runtime banks are stored in:

• data/encrypted/en_questions.enc
• data/encrypted/ru_questions.enc

Generate or refresh repository content:

python3 scripts/generate_content.py

Encrypt the question banks for runtime use:

python3 scripts/encrypt_questions.py

The app decrypts question data directly in memory during runtime. The repository includes the encryption key logic in code, so this protects content against casual access rather than providing strong secret storage.

Adaptive Assessment Logic

The assessment starts at Level 2 and adapts upward when the student answers consistently well. A single mistake does not aggressively lower the estimate. The engine tracks correct answers, mistakes, streaks, and per-level performance, then calculates a smoothed final level. The run stops when one of these happens:

• 4 total mistakes are reached;
• enough confidence has been gathered after multiple questions;
• the question bank is exhausted.

Curriculum Layout

Each curriculum level lives under levels/level_XX/ and contains:

• overview.md
• tasks_manifest.json
• tasks/task_01 ... tasks/task_10

Every task folder contains at least:

• README.md
• starter.py

Teacher-side supporting notes live in .teacher/.

Tests

Run the test suite with:

pytest