README.md

---
base_model: unsloth/gpt-oss-20b-unsloth-bnb-4bit
library_name: peft
tags:
- base_model:adapter:unsloth/gpt-oss-20b-unsloth-bnb-4bit
- lora
- sft
- transformers
- trl
- unsloth
license: apache-2.0
datasets:
- Omartificial-Intelligence-Space/Arabic-gsm8k
language:
- ar
- en
---

# GPT OSS MATH AR


![image/png](https://cdn-uploads.huggingface.co/production/uploads/628f7a71dd993507cfcbe587/j07CoD8SkYpUSrN1-7yA4.png)


Arabic step-by-step math solver fine-tuned from **gpt-oss-20B** using **LoRA (PEFT)** on curated Arabic GSM8K-style problems. The model is instructed to reason **in Arabic** and explain each solution step clearly before giving the final answer.

- **Base model:** `unsloth/gpt-oss-20b-unsloth-bnb-4bit`
- **Parameter-efficient fine-tuning:** LoRA (PEFT) via Unsloth + TRL SFT
- **Primary objective:** Arabic chain-of-thought style arithmetic / word-problem reasoning (grade-school to early middle-school range)
- **License:** Apache-2.0
- **Maintainer:** **Omer Nacar** (Omartificial-Intelligence-Space)

---

# Model summary

- **Name:** `Omartificial-Intelligence-Space/gpt-oss-math-ar`  
- **Size:** 20B (adapter on top of the base)  
- **Languages:** Arabic (primary), English (instructions/support)  
- **Capabilities:** Step-by-step solutions to math word problems, showing intermediate calculations in Arabic, ending with a concise final result line.  
- **Intended use:** Educational assistance, practice solutions, and Arabic math reasoning research.

> ⚠️ **Note on reasoning:** The model is optimized to *write out* reasoning steps in Arabic. For sensitive use cases (exams, grading, or high-stakes evaluation), always verify outputs.

---

# Example usage (Transformers + Unsloth)

```python
from unsloth import FastLanguageModel
from transformers import TextStreamer
import torch

max_seq_length = 1024
dtype = None  # auto-detect

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="Omartificial-Intelligence-Space/gpt-oss-math-ar",
    dtype=dtype,
    max_seq_length=max_seq_length,
    load_in_4bit=True,
    full_finetuning=False,
)

messages = [
    {"role": "system", "content": "reasoning language: Arabic\n\nYou are an Arabic AI math questions solver that solves math problems step-by-step and explian in Arabic language only."},
    {"role": "user", "content": "بطات جانيت تضع 16 بيضة في اليوم. فهي تأكل ثلاث منها على الفطور كل صباح وتخبز الكعك لأصدقائها كل يوم بأربع منها. إنها تبيع ما تبقى منها في سوق المزارعين كل يوم مقابل دولارين لكل بيضة بطازجة. كم تجني من الدولار كل يوم في سوق المزارعين؟"},
]
inputs = tokenizer2.apply_chat_template(
    messages,
    add_generation_prompt = True,
    return_tensors = "pt",
    return_dict = True,
    reasoning_effort = "low",
).to(model2.device)
from transformers import TextStreamer
_ = model2.generate(**inputs, max_new_tokens = 256, streamer = TextStreamer(tokenizer2))
```

**Prompting tip:** Keep the **system** message as above so the model stays in Arabic and explains step-by-step.

---

# Training data

- **Primary dataset (fine-tuning):** `Omartificial-Intelligence-Space/Arabic-gsm8k-v2`  
  Curated Arabic word problems with gold step-by-step solutions.

- **Evaluation set (unseen):** `Omartificial-Intelligence-Space/Arabic-gsm8k` (`main_test` split)

### Sample training examples

```
[ { "content": "reasoning language: Arabic\n\nYou are an Arabic AI math questions solver that solves math problems step-by-step and explian in Arabic language only.", "role": "system" },
  { "content": "باعت نتاليا مشابك إلى 48 من أصدقائها في شهر أبريل، ثم باعت نصف ذلك العدد من المشابك في شهر مايو. كم عدد المشابك التي باعتها نتاليا في شهري أبريل ومايو معًا؟", "role": "user" },
  { "content": "باعت ناتاليا 48 ÷ 2 = 24 مشبكًا في مايو.\nباعت ناتاليا 48 + 24 = 72 مشبكًا في أبريل ومايو مجتمعين.\n#### 72", "role": "assistant" } ]
```

```
[ { "content": "reasoning language: Arabic\n\nYou are an Arabic AI math questions solver that solves math problems step-by-step and explian in Arabic language only.", "role": "system" },
  { "content": "تقرأ جولي كتاباً مؤلفاً من 120 صفحة. بالأمس، تمكنت من قراءة 12 صفحة، واليوم قرأت ضعف عدد الصفحات التي قرأتها بالأمس. إذا أرادت قراءة نصف ما تبقى من صفحات غداً، كم صفحة عليها أن تقرأ؟", "role": "user" },
  { "content": "قرأت مايلا اليوم 12 × 2 = 24 صفحة.\nلذلك فإن إجمالي ما قرأته منذ الأمس هو 12 + 24 = 36 صفحة.\nتبقى 120 - 36 = 84 صفحة ليتم قراءتها.\nوبما أنها تريد قراءة نصف الصفحات المتبقية غدًا، فيجب عليها أن تقرأ 84/2 = 42 صفحة.\n#### 42", "role": "assistant" } ]
```

---

# Training procedure

**Frameworks:** Unsloth, Transformers, TRL (SFT)  
**Method:** Supervised fine-tuning with LoRA adapters

### LoRA & optimization (Unsloth)
```python
model = FastLanguageModel.get_peft_model(
    model,
    r = 16,
    target_modules = ["q_proj", "k_proj", "v_proj", "o_proj",
                      "gate_proj", "up_proj", "down_proj"],
    lora_alpha = 16,
    lora_dropout = 0,
    bias = "none",
    use_gradient_checkpointing = "unsloth",
    random_state = 3407,
    use_rslora = False,
    loftq_config = None,
)
```

### SFT configuration (TRL)
```python
from trl import SFTConfig, SFTTrainer
trainer = SFTTrainer(
    model = model,
    tokenizer = tokenizer,
    train_dataset = dataset,
    args = SFTConfig(
        per_device_train_batch_size = 16,
        gradient_accumulation_steps = 1,
        warmup_steps = 100,
        num_train_epochs = 3,
        learning_rate = 2e-4,
        logging_steps = 100,
        optim = "adamw_8bit",
        weight_decay = 0.01,
        lr_scheduler_type = "linear",
        seed = 3407,
        output_dir = "outputs",
        report_to = "none",
    ),
)
```

**Hardware:** Colab A100 40GB  
**Seed:** 3407

---

**Recommended generation (starting point):**
- `max_new_tokens`: 128–384 for typical word problems
- `temperature`: 0.1–0.5 (lower for deterministic math)
- `top_p`: 0.8–0.95
- `repetition_penalty`: ~1.05 (optional)

---

# Prompting guide (Arabic)

- Keep the **system** instruction fixed to enforce Arabic step-by-step reasoning.
- Provide one math word problem per turn.
- Expect answers in this shape:
  - Short steps showing operations
  - A final line like: `#### <النتيجة>`

**Example:**
```
[system] reasoning language: Arabic

You are an Arabic AI math questions solver that solves math problems step-by-step and explian in Arabic language only.
[user] لدى متجر 75 قطعة حلوى. باع 18 قطـعة في الصباح و 23 في المساء. كم تبقى؟
```

---

# Evaluation

- **Unseen test set:** `Omartificial-Intelligence-Space/Arabic-gsm8k` (`main_test`)  
- **Current status:** qualitative checks on arithmetic and simple word-problems; formal benchmark numbers can be added once computed.  
- **Suggested protocol:** exact-match on the final `#### <number>` line; optional step-accuracy analysis for intermediate calculations.

---

# Intended use & limitations

**Intended use**
- Educational demos, tutoring aids, and research on Arabic mathematical reasoning.
- Generating step-by-step worked examples for practice problems.

**Limitations**
- May hallucinate or miscompute under distribution shift or very long contexts.
- Not a substitute for professional instruction or grading.  
- Arabic is primary; performance in other languages is not targeted.

**Safety & responsible use**
- Verify outputs before use in assessment settings.
- Avoid using the model to complete academic work where external assistance is prohibited.

---

# Model card contacts & citation

**Author/Maintainer:** **Omer Nacar** — Omartificial-Intelligence-Space  
**Model page:** https://huggingface.co/Omartificial-Intelligence-Space/gpt-oss-math-ar

**Please cite:**
```
@model{gpt_oss_math_ar_oi_space,
  title   = {gpt-oss-math-ar: Arabic Step-by-Step Math Reasoning Adapter for gpt-oss-20B},
  author  = {Omer Nacar},
  year    = {2025},
  howpublished = {\url{https://huggingface.co/Omartificial-Intelligence-Space/gpt-oss-math-ar}}
}
```

Also cite the base and tooling:
- Unsloth, TRL, and Hugging Face Transformers
- Base model: `unsloth/gpt-oss-20b-unsloth-bnb-4bit`
- Datasets: `Omartificial-Intelligence-Space/Arabic-gsm8k` and `Arabic-gsm8k-v2`

---

# License

This adapter is released under **Apache-2.0**. Users must also comply with the licenses and terms of the **base model** and any datasets used.
---

# Changelog

- Initial public release of `gpt-oss-math-ar` (adapter on gpt-oss-20B) with Arabic step-by-step math reasoning and example inference code.