README.md

---
base_model: Qwen/Qwen3-VL-8B-Instruct
library_name: peft
pipeline_tag: text-generation
tags:
- base_model:adapter:Qwen/Qwen3-VL-8B-Instruct
- lora
- peft
- vision-language
- qwen3-vl
- coding
- math
- darija
- fine-tuned
- beginner-friendly
license: apache-2.0
---

# 🧠 Mtrini-SVL-1.0 (Adapter)

> **Mtrini** (متربّي) comes from **Darija** — Moroccan Arabic — and means
> **"trained"** or **"well-fit."** 💪 That's exactly what this model is: a
> smart base model that we trained a little further to be great at **coding**
> and **math** — while still being able to **see images.** 👀

---

## 🤔 What is this, in plain English?

There are two pieces here:

1. **A big, powerful base model** 🏗️ — `Qwen3-VL-8B-Instruct`. It already knows
   a lot and can understand both text and images.

2. **A small "adapter"** 🧩 — this is the *Mtrini* part. Instead of retraining
   the whole giant model (expensive! 💸), we trained a lightweight add-on that
   nudges the base model to be better at coding and math.

**This repo is the adapter** 🧩 — the little piece that plugs into the big model.

---

## 📖 What's in the name?

**Mtrini** (متربّي) in Darija means *trained* or *well-fit* — the root
*m-r-b* carries the sense of being raised, cultivated, and prepared. 🌱

That's literally what happened here: a capable foundation model, further
trained on focused data to become *well-fit* for reasoning tasks.

🗣️ *Say it like: "em-tree-nee."*

---

## ✨ What can it do?

| Skill | Description |
|-------|-------------|
| 💻 **Coding** | Write functions, fix bugs, explain how code works |
| 🧮 **Math** | Solve problems step by step and show its reasoning |
| 👀 **Vision** | Describe images, read screenshots, and answer questions about pictures |

---

## 📚 What was it trained on?

Two public datasets, chosen to make it sharp at reasoning:

| 📦 Dataset | 🎯 Focus |
|-----------|----------|
| `Bespoke-Stratos-17k` | Coding & problem-solving |
| `OpenR1-Math-220k` | Mathematical reasoning |

---

## 🔧 Technical details (for the curious)

| Setting | Value |
|---------|-------|
| 🏗️ Base model | `Qwen/Qwen3-VL-8B-Instruct` (8.81B params) |
| 🧩 Adapter type | LoRA (rank 16) |
| 🎯 Target modules | Attention + MLP projections |
| 📏 Context length | 2048 |
| 🚀 Learning rate | 2e-4 |
| 🔢 Max steps | 1000 |

> **LoRA** stands for *Low-Rank Adaptation* — a clever way to fine-tune a big
> model by training only a tiny fraction of its weights. That's why the adapter
> is small and fast to share. 🪶

---

## 🚀 How to use it

```python
import torch
from transformers import Qwen3VLForConditionalGeneration, AutoProcessor
from peft import PeftModel

# 1️⃣ Load the big base model
base = Qwen3VLForConditionalGeneration.from_pretrained(
    "Qwen/Qwen3-VL-8B-Instruct",
    dtype=torch.bfloat16,
    device_map="auto",
    attn_implementation="sdpa",
)

# 2️⃣ Plug in the Mtrini adapter
model = PeftModel.from_pretrained(base, "CompiwerAI/Mtrini-SVL-1.0")

# 3️⃣ Load the processor (handles text + images)
processor = AutoProcessor.from_pretrained("CompiwerAI/Mtrini-SVL-1.0")

model.eval()
```

---

## 📦 Want to skip the setup? Use the GGUF!

If all that Python looks intimidating, we've got you covered. 🙂 We **merged**
the adapter into the base model and **quantized** it into a single file you can
run locally with no Python at all:

👉 **[CompiwerAI/Mtrini-SVL-1.0-GGUF](https://huggingface.co/CompiwerAI/Mtrini-SVL-1.0-GGUF)**

- 🗜️ One file, ~8.7 GB
- 🖥️ Runs with [llama.cpp](https://github.com/ggml-org/llama.cpp)
- 🖼️ Vision included — no extra files needed

---

## ⚠️ Things to keep in mind

- It's trained for a relatively short schedule (1000 steps) on a focused mix.
- It inherits both the strengths and the limitations of the base model.
- 🧪 Always test on **your** use case before relying on it in production.

## 📜 License

Apache 2.0 — same as the base model. ✅