Virtual Student Assistant (PCMB)

A Python-based academic assistant that classifies and answers questions related to Physics, Chemistry, Mathematics, and Biology (PCMB). This project includes a custom-built machine learning ensemble (Logistic Regression, Naive Bayes, and K-Nearest Neighbors) to categorize queries, estimate difficulty, and retrieve relevant answers from a dataset.

It provides both a Command Line Interface (CLI) for training and evaluation, and a Flask-based Web Application for a user-friendly browser interface.

✨ Features

• Subject Classification: Uses an ensemble of custom-built Logistic Regression, Naive Bayes, and KNN models to accurately classify questions into Physics, Chemistry, Mathematics, or Biology.
• Semantic Question Retrieval: Matches student queries against a dataset using TF-IDF vectorization (word and character n-grams) with cosine and lexical similarity to find the closest matches and provide full answers/solutions.
• Difficulty Estimation: Evaluates the difficulty of a question (Easy, Medium, Hard) based on word count, LaTeX formula density, multi-part markers, and solution length.
• Spell Correction: Automatically corrects out-of-vocabulary words in user queries using a custom Levenshtein distance implementation.
• Analytics & Metrics: Tracks session analytics (subject distributions, difficulty distributions, confidences) and displays model evaluation metrics (F1 score, Precision, Recall).
• Web Interface: A responsive Flask application that allows users to interact with the assistant directly from their browser.

📁 Project Structure

• app.py: The main Flask web server application.
• main_modular.py: Core logic including data processing, custom ML model implementations (LR, NB, KNN), TF-IDF vectorization, spell correction, and CLI for training.
• requirements.txt: Python dependencies.
• pcmb-ots-dataset/: Directory containing the dataset files (sample_*_n.xlsx).
• templates/: HTML templates for the Flask web application (index.html, metrics.html).
• pcmb_subject_artifacts.pkl: Cached artifacts generated after training the models (vocabularies, weights, indices).

🚀 Installation & Setup

1. Clone the repository (if you haven't already):

   git clone <repository-url>
   cd virtual-student-assistant

2. Install the required dependencies: Make sure you have Python installed. Install the dependencies using pip:

   pip install -r requirements.txt

   (Dependencies include flask, numpy, pandas, and openpyxl)

3. Provide the Dataset: Ensure your PCMB dataset Excel files (sample_*_n.xlsx) are located inside the pcmb-ots-dataset/ directory.

🛠️ Usage

1. Train the Models

Before running the web app for the first time, you must train the models and generate the required artifacts. This parses the dataset, trains the ML ensemble, and caches the weights into pcmb_subject_artifacts.pkl.

python main_modular.py

Note: This script will evaluate the dataset, build feature spaces, train Logistic Regression, Naive Bayes, and KNN models, and save the state.

2. Run the Web Server

Once the models are trained, you can start the Flask application:

python app.py

3. Access the Web Interface

Open your web browser and navigate to:

http://127.0.0.1:5000/

From here, you can enter any academic question, and the assistant will classify it, estimate its difficulty, and try to find a matching solution.

📊 Endpoints

• GET / : Main chat interface.
• POST /api/query : Accepts a JSON payload {"query": "your question"} and returns classification, difficulty, and matched solutions.
• GET /api/stats : Returns the session analytics.
• GET /api/metrics : Returns the model evaluation metrics.
• GET /metrics : Renders the metrics and analytics page.

🧠 Technical Highlights

• No external ML libraries for inference: The core ML models (Logistic Regression, Multinomial Naive Bayes, K-Nearest Neighbors) and metrics (Confusion Matrix, F1, Precision, Recall) are built completely from scratch using numpy.
• Hybrid Search: Retrieves answers by combining dense vector similarity (Cosine) with Keyword boosts and exact matches.
• Smart Spell Checker: Uses a conservative Levenshtein-based algorithm that skips common English/PCMB keywords to prevent false corrections.

---

Built as a comprehensive tool to aid students in solving PCMB academic queries seamlessly.