Update README.md

README.md

@@ -1,29 +1,154 @@
-## Method
+---
+license: mit
+tags:
+- text-to-sql
+- education
+- socratic-learning
+- instruction-tuning
+- sql
+- STEM
+- pedagogy
+datasets:
+- SQL-Instruct
+---
 
-Our approach is structured in three phases to support Socratic SQL instruction for higher education.
+# SQL Socratic Models
 
-### Phase 1: SQL-Instruct Corpus Construction
+## Model Description
 
-We construct **SQL-Instruct**, a domain-specific Socratic instruction corpus, by mining high-quality interactions from Stack Overflow. This platform provides a rich source of real-world misconceptions, debugging challenges, and conceptual difficulties encountered by both students and practitioners, making it well-suited for training models that emphasize understanding over code replication.
+SQL Socratic Models are a collection of fine-tuned large language models designed for **Socratic SQL instruction in higher education**. Unlike standard Text-to-SQL systems, these models are trained to **guide learners through reasoning steps without producing final SQL solutions**, supporting conceptual understanding and active learning in STEM contexts.
 
-To ensure data quality, we filter SQL-tagged questions based on community impact. The resulting dataset reflects substantial engagement, with a cumulative reach of approximately **1.27 billion views** and an average of **128,535 views per question**. For each selected instance, we extract:
-- The core problem description  
-- User-provided SQL attempts (when available)  
-- Executable SQL blocks from the accepted solution  
+Supported architectures:
+- Phi-3
+- Qwen2.5
+- Gemma2
 
-This process yields **9,916 unique questions**, which are then transformed into Socratic instructional data using GPT-4o. We leverage GPT-4o for its strong reasoning capabilities to generate **pedagogical hints and guided reasoning steps**, ensuring that the dataset emphasizes conceptual scaffolding rather than direct answers.
+---
 
-The dataset is intentionally skewed toward higher cognitive complexity, with:
-- **8,604 intermediate-level questions**  
-- **629 advanced-level questions**  
+## Intended Use
 
-Additionally, we identify a subset of **531 debugging tasks**, enabling models to learn how to guide students through error identification and correction in SQL queries.
+These models are designed for:
+
+- Teaching SQL concepts in higher education  
+- Supporting STEM learners through guided reasoning  
+- Providing step-by-step Socratic hints for SQL problems  
+- Assisting debugging and conceptual clarification  
+
+### Important Constraint
+The models are intentionally trained to:
+- ✅ Provide reasoning steps and conceptual hints  
+- ❌ Avoid generating complete SQL solutions  
+
+This ensures alignment with pedagogical goals such as scaffolding and learner engagement.
+
+---
+
+## Training Data: SQL-Instruct Corpus
+
+We construct **SQL-Instruct**, a domain-specific Socratic instruction corpus, by mining high-quality interactions from Stack Overflow. This platform captures real-world misconceptions, debugging challenges, and conceptual gaps encountered by learners and practitioners.
+
+### Data Collection
+
+To ensure high-quality instructional signals, we filter SQL-tagged questions based on community impact. The resulting dataset has:
+
+- **1.27 billion total views**  
+- **128,535 average views per question**  
+
+For each selected entry, we extract:
+- Problem descriptions  
+- User-submitted SQL attempts  
+- Executable SQL from accepted solutions  
+
+This yields **9,916 unique questions**.
+
+---
+
+### Socratic Augmentation
+
+Each example is transformed into a Socratic instructional format using GPT-4o, which generates:
+
+- Guided reasoning steps  
+- Conceptual hints  
+- Question decomposition  
+
+This ensures the dataset emphasizes **instructional scaffolding rather than answer generation**.
+
+---
+
+### Dataset Composition
+
+- **Intermediate questions:** 8,604  
+- **Advanced questions:** 629  
+- **Debugging tasks:** 531  
+
+The dataset emphasizes challenging reasoning scenarios, particularly:
 
-The corpus spans a wide range of SQL topics, with particular emphasis on:
 - JOIN operations  
-- Aggregation and grouping  
-- Query optimization and performance  
+- Aggregations and grouping  
+- Query optimization  
+
+We further ensure reliability by selecting entries with a **median Stack Overflow score of 27**.
+
+---
+
+## Training Procedure
+
+### Phase 2: Fine-Tuning
+
+We apply **Full Fine-Tuning (FFT)** on small, open-source LLMs under pedagogical constraints designed to:
+
+- Encourage conceptual scaffolding  
+- Promote step-by-step reasoning  
+- Discourage direct SQL answer generation  
+
+---
+
+## Evaluation
+
+### Phase 3 Metrics
+
+Models are evaluated using:
+
+- **BERTScore** → semantic alignment with expected reasoning  
+- **ROUGE-L** → detection of answer leakage (i.e., unintended full SQL generation)  
+
+---
+
+## Key Contributions
+
+- Socratic SQL instruction tuning for higher education  
+- SQL-Instruct dataset derived from real-world misconceptions  
+- Multi-model fine-tuning across Phi-3, Qwen2.5, and Gemma2  
+- Evaluation framework balancing reasoning quality and answer leakage  
+- Ablation study identifying factors enabling:
+  - Misconception-based feedback  
+  - Iterative guidance  
+  - Instructor-like reasoning behavior  
+
+---
+
+## Limitations
+
+- Models may still occasionally generate partial SQL fragments  
+- Evaluation focuses on semantic similarity rather than full pedagogical outcomes  
+- Dataset is derived from Stack Overflow and may reflect community biases  
+
+---
+
+## Ethical Considerations
+
+These models are designed to support learning, not replace it. By avoiding full solution generation, they aim to:
+
+- Encourage critical thinking  
+- Reduce over-reliance on AI-generated answers  
+- Support equitable access to SQL learning resources  
+
+---
+
+## Usage
 
-By selecting questions with a **median Stack Overflow score of 27**, we ensure that the underlying solutions—and therefore the derived instructional signals—are technically reliable.
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-This corpus serves as the foundation for training models that prioritize **Socratic reasoning, misconception-aware feedback, and conceptual understanding** over direct SQL solution generation.
+model = AutoModelForCausalLM.from_pretrained("sriram882004/SQL-Socratic-Models/phi3_rq4")
+tokenizer = AutoTokenizer.from_pretrained("sriram882004/SQL-Socratic-Models/phi3_rq4")