MLS Platform

A web-based Machine Learning Lab platform for Sup'Com / MLS that manages courses, labs, student submissions, automated grading, teacher evaluation, resources, notifications, and audit logging.

The platform combines a Flask web application with a Docker-isolated notebook grading system.

---

Overview

The MLS Platform provides a complete workflow for running and evaluating Machine Learning labs:

1. Teachers manage labs and course content.
2. Students access published labs and submit their GitHub repositories.
3. The platform creates an immutable snapshot of each submission.
4. The grading service launches an isolated Docker grading environment.
5. Student notebooks are executed and evaluated against hidden tests.
6. Automated grading results are stored in the database.
7. Teachers can review and publish grades.
8. Sensitive actions are recorded in the audit log.

The platform currently includes four Machine Learning labs:

• Lab 1 — Data Preprocessing
• Lab 2 — Linear & Logistic Regression
• Lab 3 — Support Vector Machines
• Lab 4 — K-Nearest Neighbors

---

Main Features

Authentication and Roles

• GitHub OAuth authentication
• Student, teacher, and administrator roles
• Capability-based authorization
• Role management and teacher promotion
• Submission ownership checks

Lab Management

Teachers can:

• Create and edit labs
• Publish and hide labs
• Archive and restore labs
• Configure submission deadlines
• Open and close submission windows
• Attach resources to labs
• Review student submissions

Student Submissions

Students submit GitHub repositories through the platform.

The submission workflow includes:

• Repository URL validation
• GitHub repository cloning
• Immutable submission snapshots
• Submission ownership enforcement
• Re-submission requests
• Teacher approval/rejection of re-submissions

Automated Grading

The platform includes a dedicated Docker-based grading system.

The grader:

• Executes Jupyter notebooks
• Runs hidden tests
• Produces structured grading results
• Supports multiple notebooks per lab
• Calculates notebook and lab scores
• Isolates grading jobs inside Docker containers

The grading environment uses security restrictions including:

• --network none
• --read-only
• --cap-drop ALL
• Disabled Git hooks
• HTTPS-only repository cloning
• Shallow repository clones
• Hard execution timeouts

---

Lab Configuration

Lab configuration is YAML-based.

Each lab has its own directory under labs/:

labs/
├── lab1/
│   ├── config.yaml
│   ├── employee_data.csv
│   └── hidden_tests.py
│
├── lab2/
│   ├── config.yaml
│   ├── employee_data.csv
│   ├── hidden_tests_scratch.py
│   └── hidden_tests_sklearn.py
│
├── lab3/
│   ├── config.yaml
│   ├── employee_data.csv
│   ├── hidden_tests_scratch.py
│   ├── hidden_tests_dual.py
│   └── hidden_tests_sklearn.py
│
└── lab4/
    ├── config.yaml
    ├── magic04.data
    ├── hidden_tests_scratch.py
    └── hidden_tests_sklearn.py

The grader discovers available labs dynamically from the labs/ directory.

The previous centralized Labs_config.py approach has been replaced by this per-lab configuration system.

Lab 4 Example

Lab 4 contains two notebooks:

• knn_scratch.ipynb
• knn_sklearn.ipynb

The scratch implementation is tested for:

• Train/test splitting
• Euclidean distance
• Manhattan distance
• Minkowski distance
• Chebyshev distance
• Distance validation
• Model initialization
• Fitting
• Neighbor selection
• Uniform voting
• Distance-weighted voting
• Prediction
• Parameter validation

The scikit-learn implementation is tested for:

• Data splitting
• KNN model construction
• Pipeline usage
• Hyperparameter selection
• Final model construction

---

Grading Architecture

The grading system is divided into two main components.

Flask Platform

backend/
├── app.py
├── auth.py
├── database.py
├── models.py
├── permissions.py
├── notifications.py
├── audit.py
└── services/
    ├── grading_results.py
    ├── grading_service.py
    ├── lab_service.py
    ├── resource_service.py
    ├── resubmission_service.py
    └── submission_service.py

Grader

grade.py
grading_worker.py
config_loader.py
Dockerfile.grader

config_loader.py discovers labs and loads their YAML configuration:

labs/<lab_id>/config.yaml

For example:

lab1
lab2
lab3
lab4

This allows new labs to be added without modifying a central Python configuration file.

---

Project Structure

Mls-Platform/
│
├── backend/
│   ├── app.py
│   ├── auth.py
│   ├── audit.py
│   ├── database.py
│   ├── models.py
│   ├── notifications.py
│   ├── permissions.py
│   ├── promote_user.py
│   ├── seed_initial.py
│   ├── seed_lab.py
│   │
│   ├── services/
│   │   ├── grading_results.py
│   │   ├── grading_service.py
│   │   ├── lab_service.py
│   │   ├── resource_service.py
│   │   ├── resubmission_service.py
│   │   └── submission_service.py
│   │
│   ├── static/
│   │   └── style.css
│   │
│   └── templates/
│       ├── base.html
│       ├── home.html
│       ├── student_dashboard.html
│       ├── teacher_dashboard.html
│       └── ...
│
├── labs/
│   ├── lab1/
│   ├── lab2/
│   ├── lab3/
│   └── lab4/
│
├── migrations/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
│
├── config_loader.py
├── grade.py
├── grading_worker.py
├── Dockerfile.grader
├── build_test_notebook.py
├── run.ps1
│
├── requirements.txt
├── requirements-grader.txt
├── alembic.ini
├── .env.example
├── .gitignore
└── README.md

---

Requirements

Platform

• Python 3.12+
• Flask
• SQLAlchemy
• Alembic
• Git
• GitHub OAuth credentials

Grader

The grader uses:

• Python
• nbclient
• nbformat
• Jupyter Client
• IPykernel
• NumPy
• Pandas
• SciPy
• Scikit-learn
• Matplotlib
• PyYAML
• Pytest

Docker is required for the isolated grading workflow.

---

Installation

Clone the repository and create a virtual environment:

git clone https://github.com/Zanteni/Mls-Platform.git
cd Mls-Platform

python -m venv .venv

Windows PowerShell

.\.venv\Scripts\Activate.ps1

Linux / macOS

source .venv/bin/activate

Install the platform dependencies:

pip install -r requirements.txt

Install the grader dependencies:

pip install -r requirements-grader.txt

---

Environment Configuration

Create the local environment file:

Windows PowerShell

Copy-Item .env.example .env

Linux / macOS

cp .env.example .env

Configure the required environment variables, including the Flask secret key and GitHub OAuth credentials.

Do not commit .env.

---

Database Setup

Apply the Alembic migrations:

alembic upgrade head

The application uses SQLite for local development.

Runtime database files are stored locally and are intentionally excluded from Git.

---

Initial Setup

Initialize the platform and create the initial course:

python -m backend.seed_initial --admin-github-username <your-github-username>

To promote another user to teacher:

python -m backend.promote_user \
    --github-username <username> \
    --role teacher \
    --actor <admin-username>

Role changes are recorded in the audit log.

---

Running the Platform

After configuring the environment and database:

python -c "from backend.app import app; app.run(debug=True)"

The application is then available at:

http://localhost:5000

GitHub OAuth credentials are required for normal authentication.

---

Running the Grader

The grading system can be executed directly for development and testing.

A grading job requires:

• Student ID
• Lab ID
• Submission snapshot
• Submission ID

Example:

python grading_worker.py `
    --student-id test_lab4 `
    --lab-id lab4 `
    --snapshot-path /snapshot `
    --submission-id 11

The worker returns a structured GRADING_RESULT_JSON containing the grading status, checks, scores, and errors.

---

Docker Grader

Build the grading image:

docker build -f Dockerfile.grader -t mls-grader:1.2 .

Verify the available labs:

docker run --rm `
    --entrypoint python `
    mls-grader:1.2 `
    -c "from config_loader import list_labs; print(list_labs())"

Expected output:

['lab1', 'lab2', 'lab3', 'lab4']

The Docker image provides the isolated environment used by the platform's grading service.

---

Testing

The grading system uses hidden tests stored inside each lab configuration directory.

For example:

labs/lab4/
├── config.yaml
├── hidden_tests_scratch.py
└── hidden_tests_sklearn.py

Tests validate both the expected implementation behavior and parameter/error handling.

A successful grading job returns:

GRADING_RESULT_JSON:
{
    "success": true,
    ...
}

---

Security and Isolation

The platform treats submitted repositories as untrusted code.

Repository snapshots and grading execution are therefore isolated.

The grading workflow includes:

• Immutable submission snapshots
• Docker isolation
• Disabled network access
• Read-only container filesystem
• Dropped Linux capabilities
• Disabled Git hooks
• HTTPS-only Git operations
• Shallow repository cloning
• Execution timeouts
• Submission ownership checks
• Role/capability authorization
• Audit logging for sensitive operations

The application also keeps secrets and runtime data outside the Git repository.

---

Audit Logging

Sensitive platform actions are recorded in the audit log.

Examples include:

• Grade publication
• Re-grading
• Resubmission decisions
• Lab archive/restore
• Lab visibility changes
• User role changes

Content-management operations such as ordinary lab editing and resource management are intentionally treated separately from oversight-sensitive actions.

---

Runtime Data

The following directories/files are local application data and are intentionally not committed to Git:

data/
results/
uploads/
backend/uploads/
.env
__pycache__/

This keeps the repository focused on source code, lab definitions, tests, migrations, and configuration required to reproduce the system.

---

Development Utilities

run.ps1 contains PowerShell commands used during local development and testing.

build_test_notebook.py provides utilities for creating test notebooks for the grading workflow.

---

Current Status

The platform currently contains:

• Four configured Machine Learning labs
• YAML-based lab configuration
• Automated Jupyter notebook grading
• Scratch and scikit-learn lab implementations
• Docker-isolated grading
• GitHub repository submission workflow
• Student and teacher dashboards
• Lab creation/editing
• Lab archive/restore
• Submission windows and deadlines
• Resources management
• Re-submission workflow
• Grade publication
• Bulk grade publication
• Notifications
• Audit logging
• Database migrations
• Role and capability-based authorization

The project is structured so that additional labs can be introduced by adding a new lab directory and its config.yaml, dataset, and hidden tests without reintroducing a centralized lab configuration file.