# jatin-mehra119/map-charting-student-math-misunderstandings-solution architecture

> Architecture diagram of the GitHub repository jatin-mehra119/map-charting-student-math-misunderstandings-solution, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution
- Repository: https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution

## Overview

##### Project Type & Purpose
- This is an ML pipeline for a Kaggle competition (“MAP – Charting Student Math Misunderstandings”).
- Its goal is to preprocess labelled student-response data, train six LLM-based classifiers with diverse tuning methods (LoRA, QLoRA, full fine-tune), and ensemble their outputs to maximize MAP@3.

##### Main Architectural Components
a. Data Ingestion & Storage
- Source: Kaggle dataset (CSV files for train/test).
- Tools: pandas, scikit-learn LabelEncoder.
b. Data Preprocessing & Feature Engineering
- Text assembly: “Question,” “Answer,” “Is Correct,” “Student Explanation.”
- Feature engineering:
- Create “target” = Category + ":" + Misconception
- Encode “label” via LabelEncoder
- Correct answers per QuestionId and flag `is_correct`
- (Additional) Derive features such as answer length, token counts, POS tag ratios, or domain-specific flags (e.g., decimal–whole number confusion indicator).
c. Model Training Modules (Parallel)
- Hunyuan 7B (LoRA)
- Qwen 3 4B (LoRA)
- Qwen 2 8B (QLoRA)
- Qwen 3 14B (QLoRA)
- Qwen 3 8B (Full FT)
- DeepseekMath 7B (Full FT)
- Shared tech: HuggingFace Transformers, PEFT, BitsAndBytes, PyTorch, GPUs.
d. Prediction Extraction
- Each model generates logits → softmax → top-K probabilities.
- Intermediate storage: numpy arrays or serialized JSON.
e. Ensemble Aggregator
- Combines model outputs via weighted probability sum, agreement bonus, confidence bonus.
- Applies family-based filtering (True_/False_ families) and backfills to ensure 3 outputs.
f. Inference & Submission
- Notebook (`inference notebook.ipynb`) that loads ensemble scores, formats submission CSV for Kaggle.
g. Write-up & Documentation
- `writeup.md` for methodology; `README.md` for overview.

##### Relationships & Data Flows
- Each Model → Prediction Extraction → feeds into Ensemble Aggregator
- Ensemble → Inference Notebook → Submission

##### Architectural Patterns & Principles
- Pipeline pattern with clear separation of concerns.
- Parallel training modules to exploit model diversity.
- Ensemble design for robustness and improved generalization.
- Modular feature engineering to decouple raw data transforms from model code.

##### Key Technologies & Frameworks
- Python, pandas, scikit-learn LabelEncoder
- HuggingFace Transformers + PEFT (LoRA, QLoRA)
- BitsAndBytes for 4-bit quantization
- PyTorch on GPU clusters (L4 instances)
- NumPy for probability handling

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    DataIngest["Data Ingestion & Storage\n(pandas, CSV)"]:::ingest
    Preprocess["Data Preprocessing & Feature Engineering\nFeature Engineering: token_count, answer_length, POS_ratios, decimal_whole_confusion_flag"]:::ingest

    %% Model Training Cluster
    subgraph "Model Training Modules" 
        direction TB
        Hunyuan["Hunyuan 7B (LoRA)\nHuggingFace, PEFT"]:::model
        Qwen34["Qwen 3 4B (LoRA)\nHuggingFace, PEFT"]:::model
        Qwen28["Qwen 2 8B (QLoRA)\nHuggingFace, BitsAndBytes"]:::model
        Qwen314["Qwen 3 14B (QLoRA)\nHuggingFace, BitsAndBytes NF4"]:::model
        Qwen38["Qwen 3 8B (Full FT)\nPyTorch, GPUs"]:::model
        Deepseek["DeepseekMath 7B (Full FT)\nPyTorch, GPUs"]:::model
    end

    %% Prediction Extraction
    PredExtract["Prediction Extraction\n(logits→softmax→top-K)"]:::model

    %% Ensemble Aggregator
    Ensemble["Ensemble Aggregator\n34% prob sum,33% agreement,33% confidence"]:::ensemble

    %% Inference & Submission
    Inference["Inference & Submission\nFormats CSV"]:::inference

    %% Documentation
    README["README.md"]:::doc
    Writeup["writeup.md"]:::doc

    %% Connections
    DataIngest --> Preprocess
    Preprocess --> Hunyuan
    Preprocess --> Qwen34
    Preprocess --> Qwen28
    Preprocess --> Qwen314
    Preprocess --> Qwen38
    Preprocess --> Deepseek

    Hunyuan --> PredExtract
    Qwen34 --> PredExtract
    Qwen28 --> PredExtract
    Qwen314 --> PredExtract
    Qwen38 --> PredExtract
    Deepseek --> PredExtract

    PredExtract --> Ensemble
    Ensemble --> Inference

    %% Documentation dotted references
    README -.-> DataIngest
    README -.-> Ensemble
    Writeup -.-> Preprocess
    Writeup -.-> Ensemble

    %% Click Events
    click Hunyuan "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Hunyaun 7B-0.945.py"
    click Qwen34 "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Qwen 3 4B-0.945.py"
    click Qwen28 "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Qwen 2-0.945.py"
    click Qwen314 "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Qwen 3 14B-0.944.py"
    click Qwen38 "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Qwen 3 8B-0.944.py"
    click Deepseek "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/training scripts/Deepseek Math 7B-.944.py"
    click Inference "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/inference notebook.ipynb"
    click README "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/README.md"
    click Writeup "https://github.com/jatin-mehra119/map-charting-student-math-misunderstandings-solution/blob/main/writeup.md"

    %% Styles
    classDef ingest fill:#e0f7fa,stroke:#0288d1,color:#000
    classDef model fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef ensemble fill:#fff3e0,stroke:#ef6c00,color:#000
    classDef inference fill:#f3e5f5,stroke:#8e24aa,color:#000
    classDef doc fill:#f5f5f5,stroke-dasharray: 5 5,stroke:#757575,color:#000
```
