y-gemma4-svg-lora-enhanced

# y-gemma4-svg-lora-enhanced

QLoRA adapter for **Y**, a local-first AI whiteboard tutor built for the [Gemma 4 Good Hackathon](https://www.kaggle.com/competitions/gemma-4-good-hackathon).

This adapter fine-tunes Gemma 4 E4B to emit an SVG-native whiteboard tutoring DSL:

- `[text: "..."]` for narrated whiteboard captions
- `[draw_part: name="..." viewBox="..."]` for named diagram parts
- raw SVG path-data or whitelisted SVG elements per line
- `[/draw_part]` to close each drawable part

The goal is to move Y toward a tutor that can write and draw step-by-step on a whiteboard, closer to how a human teacher explains visual ideas.

## Base Model

Finetuned from:

`unsloth/gemma-4-e4b-it-unsloth-bnb-4bit`

The notebook loads the model through `FastVisionModel` so the saved adapter + processor remain compatible with multimodal whiteboard inputs at inference time.

## Dataset

Trained on a prepared SVG tutoring dataset built from `duxiaodan/ControlSketch-Part` using Y's dataset preparation pipeline.

Final training set:

- 400 prepared ControlSketch-Part rows
- +40 repeated high-quality syntax anchors
- 440 total training rows

The anchors overrepresent exact tool syntax for examples such as Pythagorean theorem, free-body diagrams, benzene, animal cells, and DFS trees.

## Training Config

- Framework: Unsloth
- Base: `unsloth/gemma-4-e4b-it-unsloth-bnb-4bit`
- Method: QLoRA
- Loader: `FastVisionModel`
- Sequence length: `4096`
- LoRA rank: `r=16`
- LoRA alpha: `32`
- LoRA dropout: `0`
- Bias: `none`
- Target modules: `all-linear`
- Vision layers: frozen
- Audio layers: frozen
- Language layers: trained
- Attention modules: trained
- MLP modules: trained
- Optimizer: AdamW 8-bit
- Learning rate: `1.5e-4`
- Warmup steps: `10`
- Weight decay: `0.01`
- LR schedule: linear
- Batch size: `2`
- Gradient accumulation: `4`
- Effective batch size: `8`
- Epochs: `6`
- Total steps: `330`
- Trainable params: `41,222,144 / 8,037,378,592` (`0.51%`)
- Runtime: `3:14:56` on Kaggle T4
- Seed: `3407`

Training used `train_on_responses_only`, so loss was computed only on assistant/tool-output tokens, not on the system/user prompt.

## Training Loss

| Step | Loss |
| --- | --- |
| 10 | 1.3668 |
| 20 | 0.4403 |
| 50 | 0.3260 |
| 100 | 0.2840 |
| 150 | 0.2740 |
| 200 | 0.2650 |
| 250 | 0.2627 |
| 300 | 0.2599 |
| 330 | 0.2595 |

## Sanity Check

Held-out prompt:

```text
Draw a benzene ring with alternating bonds, decomposing into named parts.

Observed output after training:

[draw_part: benzene ring with alternating bonds]
[draw_part: central hexagon]
[draw_part: six carbon atoms at vertices]
[draw_part: alternating single and double bonds]
[/draw_part]<turn|>

Generation time: 12.36 s

This shows the adapter learned the intended draw_part-style structure, though the output is still early and needs stricter validation/repair before being used as the default renderer.

Usage

from unsloth import FastVisionModel

model, processor = FastVisionModel.from_pretrained(
    model_name="QuantumTransformer/y-gemma4-svg-lora-enhanced",
    max_seq_length=4096,
    load_in_4bit=True,
)

FastVisionModel.for_inference(model)

Example Target Format

[text: "First draw the carbon skeleton."]
[draw_part: name="carbon skeleton" viewBox="0 0 400 300"]
M 200 80 L 280 130 L 280 220 L 200 270 L 120 220 L 120 130 Z
[/draw_part]
[text: "Now add the alternating bonds."]
[draw_part: name="alternating bonds" viewBox="0 0 400 300"]
M 210 95 L 265 130
M 265 220 L 210 255
M 135 130 L 190 95
[/draw_part]

Project Context

This model is part of Y, an AI learning companion that reads a student's whiteboard and writes an explanation back onto the same canvas.

The current Y demo uses a robust deterministic primitive renderer for reliability. This LoRA is the research path toward a more SVG-native teacher: a model that can generate named diagram parts directly while preserving the step-by-step whiteboard teaching style.

Links

• Enhanced adapter: https://huggingface.co/QuantumTransformer/y-gemma4-svg-lora-enhanced
• Original adapter: https://huggingface.co/QuantumTransformer/y-gemma4-svg-lora
• Hackathon: https://www.kaggle.com/competitions/gemma-4-good-hackathon

License

Published as Apache-2.0 on Hugging Face. Users should also comply with the upstream Gemma model terms.