docs/architecture.md

DeBERTa-v3 MCQ Solver — Model Pipeline Architecture

Inference Pipeline

User Input
    │
    ▼
┌─────────────────────────────────────────────────────────────┐
│          GRADIO 5.x MULTI-MODEL WEB APPLICATION             │
│                        (app.py)                             │
│                                                             │
│   ┌──────────────────────────────────────────────────────┐  │
│   │  Model Selector Dropdown                             │  │
│   │   ● DeBERTa-v3-large (0.4B) — Main High-Accuracy    │  │
│   │   ○ DeBERTa-v3-base  (0.2B) — Fast Lightweight      │  │
│   └──────────────────────────────────────────────────────┘  │
│                                                             │
│   ┌────────────────────┐    ┌────────────────────────────┐  │
│   │  QUESTION INPUT     │    │  OPTION INPUTS A–E         │  │
│   │  (freetext)        │    │  (5 parallel textboxes)    │  │
│   └────────────────────┘    └────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│              INFERENCE ENGINE  (predict function)           │
│                                                             │
│   Strategy 1:  Direct PyTorch (local model files)          │
│    ● Load local deberta_v3_large/ checkpoint                │
│    ● Tokenize [CLS] question [SEP] option [SEP]            │
│    ● Run forward pass → logits → argmax → top-3 MAP@3      │
│                                                             │
│   Strategy 2:  HF Serverless Router API (fallback)         │
│    ● POST to router.huggingface.co/hf-inference/models/... │
│    ● Parse JSON response scores → argmax → top-3           │
└─────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│                   OUTPUT DISPLAY                            │
│                                                             │
│   ● Predicted Option (A–E) — large HTML card               │
│   ● Selected Answer Text                                    │
│   ● MAP@3 Ranking Order (e.g. B → A → C)                   │
│   ● Confidence Distribution (Gradio Label widget)          │
└─────────────────────────────────────────────────────────────┘

Model Files (deberta_v3_large/)

File	Purpose
config.json	Model architecture & hyperparameters
tokenizer.json	DeBERTa-v3 fast tokenizer vocabulary
tokenizer_config.json	Tokenizer settings & special tokens
model.safetensors	PyTorch fine-tuned weights (~1.74 GB)

Training Configuration

Parameter	Value
Base Model	microsoft/deberta-v3-large
Task	5-option MCQ Sequence Classification
Head Architecture	num_labels=1 scoring head
Training Strategy	K-Fold Cross-Validation + Early Stopping
Optimizer	AdamW with Linear Warmup
Best Validation MAP@3	1.0000 ✅