README.md

---
language:
- fa
- en
license: apache-2.0
base_model: unsloth/Qwen3-14B-bnb-4bit
tags:
- farsi
- persian
- lora
- adapter
- reasoning
- chain-of-thought
- conversational
- qwen3
datasets:
- artindnr/Persian-Thinking
- xmanii/maux-gpt-sft-20k
pipeline_tag: text-generation
---

# 🍓 Farangis

**Farangis** is a fine-tuned adapter for [Qwen3-14B](https://huggingface.co/Qwen/Qwen3-14B) that brings native Farsi conversational ability and chain-of-thought (CoT) reasoning to the base model. It was trained on a mix of reasoning and non-reasoning Persian data so it can hold a natural conversation *and* think step-by-step in Farsi when a task calls for it.

## Model Details

- **Base model:** Qwen/Qwen3-14B
- **Adapter type:** LoRA (fine-tuned adapter, not a full merge)
- **Language:** Farsi (Persian), with English capability inherited from the base model
- **Capabilities:** general conversation, instruction following, and chain-of-thought reasoning — all in Farsi

## Training Data

Farangis was trained on a mix of two datasets to balance conversational fluency with reasoning ability:

| Dataset | Type | Purpose |
|---|---|---|
| [`artindnr/Persian-Thinking`](https://huggingface.co/datasets/artindnr/Persian-Thinking) | Reasoning | Teaches the model to generate explicit chain-of-thought traces in Farsi before producing an answer |
| [`xmanii/maux-gpt-sft-20k`](https://huggingface.co/datasets/xmanii/maux-gpt-sft-20k) | Non-reasoning (SFT) | Grounds the model in natural, direct Farsi conversation and instruction-following |

Mixing reasoning and non-reasoning examples was intended to let the model reason step-by-step (CoT) when a problem needs it, while still answering straightforward conversational prompts directly and naturally, without over-explaining or forcing unnecessary reasoning traces.

## Intended Use

- Farsi-language chat assistants and conversational agents
- Tasks that benefit from visible step-by-step reasoning in Farsi (math, logic, multi-step Q&A, analysis)
- General-purpose Farsi instruction following

## How to Use

Farangis is distributed as a LoRA adapter on top of Qwen3-14B. Load the base model and apply the adapter with 🤗 PEFT:

```python
from unsloth import FastLanguageModel

BASE_MODEL = "unsloth/qwen3-14b-unsloth-bnb-4bit"
ADAPTER_REPO = "artindnr/qwen3-14b-model-persian-cot-adapter"
MERGED_REPO = "artindnr/farangis"

# Load base model + tokenizer
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name = BASE_MODEL,
    max_seq_length = 2048,
    dtype = None,
    load_in_4bit = False,
)

# Attach the LoRA adapter from the hub
model.load_adapter(ADAPTER_REPO)


messages = [
    {"role" : "user", "content" : "Continue the sequence: 1, 1, 2, 3, 5, 8,"}
]
text = tokenizer.apply_chat_template(
    messages,
    tokenize = False,
    add_generation_prompt = True, # Must add for generation
)

from transformers import TextStreamer
_ = model.generate(
    **tokenizer(text, return_tensors = "pt").to("cuda"),
    max_new_tokens = 512, # Increase for longer outputs
    temperature = 0.7, top_p = 0.8, top_k = 20,
    use_cache = True,
    streamer = TextStreamer(tokenizer, skip_prompt = True),
)
```

## Limitations

- As a LoRA adapter, output quality is bounded by the capabilities of the Qwen3-14B base model.
- Reasoning traces are generated in Farsi and, like any CoT output, are not a guaranteed reflection of the model's internal computation — treat them as an explanation, not ground truth.
- Trained primarily on Farsi data; performance on other languages should be expected to track the base model's baseline, not this adapter's tuning.
- Not evaluated for safety-critical, medical, legal, or financial use.

## Citation

If you use Farangis in your work, please cite this repository along with the training datasets:

```bibtex
@misc{farangis,
  title  = {Farangis: A Farsi Reasoning and Conversation Adapter for Qwen3-14B},
  author = {Artin},
  year   = {2026},
  url    = {https://huggingface.co/<your-namespace>/farangis}
}
```