README.md

---
language:
- ar
- en
license: apache-2.0
base_model: meta-llama/Llama-3.1-8B
tags:
- llama
- arabic
- egyptian
- coding
- text-generation
- conversational
- unsloth
- trl
- fine-tuned
pipeline_tag: text-generation
library_name: transformers
---

#  Horus-Egy-Coder

**Egyptian Arabic coding assistant** — a fine-tuned Llama 3.1-8B model specialized in helping Arabic and Egyptian developers write, debug, and understand code.

> Built in Egypt 🇪🇬 | Powered by [Unsloth](https://github.com/unslothai/unsloth) + TRL

---

## Model Description

`horus-egy-coder` is a fine-tuned version of `meta-llama/Llama-3.1-8B-Instruct` trained to assist Arabic-speaking developers — with native understanding of Egyptian Arabic technical dialect. It can explain code in Arabic, help debug in conversational Egyptian, and write clean code with Arabic comments.

| Property | Value |
|---|---|
| **Base model** | meta-llama/Llama-3.1-8B-Instruct |
| **Parameters** | 1B (quantized BF16) |
| **Training** | Unsloth + HuggingFace TRL (2x faster) |
| **License** | Apache 2.0 |
| **Language** | Arabic 🇪🇬 / English |
| **Task** | Code generation, explanation, debugging |

---

##  Quick Start

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "BLACK0X80/horus-egy-coder"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

messages = [
    {
        "role": "system",
        "content": "أنت مساعد برمجة بيتكلم عربي مصري. بتشرح الكود بالعربي وبتساعد المطورين."
    },
    {
        "role": "user", 
        "content": "اكتبلي function بـ Python بتحسب الـ factorial"
    }
]

input_ids = tokenizer.apply_chat_template(
    messages,
    tokenize=True,
    add_generation_prompt=True,
    return_tensors="pt"
).to(model.device)

output = model.generate(
    input_ids,
    max_new_tokens=512,
    temperature=0.7,
    do_sample=True
)

print(tokenizer.decode(output[0][input_ids.shape[1]:], skip_special_tokens=True))
```

---

##  Example Interactions

**Example 1 — Code explanation in Arabic:**
```
User: فسرلي الكود ده
      for i in range(len(arr)-1):
          for j in range(len(arr)-i-1):
              if arr[j] > arr[j+1]:
                  arr[j], arr[j+1] = arr[j+1], arr[j]

Model: ده Bubble Sort — خوارزمية ترتيب بسيطة.
       بتعمل loop على الـ array وبتقارن كل عنصر بالي بعده،
       لو العنصر الأكبر جه الأول بتبدلهم...
```

**Example 2 — Debugging:**
```
User: الكود ده بيطلع IndexError، مش عارف ليه
Model: المشكلة في السطر ده... جرب كذا...
```

---

🔢 GGUF Version (للأجهزة المحدودة)

لو جهازك مش عنده GPU كبير، استخدم النسخة المضغوطة:

 [`BLACK0X80/horus-egy-coder-Q4_K_M-GGUF`](https://huggingface.co/BLACK0X80/horus-egy-coder-Q4_K_M-GGUF)

```bash
# تشغيل بـ llama.cpp
./llama-cli -m horus-egy-coder-Q4_K_M.gguf \
  -p "أنت مساعد برمجة عربي مصري." \
  --chat-format llama-3
```

---

##  Training Details

- **Framework:** [Unsloth](https://github.com/unslothai/unsloth) (2x faster training, 60% less memory)
- **Library:** HuggingFace TRL (SFT Trainer)
- **Base:** `unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit`
- **Quantization:** BF16

---

##  Intended Use

 **Good for:**
- شرح الكود بالعربي المصري
- كتابة functions وscripts بـ Python
- Debugging مع تفسير الأخطاء بالعربي
- تعليم البرمجة للمبتدئين العرب

 **Limitations:**
- النموذج fine-tuned على بيانات محدودة — ممكن يغلط في كود معقد جداً
- مش متخصص في لغات غير Python بنفس الكفاءة
- مش مناسب لـ production code بدون مراجعة بشرية

---

##  About HORUS-AI

HORUS-AI is an Egyptian AI initiative focused on building Arabic and Egyptian-dialect AI models. Named after the ancient Egyptian god of knowledge, we aim to make AI accessible to Arabic-speaking developers.

-  GitHub: [BLACK0X80](https://github.com/BLACK0X80)
-  Web: [black0x80.vercel.app](https://black0x80.vercel.app)

---

##  Citation

```bibtex
@misc{horus-egy-coder-2025,
  title={Horus-Egy-Coder: Egyptian Arabic Coding Assistant},
  author={BLACK0X80 and HORUS-AI},
  year={2025},
  url={https://huggingface.co/BLACK0X80/horus-egy-coder},
  note={Fine-tuned from meta-llama/Llama-3.1-8B-Instruct}
}
```

---

*Made with ❤️ in Egypt 🇪🇬*