Model Card for Phi-3.5-mini-Socratic-Coding-Tutor

Phi-3.5-mini-Socratic-Coding-Tutor is a fine-tuned LoRA adapter built on top of microsoft/Phi-3.5-mini-instruct using 8-bit QLoRA. It is designed to act as an expert Socratic programming tutor following the PACT (Pedagogical Alignment for Coding Tutors) methodology.

Rather than outputting complete copy-paste solutions immediately, the model engages developers interactively—probing conceptual understanding, asking targeted debugging questions, highlighting edge cases, and guiding learners to discover and resolve bugs on their own.

---

Model Details

Model Description

• Developed by: Kami0867
• Model type: 8-bit QLoRA PEFT Adapter for Causal Language Modeling
• Base Model: microsoft/Phi-3.5-mini-instruct
• Language(s) (NLP): English
• License: MIT
• Finetuned from model: microsoft/Phi-3.5-mini-instruct
• Training Dataset: AndreiSobo/PACT-Socratic-Coding-Tutor
• Target Hardware: Consumer GPUs with 8GB VRAM (e.g., RTX 5060 Ti / RTX 4060)

Model Sources

• Hugging Face Hub Repository: Kami0867/Phi-3.5-mini-Socratic-Coding-Tutor
• Base Architecture Paper: Phi-3 Technical Report

---

Uses

Direct Use

• Interactive Coding Pedagogy: Guiding students and software engineers through algorithmic challenges (data structures, edge-case analysis, LeetCode style problems).
• Interactive Debugging: Guiding developers to reason through logic bugs, off-by-one errors, and boundary condition failures via targeted questions.
• Codebase Exploration: Providing guided hints and architectural breakdowns when exploring repositories.

Socratic Tutoring Behavioral Guardrails (PACT)

1. Never provide complete code solutions directly unless explicitly requested after multiple repeated failed attempts.
2. Probe boundary conditions and edge cases (e.g., empty arrays, single-item collections, integer overflow, pointer nullability).
3. Decompose complex problems into smaller, manageable milestones.
4. Encourage independent reasoning by acknowledging partial progress before pointing out flaws.

Out-of-Scope Use

• Zero-shot complete script generation or unguided code dump generation.
• Generating malicious exploit payloads, bypassing security constraints, or unverified safety-critical code deployment.

---

How to Get Started with the Model

GitHub: https://github.com/ChiragPrasad2006/Assist-stu You can load and query the model directly using Hugging Face transformers and peft in 8-bit quantization:

import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
from peft import PeftModel

adapter_id = "Kami0867/Phi-3.5-mini-Socratic-Coding-Tutor"
base_model_id = "microsoft/Phi-3.5-mini-instruct"

# 1. Load Tokenizer
tokenizer = AutoTokenizer.from_pretrained(adapter_id, trust_remote_code=True)
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

# 2. Configure 8-bit Quantization (fits in ~3.8 GB VRAM)
bnb_config = BitsAndBytesConfig(
    load_in_8bit=True,
)

# 3. Load Quantized Base Model
base_model = AutoModelForCausalLM.from_pretrained(
    base_model_id,
    quantization_config=bnb_config,
    device_map={"": 0},
    torch_dtype=torch.float16,
    trust_remote_code=True,
    attn_implementation="eager",
)

# 4. Attach Socratic LoRA Adapter
model = PeftModel.from_pretrained(base_model, adapter_id)
model.eval()

# 5. Format Socratic Chat Prompt
messages = [
    {
        "role": "system",
        "content": (
            "You are an expert Socratic Coding Tutor. Your goal is to help developers discover "
            "bugs, design architectures, and reason through code independently. Never generate the "
            "complete solution directly unless explicitly requested after multiple failed attempts. "
            "Provide precise hints, highlight conceptual pitfalls, and ask targeted guiding questions."
        ),
    },
    {
        "role": "user",
        "content": "Why is my binary search getting stuck in an infinite loop when the target is not in the array?",
    },
]

prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to("cuda:0")

# 6. Generate Response
with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        temperature=0.7,
        top_p=0.9,
        do_sample=True,
        use_cache=False,
    )

response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True)
print(response)

---

Training Details

Training Data

• Dataset: AndreiSobo/PACT-Socratic-Coding-Tutor
• Format: Multi-turn conversational dialogues demonstrating Socratic interaction patterns, progressive hints, and guided queries.
• Max Sequence Length: 1024 tokens

Training Procedure

Fine-tuned using Supervised Fine-Tuning (SFT) with QLoRA via Hugging Face peft and trl.

LoRA Hyperparameters

• LoRA Rank ($r$): 16
• LoRA Alpha ($\alpha$): 32
• LoRA Dropout: 0.05
• Target Modules: ["qkv_proj", "o_proj", "gate_up_proj", "down_proj"]
• Bias: "none"
• Task Type: CAUSAL_LM

Training Hyperparameters

• Epochs: 4.0
• Per-Device Batch Size: 1
• Gradient Accumulation Steps: 8
• Effective Batch Size: 8
• Learning Rate: $2 \times 10^{-4}$
• Learning Rate Schedule: Cosine decay with warmup
• Warmup Ratio: 0.05
• Weight Decay: 0.01
• Optimizer: paged_adamw_8bit
• Quantization: 8-bit normal float via bitsandbytes
• Precision: FP16 mixed precision

---

Evaluation

Evaluation Metrics

Evaluated on a held-out test split of the PACT Socratic Coding dataset:

Metric	Result
Evaluation Loss	0.564
Token Accuracy	85.48%
Perplexity	1.758

Qualitative Findings

• Consistent avoidance of raw copy-paste code dumps.
• High accuracy in pinpointing algorithmic pitfalls (recursion base cases, index off-by-one, null references).
• Concise and interactive conversational style.

---

Technical Specifications & Environmental Impact

• Hardware Used: Single NVIDIA GeForce RTX 5060 Ti (8GB VRAM)
• Peak VRAM During Training: ~6.2 GB
• Peak VRAM During Inference: ~3.84 GB
• Compute Provider: Local workstation
• Estimated Carbon: < 0.15 kg CO2eq for 4 epochs