cambodia-major-field-recommender

Cambodia Major Field Recommender System

A machine learning-powered recommendation system that suggests university major fields to Cambodian high school students based on their academic grades.

Quick Start

Development

# Activate virtual environment
source bin/activate

# Run web server
python app.py

# Visit http://localhost:5000

Production

See PRODUCTION_GUIDE.md for detailed deployment instructions.

Project Structure

ai-env/
├── app.py                      # Flask web server
├── train_mac.py               # Model training script
├── evaluate_accuracy.py        # Model evaluation
├── requirements.txt            # Python dependencies
├── .env.example               # Environment template
├── templates/
│   └── index.html            # Web interface
├── data/
│   ├── combined_train.csv    # Training data
│   └── combined_test.csv     # Test data
├── results/
│   └── combined/
│       ├── lightgbm_multioutput.pkl  # Trained model
│       └── metadata.pkl               # Model metadata
├── MODEL_REPORT.md            # Detailed model documentation
└── PRODUCTION_GUIDE.md        # Deployment instructions

Features

✅ Multi-stream Support: Separate subject requirements for Science and Social streams
✅ LightGBM ML Model: Fast, accurate predictions with 79.72% Top-5 accuracy
✅ Web Interface: User-friendly form for grade input and recommendations
✅ REST API: /api/predict endpoint for integration
✅ Production Ready: Configured for Gunicorn, Docker, and cloud deployment

Model Performance

See MODEL_REPORT.md for full technical details.

API Usage

Predict Major Fields

curl -X POST http://localhost:5000/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "stream": "science",
    "grades": {
      "mathematics": "A",
      "khmer": "B",
      "english": "A",
      "history": "C",
      "biology": "B",
      "chemistry": "A",
      "physics": "B"
    }
  }'

Training a New Model

# Prepare data in data/combined_train.csv and data/combined_test.csv
python train_mac.py

# Evaluate model
python evaluate_accuracy.py

Variables & Streams

Science Stream Subjects

• Mathematics ⭐
• Biology
• Chemistry
• Physics
• History ⭐
• Khmer ⭐
• English ⭐

Social Stream Subjects

• Mathematics ⭐
• Geography
• Moral & Civic Education
• Earth Science
• History ⭐
• Khmer ⭐
• English ⭐

⭐ = Required in both streams

Major Field Categories

The model predicts probability scores for these 12 fields:

1. IT & Computer Science
2. Engineering
3. Health & Medical Sciences
4. Agriculture & Environmental
5. Architecture & Urban Planning
6. Business & Economics
7. Education
8. Arts & Media
9. Law & Legal Studies
10. Social Sciences
11. Tourism & Hospitality
12. Languages & Literature

Dependencies

• Python 3.10+
• Flask 3.0+
• LightGBM 4.0+
• scikit-learn 1.3+
• pandas 2.0+
• numpy 1.24+

Install all with: pip install -r requirements.txt

Configuration

Copy .env.example to .env and customize:

cp .env.example .env
# Edit .env with your settings

Environment Variables

• FLASK_DEBUG: Enable debug mode (false for production)
• HOST: Server host (default: 127.0.0.1)
• PORT: Server port (default: 5000)
• MODEL_PATH: Path to trained model
• METADATA_PATH: Path to model metadata

Deployment

Local Development

python app.py

Production with Gunicorn

gunicorn --workers 4 --bind 0.0.0.0:5000 app:app

Docker

docker build -t major-recommender .
docker run -p 5000:5000 major-recommender

See PRODUCTION_GUIDE.md for more deployment options.

Data Format

Input (CSV)

High school grade data with columns:

• mathematics, khmer, english, history: All students
• biology, chemistry, physics: Science stream only
• geography, moral_civics, earth_science: Social stream only
• stream: "science" or "social"
• 12 major field columns with probability values (0.0-1.0)

Output (JSON)

{
  "stream": "Science",
  "majors": [
    {"field": "Engineering", "score": 0.145},
    {"field": "IT & Computer Science", "score": 0.128},
    ...
  ]
}

Monitoring

• Check logs: tail -f logs/app.log
• Model health: Request /api/predict regularly
• Performance: Track response time (<100ms target)

Troubleshooting

Model won't load

• Verify model files exist in results/combined/
• Check file permissions: chmod 644 results/combined/*

Port conflict

• Change port: export PORT=5001 && python app.py
• Or kill existing process: lsof -i :5000 then kill -9 <PID>

Prediction errors

• Check input JSON format matches API docs
• Ensure all required grades are provided per stream
• View logs: python app.py (development mode)

License

Educational/Research Project - CADT Capstone 2026

Contact

Developed as part of CADT Year 3, Term 2 Capstone Project

---

Version: 1.0
Last Updated: March 2026
Status: Production Ready ✅

Recommendation-Model