Upload README.md with huggingface_hub

README.md

@@ -1,7 +1,140 @@
 ---
-language: en
-library_name: mlx
-pipeline_tag: text-generation
+language:
+  - en
+  - sw
+  - ha
+  - yo
+  - ig
+  - am
+  - zu
+  - xh
+  - af
+  - so
+  - rw
+  - sn
+  - tw
+  - ee
+  - wo
+  - ny
+  - ti
+  - nso
+  - tn
+  - om
+  - ve
+  - nd
+  - ar
+  - fr
+  - pt
+  - es
+  - de
+  - zh
+  - ja
+  - ko
+license: mit
 tags:
-- mlx
+  - translation
+  - mlx
+  - apple-silicon
+  - multilingual
+  - african-languages
+pipeline_tag: text2text-generation
+library_name: mlx
 ---
+
+# TranslateBlue v2 (MLX 4-bit)
+
+Translation model focused on **29 languages** with emphasis on **African languages**, in MLX 4-bit format for **Apple Silicon** (M1+ Mac, and mlx-swift on supported devices).
+
+## Model description
+
+- **Base model**: Qwen3-4B-Instruct
+- **Format**: MLX, 4-bit quantized
+- **Size**: ~2.1 GB
+- **Training**: LoRA fine-tuning on parallel translation data (10,000 steps, 16 LoRA layers)
+- **Training data**: 563,986 sentence pairs from 29 languages
+
+## Intended use
+
+- **Text translation** between the supported languages, especially to/from African languages
+- **Offline translation** on Mac (and in apps using mlx-swift where supported)
+- **Low-latency translation** on Apple Silicon with Metal acceleration
+
+## Supported languages (29)
+
+| Code | Language    | Code | Language        | Code | Language        |
+|------|-------------|------|-----------------|------|-----------------|
+| sw   | Swahili     | ha   | Hausa           | yo   | Yoruba          |
+| ig   | Igbo        | am   | Amharic         | zu   | Zulu            |
+| xh   | Xhosa       | af   | Afrikaans       | so   | Somali          |
+| rw   | Kinyarwanda | sn   | Shona           | tw   | Twi             |
+| ee   | Ewe         | wo   | Wolof           | ny   | Chichewa        |
+| ti   | Tigrinya    | nso  | Northern Sotho  | tn   | Tswana          |
+| om   | Oromo       | ve   | Venda           | nd   | Ndebele         |
+| ar   | Arabic      | fr   | French          | pt   | Portuguese      |
+| es   | Spanish     | de   | German          | zh   | Chinese         |
+| ja   | Japanese    | ko   | Korean          | en   | English         |
+
+## Limitations
+
+- **Apple Silicon only** for this MLX build (Mac with M1 or later; mlx-swift on supported iOS/iPadOS when available).
+- Best for **short to medium** sentences; very long texts may lose quality.
+- Low-resource pairs may be less accurate than high-resource ones.
+- No built-in language detection; source and target languages should be specified in the prompt.
+
+## How to use
+
+### Prompt format
+
+Use a clear translation instruction, for example:
+
+```
+Translate from English to Swahili:
+
+Hello, how are you?
+```
+
+### With Python (mlx-lm)
+
+```bash
+pip install mlx mlx-lm
+```
+
+```python
+from mlx_lm import load, generate
+from mlx_lm.sample_utils import make_sampler
+
+model, tokenizer = load("aoiandroid/TranslateBlue-v2-MLX-4bit")
+sampler = make_sampler(temp=0.3, top_p=0.9)
+
+messages = [{"role": "user", "content": "Translate from English to Swahili:\n\nHello, how are you?"}]
+prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+response = generate(model, tokenizer, prompt=prompt, max_tokens=64, sampler=sampler, verbose=False)
+print(response)
+```
+
+### With Swift (mlx-swift / TranslateBlue)
+
+The model is registered as **TranslateBlue v2 (MLX)**. After downloading via the app (or placing the model in the expected path), it runs with MLXModelService using the same prompt format above.
+
+## Training details
+
+| Setting        | Value   |
+|----------------|---------|
+| Base model     | Qwen3-4B-Instruct |
+| Method         | LoRA    |
+| LoRA layers    | 16      |
+| Steps          | 10,000  |
+| Training samples | 563,986 |
+| Validation loss | ~2.5    |
+
+## Related models
+
+- **GGUF version** (llama.cpp, cross-platform): [aoiandroid/TranslateBlue-v2-GGUF](https://huggingface.co/aoiandroid/TranslateBlue-v2-GGUF)
+
+## License
+
+MIT.
+
+## Citation
+
+If you use this model in research or a product, please cite the base model (Qwen3) and the TranslateBlue project as appropriate.