README.md

---
language: 
- en
tags:
- xgboost
- regression
- tabular
- education
- test-scores
license: mit
datasets:
- synthetic
model-index:
- name: test-score-predictor
  results:
  - task:
      type: regression
      name: Regression
    dataset:
      name: Synthetic Test Score Dataset
      type: tabular
    metrics:
      - type: mean_squared_error
        value: 38.25
      - type: r2
        value: 0.79
---

# Test Score Predictor (XGBoost)

This model predicts **final test scores** for students based on previous performance and study habits.  
It was trained on a **synthetic dataset of 1,000 rows** generated to reflect average realism (balanced distribution of student profiles).

---

## 📊 Input Features

The model expects the following features:

- **`previous_test_score`** → Student’s most recent test score (0–100)  
- **`motivation_level`** → Self-reported motivation (1–10)  
- **`self_confidence`** → Confidence in academic ability (1–10)  
- **`study_environment_quality`** → Quality of study environment (1–10, quiet & focused = higher)  
- **`time_management_skill`** → Time management ability (1–10)  
- **`last_minute_cram_hours`** → Hours crammed the night before the test (0–12)  

---

## 🎯 Output

- **Predicted final test score** (0–100)  
- Can also be mapped to a **letter grade (A–F)**

| Score Range | Grade |
|-------------|-------|
| 90–100      | A     |
| 80–89       | B     |
| 70–79       | C     |
| 60–69       | D     |
| < 60        | F     |

---

## 🛠️ Usage

### 1. Install dependencies

```bash
pip install xgboost scikit-learn pandas joblib huggingface_hub
import joblib
import pandas as pd
from huggingface_hub import hf_hub_download

# Download model file from Hugging Face repo
model_path = hf_hub_download(
    repo_id="mjpsm/test-score-predictor",
    filename="xgb_test_score_model.pkl"
)

# Load the model
model = joblib.load(model_path)

# Example student
student = pd.DataFrame([{
    "previous_test_score": 72,
    "motivation_level": 8,
    "self_confidence": 7,
    "study_environment_quality": 6,
    "time_management_skill": 5,
    "last_minute_cram_hours": 3
}])

# Predict final score
prediction = model.predict(student)[0]
print(f"Predicted final test score: {prediction:.2f}")
```

## 📈 Training
- Algorithm: XGBoost Regressor
- Dataset: 1,000 rows synthetic (realistic student performance simulation)

Metrics on test set:
- MSE: ~38.25
- R²: ~0.79

## 📌 Notes
- Predictions are continuous values, so results may slightly exceed 100 — clamp to [0, 100] if needed.
- The dataset reflects average realism: some students improve, some decline, depending on habits and prior scores.