====================================================================
        JoSAA COLLEGE PREDICTOR - USER GUIDE
====================================================================

An interactive web application that predicts JoSAA college and branch 
admission chances using XGBoost, Logistic Regression, and Random Forests.
All model training uses CSV-based historical JoSAA counselling data.

====================================================================
FEATURES
====================================================================

✓ Three ML Models: XGBoost, Logistic Regression, Random Forest
✓ CSV-based Training: Upload your own historical JoSAA data
✓ Interactive Predictions: Enter rank & category, get instant results
✓ Model Comparison: See predictions from all three models side-by-side
✓ Consensus Predictions: Highlights colleges agreed upon by multiple models
✓ Real-time Updates: Modify inputs and see updated recommendations

====================================================================
QUICK START (Automated Setup)
====================================================================

1. Double-click 'setup_and_run.bat'
   - This will automatically install all dependencies
   - Generate sample data
   - Start both backend and frontend servers

2. Open your browser and go to: http://localhost:3000

3. Navigate to "Train Models" tab and click "Train All Models"

4. Go to "Predict Colleges" tab and enter your details

That's it! You're ready to use the predictor.

====================================================================
MANUAL SETUP (Step-by-Step)
====================================================================

PREREQUISITES:
- Python 3.8 or higher
- Node.js 16 or higher
- pip (Python package manager)
- npm (Node package manager)

STEP 1: Install Python Dependencies
-----------------------------------
Open Command Prompt in this folder and run:

    pip install -r requirements.txt

STEP 2: Generate Sample Data (or use your own CSV)
--------------------------------------------------
To generate sample JoSAA data for testing:

    python generate_sample_data.py

This creates:
- data/train.csv (2000 sample records)
- data/test.csv (500 sample records)

OR use your own CSV files with columns:
- rank, category, institute, branch, year

STEP 3: Install Frontend Dependencies
-------------------------------------
    npm install

STEP 4: Start the Backend Server
--------------------------------
Open a new Command Prompt and run:

    python app.py

The API will start at: http://localhost:5000

STEP 5: Start the Frontend
--------------------------
Open another Command Prompt and run:

    npm run dev

The web app will start at: http://localhost:3000

====================================================================
USING YOUR OWN CSV DATA
====================================================================

CSV FORMAT REQUIRED:
Your CSV file should have these columns:
- rank: Student's JEE Advanced rank (integer)
- category: Category (OPEN, OBC-NCL, SC, ST, EWS)
- institute: College name (e.g., "IIT Bombay")
- branch: Branch name (e.g., "Computer Science and Engineering")
- year: Year of admission (optional)

EXAMPLE CSV:
rank,category,institute,branch,year
156,OPEN,IIT Bombay,Computer Science and Engineering,2024
450,OBC-NCL,IIT Delhi,Electrical Engineering,2024
1200,SC,NIT Trichy,Mechanical Engineering,2023

HOW TO UPLOAD:
1. Go to "Train Models" tab in the web interface
2. Click "Choose Training CSV" and select your file
3. Optionally upload a separate test CSV for evaluation
4. Click "Train All Models"

====================================================================
USING THE WEB INTERFACE
====================================================================

PREDICT COLLEGES TAB:
--------------------
1. Enter your JEE Advanced rank
2. Select your category (OPEN, OBC-NCL, SC, ST, EWS)
3. Choose number of predictions (3, 5, or 10)
4. Click "Get Predictions"

You'll see:
- Consensus Predictions (agreed by multiple models)
- Individual predictions from each ML model
- Probability scores for each prediction
- Visual probability bars

TRAIN MODELS TAB:
----------------
1. Upload training CSV file
2. Upload test CSV file (optional)
3. Click "Train All Models"
4. View training results and model accuracies

====================================================================
API ENDPOINTS
====================================================================

The Flask backend provides these REST APIs:

POST /api/train
- Train all models with CSV data
- Body: {"train_csv": "path", "test_csv": "path"}

POST /api/predict
- Get predictions for a rank and category
- Body: {"rank": 1000, "category": "OPEN", "top_n": 5}

POST /api/upload
- Upload CSV files
- Form data: file, type (train/test)

GET /api/categories
- Get available categories

GET /api/status
- Check if models are trained

====================================================================
COMMAND LINE MODEL TRAINING
====================================================================

After starting the backend server, you can train models from CLI:

    python train_models.py

This will:
- Train all three models
- Show accuracy metrics
- Save models to the 'models' folder

====================================================================
FILE STRUCTURE
====================================================================

josaa-rank-predictor/
├── app.py                      # Flask backend server
├── generate_sample_data.py     # Sample data generator
├── train_models.py             # CLI training script
├── requirements.txt            # Python dependencies
├── package.json                # Node.js dependencies
├── vite.config.js              # Vite configuration
├── index.html                  # HTML entry point
├── setup_and_run.bat           # Automated setup script
├── src/
│   ├── main.jsx               # React entry point
│   ├── App.jsx                # Main React component
│   ├── App.css                # Component styles
│   └── index.css              # Global styles
├── data/
│   ├── train.csv              # Training data
│   └── test.csv               # Test data
└── models/                     # Saved trained models
    ├── xgboost.joblib
    ├── logistic_regression.joblib
    ├── random_forest.joblib
    └── *_encoder.joblib        # Label encoders

====================================================================
TROUBLESHOOTING
====================================================================

Problem: "Models not trained" error
Solution: Go to "Train Models" tab and train the models first

Problem: "Cannot connect to backend"
Solution: Make sure Flask server is running (python app.py)

Problem: Port 5000 or 3000 already in use
Solution: Change ports in app.py and vite.config.js

Problem: CSV upload fails
Solution: Check CSV format matches required columns

Problem: Low prediction accuracy
Solution: Use more training data with realistic rank ranges

====================================================================
TECHNICAL DETAILS
====================================================================

MACHINE LEARNING MODELS:
1. XGBoost Classifier
   - Gradient boosting algorithm
   - 100 estimators, max depth 6
   - Best for complex patterns

2. Logistic Regression
   - Multinomial classification
   - Maximum 1000 iterations
   - Fast and interpretable

3. Random Forest Classifier
   - Ensemble of 100 decision trees
   - Max depth 10
   - Robust to overfitting

FEATURES USED:
- Student's rank (normalized)
- Category (encoded)

TARGET:
- Combined institute + branch combination

====================================================================
SUPPORT & CUSTOMIZATION
====================================================================

To customize the predictor:

1. Add more features: Edit app.py JoSAAPredictor class
2. Modify model parameters: Adjust hyperparameters in train_models()
3. Change UI: Edit src/App.jsx and src/index.css
4. Add institutes/branches: Use your own CSV data

====================================================================
NOTES
====================================================================

- Sample data is for demonstration only
- Use real JoSAA historical data for production
- Models are saved automatically after training
- Predictions are probabilistic, not guaranteed
- More training data = better predictions

====================================================================
CREATED WITH
====================================================================

Backend: Python 3, Flask, Scikit-learn, XGBoost, Pandas
Frontend: React 18, Vite, Axios
Styling: Custom CSS with gradient themes

====================================================================