Skip to content

crazyblog/PyTutor

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

8 Commits
backend
backend
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 

Repository files navigation

PyTutor AI: Interactive Python Intelligent Tutoring Platform

Student Projects 2024-25 | University of Birmingham
Student: Runtao Duan (rxd496@student.bham.ac.uk)
Supervisor: Dr. Rachid Anane
Department: School of Computer Science, College of Engineering and Physical Sciences

A web-based programming education platform built upon the Intelligent Tutoring Systems (ITS) three-model architecture (Domain Model, Learner Model, and Tutoring Model), providing personalized learning experiences for novice Python programmers.

Note: Earlier commits were made while testing GitLab usage. The actual project code is included in this latest commit.

Abstract

This platform addresses the gap between mainstream online coding platforms and research-based intelligent tutoring systems. It provides instant, multi-source feedback through large language models (OpenAI, DeepSeek), implements adaptive scaffolding based on learner behavior, and maintains comprehensive learning analytics for educational research.

Core Features

Intelligent Tutoring System Architecture

  • Domain Model: Hierarchical curriculum structure with prerequisite dependencies
  • Learner Model: Overlay model tracking progress, attempts, and temporal learning patterns
  • Tutoring Model: Rule-based adaptive scaffolding with real-time intervention triggers

Advanced Learning Support

  • In-browser Code Execution: Secure sandboxed execution via Judge0 API with automatic fallback
  • Multi-source AI Feedback: Parallel analysis from multiple LLMs with comparative insights
  • Adaptive Scaffolding: Dynamic hint provision based on attempt count, time-on-task, and individual learning patterns
  • Real-time Learning Analytics: Comprehensive tracking of coding behavior and learning progression

Security & Reliability

  • Sandboxed Execution: All user code runs in isolated Judge0 containers
  • Graceful Degradation: Automatic fallback mechanisms when external services are unavailable
  • Secure Authentication: JWT-based stateless authentication with refresh token support

Technical Architecture

Frontend (Vue 3)     ←→     Backend (Flask)     ←→     Database (SQLite)
     ↓                           ↓                         ↓
CodeMirror 6              RESTful API              Learning Analytics
Scaffolding UI           Multi-model AI           Progress Tracking
Real-time Feedback    ←→  Judge0 Integration  ←→   Content Management

Technology Stack

  • Frontend: Vue 3, Vite, Vue Router, Pinia, CodeMirror 6, i18n
  • Backend: Flask 2.3, SQLAlchemy, Flask-JWT-Extended, Flask-CORS
  • Database: SQLite (PostgreSQL-ready)
  • External Services: Judge0 (code execution), OpenRouter (AI feedback)
  • Deployment: Docker-ready, Nginx-compatible

Research Contributions

Educational Theory Implementation

  • Zone of Proximal Development: Scaffolding triggers based on Vygotsky's ZPD theory
  • Personalized Learning: Individual time thresholds adapted from historical performance
  • Feedback Effectiveness Tracking: Quantitative measurement of different tutoring approaches

Technical Innovations

  • Real-time Behavioral Monitoring: Millisecond-precision tracking of coding activity
  • Multi-model AI Comparison: Concurrent analysis from different LLM providers
  • Session-based Time Calculation: Active learning time computation excluding idle periods
  • Feedback Loop Closure: Complete data pipeline from intervention to success measurement

Cloning from GitLab

git clone https://git.cs.bham.ac.uk/projects-2024-25/rxd496.git
cd rxd496

Quick Start

Prerequisites

  • Python 3.8+
  • Node.js 18+
  • Git

Backend Setup

cd backend
python -m venv venv
venv\Scripts\activate  # For Windows PowerShell
pip install -r requirements.txt
cp env.example .env  # Configure API keys as needed
python setup_database.py  # Initialize with sample data
python app.py

Frontend Setup

ell
cd frontend
npm install
cp env.example .env.local  # Configure API endpoints
npm run dev

Access Points

  • Frontend Application: http://localhost:3000
  • API Health Check: http://localhost:5000/api/health
  • API Documentation: http://localhost:5000/

Default Admin Credentials

  • Username: admin
  • Password: admin123 (⚠️ Change in production)

Demo & Live Deployment

For a complete demonstration of the platform's functionality:

Local Development Setup

# Quick start for evaluation
git clone https://git.cs.bham.ac.uk/projects-2024-25/rxd496.git
cd rxd496

# Backend setup (Terminal 1)
cd backend; python -m venv venv; venv\Scripts\activate
pip install -r requirements.txt; python setup_database.py
python app.py

# Frontend setup (Terminal 2)  
cd frontend; npm install; npm run dev

Live Demo Access

  • Demo URL: http://localhost:3000 (after setup)
  • API Endpoints: http://localhost:5000/api/
  • Admin Panel: Login with admin credentials above

Production Build (Optional)

# For deployment purposes
cd frontend; npm run build
# Serves static files from backend at /static/

Project Structure

├── backend/                    # Flask REST API
│   ├── app.py                 # Application factory
│   ├── config.py              # Configuration management
│   ├── extensions.py          # Flask extensions initialization
│   ├── env.example           # Environment variables template
│   ├── requirements.txt      # Python dependencies
│   ├── setup_database.py     # Database initialization script
│   ├── models/                # Database models
│   │   ├── content_models.py  # Domain Model (Module/Lesson/Exercise)
│   │   └── learning_models.py # Learner Model (User/Progress/Feedback)
│   ├── routes/                # API endpoints
│   │   ├── auth.py           # Authentication
│   │   ├── content.py        # Content delivery
│   │   ├── submissions.py    # Code submission & evaluation
│   │   ├── admin.py          # Content management
│   │   ├── analytics.py      # Learning analytics
│   │   ├── chat.py           # Chat functionality
│   │   ├── progress.py       # Progress tracking
│   │   └── upload.py         # File upload handling
│   └── utils/                 # Core utilities
│       ├── code_executor.py  # Judge0 integration
│       ├── code_analyzer.py  # Multi-model AI analysis
│       ├── datetime_utils.py # Date/time utilities
│       └── messages.py       # Internationalization
├── frontend/                   # Vue 3 SPA
│   ├── index.html            # Main HTML template
│   ├── package.json          # Node.js dependencies
│   ├── package-lock.json     # Dependency lock file
│   ├── vite.config.js        # Build configuration
│   ├── vitest.config.ts      # Testing configuration
│   ├── tsconfig.json         # TypeScript configuration
│   ├── env.example           # Environment variables template
│   └── src/
│       ├── App.vue           # Root component
│       ├── main.js           # Application entry point
│       ├── style.css         # Global styles
│       ├── api.js            # API client
│       ├── adminApi.js       # Admin API client
│       ├── components/       # Reusable components
│       ├── views/            # Page components
│       ├── stores/           # Pinia state management
│       ├── composables/      # Vue composition functions
│       ├── utils/            # Utility functions
│       ├── types/            # TypeScript type definitions
│       ├── styles/           # Additional styling
│       ├── tests/            # Test files
│       ├── directives/       # Vue directives
│       ├── config/           # Configuration files
│       ├── router/           # Vue Router configuration
│       └── i18n/             # Internationalization
├── .gitignore                 # Git ignore rules
└── README.md                  # Project documentation

Configuration

Backend Environment Variables (.env)

# Environment mode
FLASK_ENV=development

# Server configuration
HOST=0.0.0.0
PORT=5000
DEBUG=true

# Frontend configuration
FRONTEND_URL=http://localhost:3000
FRONTEND_PORT=3000

# Security configuration
SECRET_KEY=your-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-here

# Database configuration (optional, defaults to SQLite)
# DATABASE_URL=sqlite:///learning_platform.db
# DATABASE_URL=postgresql://user:pass@localhost/dbname 

# External APIs
# Judge0 API (Code execution service)
JUDGE0_API_KEY=your-judge0-api-key-here
JUDGE0_BASE_URL=https://judge0-ce.p.rapidapi.com
JUDGE0_HOST=judge0-ce.p.rapidapi.com
JUDGE0_TIMEOUT=15
PYTHON_LANGUAGE_ID=71

# OpenRouter API (AI analysis service)
OPENROUTER_API_KEY=your-openrouter-api-key-here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_TIMEOUT=15

Frontend Environment Variables (.env.local)

# API base URL
VITE_API_BASE_URL=http://localhost:5000/api

# Port configuration
VITE_FRONTEND_PORT=3000
VITE_BACKEND_PORT=5000

API Reference

Authentication

  • POST /api/auth/register - User registration
  • POST /api/auth/login - User authentication
  • GET /api/auth/profile - Get user profile

Content Management

  • GET /api/content/modules - Retrieve course modules
  • GET /api/content/lessons/:id - Get lesson details with progress
  • GET /api/content/exercises/:id/hints - Fetch adaptive hints

Code Submission & Feedback

  • POST /api/submissions/submit - Submit code for evaluation
  • POST /api/submissions/exercises/:id/hint - Request scaffolding hint
  • GET /api/submissions/exercises/:id/history - Get submission history
  • POST /api/submissions/feedback-rating - Rate feedback effectiveness

Learning Analytics

  • GET /api/analytics/user/code_analysis - Personal learning insights
  • GET /api/analytics/exercise/:id/analysis - Exercise-specific analytics
  • GET /api/analytics/research/feedback_effectiveness - Research data (Admin)

Intelligent Scaffolding System

Multi-criteria Trigger Logic

const shouldShowHintByTime = (exercise) => {
  const currentTime = currentTimes.value[exerciseId] || 0
  const avgTime = lesson.value?.progress?.avg_time_sec || 0
  const attempts = lesson.value?.progress?.attempts || 0
  
  // Fixed threshold: 90 seconds of active coding
  if (currentTime > 90) return true
  
  // Personalized threshold: 1.5x individual average time
  if (avgTime > 0 && currentTime > avgTime * 1.5) return true
  
  // Attempt-based threshold: 3+ failed submissions
  if (attempts >= 3) return true
  
  return false
}

Progressive Visual Feedback

  1. Silent Phase (0-60s): No intervention, allowing independent exploration
  2. Reminder Phase (60-90s): Subtle hint button availability
  3. Support Phase (90-120s): Animated breathing effect and enhanced messaging
  4. Active Phase (120s+): Prominent visual cues and proactive assistance offers

Research Data Collection

The platform collects comprehensive data for educational research:

Learning Behavior Metrics

  • Temporal Patterns: Precise coding session timestamps and durations
  • Error Classification: Syntax, logic, runtime, and timeout error categorization
  • Scaffolding Usage: Hint request patterns and effectiveness measurement
  • Progress Tracking: Lesson completion rates and prerequisite navigation

Feedback Effectiveness Analysis

-- Sample query for research analysis
SELECT 
    f.feedback_type,
    AVG(fe.time_to_success_sec) as avg_resolution_time,
    AVG(fe.subsequent_attempts) as avg_attempts,
    AVG(fe.helpfulness_rating) as user_satisfaction
FROM feedback_instances f
JOIN feedback_effectiveness fe ON f.feedback_id = fe.feedback_id
WHERE fe.did_succeed = true
GROUP BY f.feedback_type;

Internationalization

The platform supports multiple languages with complete UI translation:

  • English: Full interface and error messages
  • Chinese (Simplified): Complete localization support
  • Extensible: Easy addition of new language packs

Testing & Quality Assurance

Backend Testing

cd backend
python -m pytest tests/ -v --cov=.

Frontend Testing

cd frontend
npm run test:unit
npm run test:e2e

Performance Benchmarks

  • Code Execution: < 10 seconds end-to-end (Judge0 + AI feedback)
  • UI Responsiveness: < 200ms for all user interactions
  • Scalability: Tested with concurrent users up to 50+ sessions

Deployment

Docker Deployment

# Build and run with Docker Compose
docker-compose up --build -d

# Or build individually
docker build -t its-platform-backend ./backend
docker build -t its-platform-frontend ./frontend

Production Recommendations

  • Database: Migrate to PostgreSQL for production workloads
  • Web Server: Use Nginx as reverse proxy with Gunicorn
  • Monitoring: Implement logging and error tracking
  • Security: Update secret keys and enable HTTPS

Research Applications

Educational Research

  • Learning Effectiveness: Compare scaffolding strategies across different learner populations
  • AI Feedback Quality: Analyze which LLM approaches yield better learning outcomes
  • Temporal Learning Patterns: Study how coding session timing affects comprehension

Technical Research

  • ITS Architecture Evaluation: Benchmark three-model implementation effectiveness
  • Personalization Algorithms: Test different adaptive threshold algorithms
  • Multi-modal Feedback: Explore combining AI analysis with static code metrics

Contributing

This project serves as a research platform. For academic collaborations or technical improvements:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/improvement)
  3. Commit changes with clear messages
  4. Document any research implications
  5. Submit a pull request with detailed description

License

This project is developed for academic and research purposes. Please cite this work in academic publications:

@misc{pytutor_ai_2025,
  title={PyTutor AI: Interactive Python Intelligent Tutoring Platform - Implementing Adaptive Scaffolding with Multi-source AI Feedback},
  author={Runtao Duan},
  year={2025},
  school={University of Birmingham},
  department={School of Computer Science, College of Engineering and Physical Sciences},
  type={Master's Thesis},
  supervisor={Dr. Rachid Anane},
  studentid={2850586}
}

Contact

For research inquiries, technical questions, or collaboration opportunities:

Bridging the gap between scalable online education and personalized intelligent tutoring through adaptive AI-powered scaffolding.

Note: This README file was generated with assistance from Claude 4.0 and subsequently reviewed and edited by the author.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages