Update README.md

README.md

@@ -1,87 +1,126 @@
 ---
-title: Translator Model API
+title: Translation Engine API
 emoji: 🌍
 colorFrom: indigo
 colorTo: green
 sdk: docker
 app_port: 7860
 pinned: false
-short_description: Fast CPU-optimized Translation API powered by CTranslate2
+short_description: Multi-model Translation API powered by CTranslate2
 ---
 
-# 🌍 Translator Model API
+# 🌍 Translation Engine API
 
-A lightweight, high-performance Translation API built with **FastAPI** and powered by **CTranslate2 (INT8)** for fast, memory-efficient CPU inference.
+A high-performance, multi-engine Translation API built with **FastAPI** and **Scalar**. 
 
-Models are automatically fetched from Hugging Face on container startup and converted to CTranslate2 INT8 format to minimize RAM consumption and maximize CPU execution throughput.
+This Space serves local CPU-optimized machine learning models alongside cloud API providers. It is designed to act as the primary translation backend for an upcoming **Django web application**, but functions completely as a **standalone REST API**.
 
 ---
 
-## 🚀 Supported Models
+## Interactive API Documentation
 
-| Model Name | Original Source | CT2 INT8 Size | Primary Use Case |
-| :--- | :--- | :--- | :--- |
-| **NLLB 600M** | `facebook/nllb-200-distilled-600M` | ~600 MB | Fast general translation (200+ languages) |
-| **NLLB 1.3B** | `facebook/nllb-200-distilled-1.3B` | ~1.4 GB | Higher quality general translation |
-| **MADLAD 3B** | `google/madlad400-3b-mt` | ~3.1 GB | Multilingual translation across 400+ languages |
-| **Sunbird NLLB 3.3B** | `Sunbird/translate-nllb-3.3b-salt` | ~3.8 GB | Ugandan & East African languages (Luganda, Acholi, Runyankole, Swahili, etc.) |
+Interactive Scalar documentation is hosted directly on the root endpoint:
+👉 **[Open API Docs & Sandbox](/scalar)**
 
 ---
 
-## ⚡ Performance Highlights
+## Available Translation Engines
+
+### 1. Local CPU Models (Offline & Private)
+Local models are automatically downloaded, quantized to **INT8 / GGUF** format, and cached in ephemeral storage for fast CPU execution with minimal RAM footprint.
+
+| Model ID | Provider Name | Base Weights | Precision | Target Languages / Features |
+| :--- | :--- | :--- | :--- | :--- |
+| `nllb` | **NLLB-200 (600M)** | Meta `nllb-200-distilled-600M` | `int8` | Fast general translation (200+ languages) |
+| `nllb_1_3b` | **NLLB-200 (1.3B)** | Meta `nllb-200-distilled-1.3B` | `int8` | Higher accuracy general translation |
+| `afrinllb` | **AfriNLLB (600M)** | `AfriNLP/AfriNLLB-12enc-12dec-full-ft-kd` | `int8` | Knowledge-distilled for 15+ African languages |
+| `madlad` | **MADLAD-400 (3B)** | `google/madlad400-3b-mt` | `int8` | Multilingual translation across 400+ languages |
+| `swahili_gemma` | **Swahili Gemma (1B)** | `CraneAILabs/swahili-gemma-1b-GGUF` | `Q4_K_M` | Fine-tuned for English ↔ Swahili translation |
 
-- **CTranslate2 INT8 Quantization:** Reduces weight footprint by ~75% and speeds up token generation by up to 4–8x on CPU compared to standard PyTorch FP32/FP16 models.
-- **OpenMP Multi-threading:** Configured to parallelize generation across available CPU cores.
-- **Safetensors Support:** Automatically handles Hugging Face `.safetensors` weights during startup conversion.
+### 2. Cloud API Engines (Bring-Your-Own-Key)
+Cloud API providers allow accessing large language models. You can either configure environment variables on the server or pass your API key dynamically in the JSON payload per request.
+
+| Provider ID | Provider Name | Default Model | Required Client Key |
+| :--- | :--- | :--- | :--- |
+| `gemini` | **Google Gemini** | `gemini-1.5-flash` | `api_key` (Gemini API Key) |
+| `groq` | **Groq LLaMA** | `llama-3.3-70b-versatile` | `api_key` (Groq API Key) |
+| `groq_qwen` | **Groq Qwen** | `qwen-2.5-coder-32b` | `api_key` (Groq API Key) |
 
 ---
 
-## 🛠️ API Usage
+## How to Use the API
 
-### Health Check
+### 1. Check Available Engines
 ```bash
 GET /
 ```
 
-### Translate Text
+### 2. Translate via Local Model (e.g., AfriNLLB)
+```bash
+POST /translate
+Content-Type: application/json
+
+{
+    "text": "Is it not a beautiful Tuesday morning?",
+    "source": "eng_Latn",
+    "target": "swh_Latn",
+    "engine": "afrinllb"
+  }
+```
+
+### 3. Translate via Cloud API (Passing API Key dynamically)
+If no server-side API key is set, clients can supply their own key directly:
+
 ```bash
 POST /translate
 Content-Type: application/json
 
 {
-  "model": "sunbird-nllb-3.3b",
-  "text": "Hello, how are you today?",
-  "src_lang": "eng_Latn",
-  "tgt_lang": "lug_Latn"
+  "provider": "gemini",
+  "text": "Good morning, how can I help you today?",
+  "src": "en",
+  "tgt": "sw",
+  "api_key": "YOUR_GEMINI_API_KEY_HERE"
 }
 ```
 
 ---
 
-## 🐳 Local Development (Docker)
+## Environment Variables Configuration
 
-To build and test the container locally:
+If you are hosting this Space yourself or running it locally, you can set optional environment keys in Space Settings:
 
-```bash
-# Build Docker image
-docker build -t translator-api .
+```env
+# Optional Cloud Keys (If set, clients do not need to provide their own keys)
+GEMINI_API_KEY=your_gemini_key
+GROQ_API_KEY=your_groq_key
 
-# Run Docker container mapping port 7860
-docker run -p 7860:7860 -v $(pwd)/data:/data translator-api
+# CTranslate2 / CPU Threading Controls
+OMP_NUM_THREADS=8
+CT2_COMPUTE_TYPE=int8
 ```
 
-## 📜 Citation & Credits
+---
+
+## 📜 Citations & Credits
 
-This Space utilizes [AfriNLLB](https://huggingface.co/AfriNLP/AfriNLLB-12enc-12dec-full-ft-kd) developed by AfriNLP:
+This project builds upon open-source research and model checkpoints from the AI community:
 
+### AfriNLLB
 ```bibtex
 @inproceedings{moslem-etal-2026-afrinllb,
     title = "{A}fri{NLLB}: Efficient Translation Models for African Languages",
     author = "Moslem, Yasmin and Wassie, Aman Kassahun and Gizachew, Amanuel",
     booktitle = "Proceedings of the Seventh Workshop on African Natural Language Processing (AfricaNLP)",
-    month = mar,
     year = "2026",
-    address = "Rabat, Morocco",
-    publisher = "Association for Computational Linguistics",
-    url = "https://openreview.net/forum?id=hVJZNUZBur"
-}
+    publisher = "Association for Computational Linguistics"
+}
+```
+
+### Swahili Gemma
+* Fine-tuned and quantized GGUF weights provided by [Crane AI Labs](https://huggingface.co/CraneAILabs/swahili-gemma-1b-GGUF).
+
+### Meta NLLB-200 & Google MADLAD-400
+* Meta AI: *No Language Left Behind: Scaling Human-Centered Machine Translation*
+* Google Research: *MADLAD-400: A Multilingual Machine Translation Dataset and Model*
+```