Update README.md

README.md

@@ -1,23 +1,145 @@
 ---
+language:
+- en
+license: other
+license_name: qianwen
+license_link: https://huggingface.co/Qwen/Qwen3-4B/blob/main/LICENSE
+base_model:
+- Qwen/Qwen3-4B
 tags:
-- gguf
-- llama.cpp
+- fine-tuned
+- education
+- python
+- socratic
+- qlora
 - unsloth
+---
+
+# Fyve-AI
+
+**Fyve-AI** is a fine-tuned version of [Qwen3-4B](https://huggingface.co/Qwen/Qwen3-4B) trained for one specific task: reading a student's broken Python code and responding with a Socratic 3-sentence hint — not the answer.
+
+It is the AI model powering [PyFyve](https://github.com/Macmill-340/PyFyve), a fully offline Python tutoring application.
+
+---
+
+## What It Does
+
+Given a task description, the student's buggy code, and the Python error it produced, the model outputs a JSON object with two fields:
+
+- `reasoning` — internal diagnosis of what went wrong and why
+- `hint` — exactly 3 sentences following a fixed structure:
+  1. **Diagnosis** — names the specific variable, expression, or construct that caused the error
+  2. **Rule** — states the Python rule that was violated
+  3. **Directive** — starts with *"Think about..."* or *"Consider..."* and guides without giving the fix
+
+The model never gives corrected code. It never gives more than 3 sentences. It does not know how to do anything outside this task.
+
+---
+
+## Input Format
+
+```
+Task:
+<what the student was asked to do>
+Code:
+<the student's broken code>
+Error:
+<the Python error message>
+```
+
+---
+
+## Output Format
+
+```json
+{
+  "reasoning": "...",
+  "hint": "Sentence 1.\nSentence 2.\nSentence 3."
+}
+```
+
+---
+
+## Example
+
+**Input:**
+```
+Task:
+Create a variable score = 95 and print its value.
+Code:
+score = 95
+print(Score)
+Error:
+NameError: name 'Score' is not defined at line 2
+```
+
+**Output:**
+```json
+{
+  "reasoning": "score is defined lowercase but Score (capital S) is used in print. I name both spellings, explain case sensitivity, and direct toward comparing the two usages.",
+  "hint": "You defined a variable called score on line 1 but referenced Score on line 2.\nIn Python, variable names are case-sensitive, so score and Score are treated as two completely different identifiers.\nConsider whether the capitalisation of the variable name is consistent between where it was defined and where it is used."
+}
+```
 
 ---
 
-# qwen-finetune-v3 : GGUF
+## Training Details
 
-This model was finetuned and converted to GGUF format using [Unsloth](https://github.com/unslothai/unsloth).
+| Detail | Value |
+|--------|-------|
+| Base model | Qwen3-4B |
+| Method | QLoRA via [Unsloth](https://github.com/unslothai/unsloth) |
+| Hardware | Google Colab T4 (free tier) |
+| Dataset | 555 curated (task, code, error, hint) pairs |
+| Dataset source | Synthetic — generated using Qwen3-30B-A3B as teacher model |
+| Error types covered | SyntaxError, NameError, TypeError, IndexError, KeyError, ValueError, AttributeError, UnboundLocalError, RecursionError, ZeroDivisionError, and more |
 
-**Example usage**:
-- For text only LLMs:    `llama-cli -hf Macmill/qwen-finetune-v3 --jinja`
-- For multimodal models: `llama-mtmd-cli -hf Macmill/qwen-finetune-v3 --jinja`
+The training data was generated by a 30B teacher model, manually reviewed for quality, and filtered through a validation pipeline that checks hint structure, sentence count, and semantic rules (e.g. AttributeError on strings must guide toward `+` or `+=`, not list conversion).
+
+---
+
+## Intended Use
+
+This model is designed exclusively for use inside the PyFyve app. It is not a general-purpose assistant and will produce poor results for tasks outside its training distribution.
+
+**It is not designed to:**
+- Answer general Python questions
+- Explain concepts freely
+- Write or complete code
+- Serve as a chatbot
+
+---
+
+## Limitations
+
+- Trained on 555 examples — covers common beginner and intermediate Python errors well, but unusual or advanced errors may produce weaker hints
+- No coverage of logic errors (code that runs but produces wrong output)
+- Some uncommon syntax patterns (e.g. trailing comma creating a tuple) are outside the training distribution
+- The 3-sentence format is enforced by the prompt at inference time — removing the few-shot examples from the prompt degrades output quality significantly
+
+---
+
+## Usage with Ollama
+
+This model is distributed as a GGUF file for use with [Ollama](https://ollama.com). The `Modelfile` in this repository contains the Ollama model definition.
+
+```bash
+ollama create fyve-ai -f Modelfile
+```
+
+Or use the PyFyve app, which handles setup automatically.
+
+---
+
+## License
+
+The fine-tuned weights are released under the same license as the base model: the [Qianwen License](https://huggingface.co/Qwen/Qwen3-4B/blob/main/LICENSE).
+
+Please read it before redistributing — it permits research and personal use but has restrictions on commercial use above certain usage thresholds.
+
+---
 
-## Available Model files:
-- `qwen3-4b-instruct-2507.Q4_K_M.gguf`
+## Citation
 
-## Ollama
-An Ollama Modelfile is included for easy deployment.
-This was trained 2x faster with [Unsloth](https://github.com/unslothai/unsloth)
-[<img src="https://raw.githubusercontent.com/unslothai/unsloth/main/images/unsloth%20made%20with%20love.png" width="200"/>](https://github.com/unslothai/unsloth)
+If you use this model in research or build on it, please link back to the [PyFyve repository](https://github.com/Macmill-340/PyFyve).