Update README.md

README.md

@@ -1,301 +1,71 @@
-# The Translator App
-
-A Django web application for text translation, with a **separate backend model
-API** (FastAPI) in `backend/` that serves translation engines and model
-inference.
-
 ---
-
-## 1. System overview
-
-This repository contains two runtime components:
-
-| Component | Location | Responsibility |
-|---|---|---|
-| Frontend + app logic | `translator_app/` (Django) | UI, form submission, model selection, translation history persistence, cache, and orchestration of translation requests |
-| Model-serving API | `backend/` (FastAPI) | Exposes `/api/translate`, `/api/engines`, `/api/languages`, and routes requests to available providers (NLLB/MADLAD/Ollama/Gemini/Groq) |
-
-High-level request flow:
-
-1. User submits text on Django page (`/`).
-2. Django `translate_api` view validates input and calls `TranslationService`.
-3. `TranslationService` maps app language codes to FLORES-200 codes and calls `MODEL_API_URL`.
-4. FastAPI backend dispatches to the selected provider/engine.
-5. Django stores translation in `TranslationHistory` and returns JSON to the UI.
-
+title: Translator Model API
+emoji: 🌍
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+short_description: Fast CPU-optimized Translation API powered by CTranslate2
 ---
 
-## 2. Repository structure
-
-```text
-.
-├── translator_app/                  # Django app (user-facing application)
-│   ├── translator_project/          # Django project config
-│   ├── translator/                  # App: models, views, services, templates
-│   └── manage.py
-├── backend/                         # FastAPI model-serving API
-│   ├── main.py                      # API entrypoint
-│   ├── providers/                   # Translation engine implementations
-│   ├── languages.py                 # FLORES-200 language map
-│   ├── convert_model.py             # NLLB/MADLAD conversion helper
-│   └── deploy_hf.py                 # Hugging Face Space deployment helper
-├── Dockerfile                       # Root Docker build (backend-focused)
-├── docker-compose.yml               # Local backend compose setup
-└── entrypoint.sh                    # Runtime model conversion + uvicorn start
-```
-
----
-
-## 3. Django application (`translator_app/`)
-
-### 3.1 Core URLs
-
-- `/` → translation UI (`translator.views.translator`)
-- `/api/translate/` → AJAX translation endpoint (`translator.views.translate_api`)
-- `/history/` → translation history list (`translator.views.history`)
-- `/history/<id>/delete/` → delete one entry
-- `/history/clear/` → clear all entries
-
-### 3.2 Models
-
-Defined in `translator/models.py`:
-
-- `Language`: curated/active language list used by UI when present.
-- `TranslationHistory`: persisted history with source text, translated text,
-  source/target language FK, selected model, and metadata.
-- `TranslationCache`: hash-based cache for repeated translations.
-
-Notable behavior:
-
-- `TranslationHistory.save()` auto-computes `character_count` and `word_count`.
-- History is ordered newest-first and indexed by `(user, -created_at)`.
-
-### 3.3 Views and orchestration
-
-`translator/views.py` coordinates UI + backend translation:
-
-- `_languages()`:
-  - uses DB `Language` rows where `is_active=True`;
-  - falls back to `TranslationService().get_supported_languages()`.
-- `translator()` renders model picker and language selectors.
-- `translate_api()`:
-  - validates JSON payload and limits text to 5000 chars;
-  - validates selected model against `TRANSLATION_MODELS`;
-  - calls `TranslationService.translate(...)`;
-  - persists `TranslationHistory`;
-  - returns translated text + model label.
+# 🌍 Translator Model API
 
-### 3.4 Service layer
+A lightweight, high-performance Translation API built with **FastAPI** and powered by **CTranslate2 (INT8)** for fast, memory-efficient CPU inference.
 
-`translator/services/translation_service.py`:
-
-- Detects source language with `langdetect` when source is not provided.
-- Converts app language codes (`en`, `sw`, etc.) to FLORES-200 (`eng_Latn`,
-  `swh_Latn`) for the backend API.
-- Uses cache (`TranslationCache`) keyed by text + source + target + model.
-- Supports:
-  - model API path (via `MODEL_API_URL`), and
-  - optional `deepl_fallback` path when `TRANSLATION_API_KEY` is configured.
-
-### 3.5 Templates/UI behavior
-
-Templates in `translator/templates/translator/`:
-
-- `base.html`: shell layout and Tailwind CDN styling.
-- `translator.html`: main translation page with JS submit flow.
-- `history.html`: persisted history view with delete/clear actions.
-
-Client-side behavior in `translator.html`:
-
-- POSTs JSON to `/api/translate/` with CSRF header.
-- Sends selected `model`, `source_language`, `target_language`, and text.
-- Disables source selector when model is `madlad` (MADLAD auto-detect source).
+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.
 
 ---
 
-## 4. Backend model API (`backend/`)
-
-### 4.1 API endpoints (`backend/main.py`)
-
-- `GET /api/health` → service status + default available engine.
-- `GET /api/engines` → all engines with metadata and availability.
-- `GET /api/languages` → language list (from FLORES-200 map).
-- `POST /api/translate` → translation endpoint.
-- `GET /scalar` → Scalar API documentation UI.
-
-`/api/translate` request shape:
-
-```json
-{
-  "text": "Hello world",
-  "source": "eng_Latn",
-  "target": "swh_Latn",
-  "engine": "nllb"
-}
-```
-
-Response shape:
-
-```json
-{
-  "translation": "Habari dunia",
-  "source": "eng_Latn",
-  "target": "swh_Latn",
-  "engine": "nllb"
-}
-```
-
-### 4.2 Provider architecture
-
-Providers implement `TranslationProvider` (`backend/providers/base.py`).
-
-Registry in `backend/providers/__init__.py` includes:
-
-- `nllb` (NLLB-200 600M)
-- `nllb_1_3b` (NLLB-200 1.3B)
-- `madlad` (MADLAD-400 3B)
-- `ollama` (local Ollama model)
-- `gemini` (Google API)
-- `groq_qwen` and `groq` (Groq API models)
+## 🚀 Supported Models
 
-Availability logic:
-
-- local engines → available when required local model/service exists.
-- API engines → available when server key exists (or key passed by request
-  headers for BYOK flow in FastAPI endpoint).
-
-### 4.3 Language system
-
-`backend/languages.py` provides a full FLORES-200 code map used by local/API
-providers. Django only exposes a curated subset in app-level UI defaults.
-
-### 4.4 Model conversion
-
-`backend/convert_model.py` converts Hugging Face checkpoints to CTranslate2
-int8 models (faster/lower-memory inference). Conversion target path defaults to:
-
-- `models/nllb-200-distilled-600M-int8`
-
-Environment overrides allow converting additional models (e.g. 1.3B, MADLAD).
+| 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.) |
 
 ---
 
-## 5. Configuration
-
-### 5.1 Django (`translator_app/.env`)
-
-Important settings loaded by `translator_project/settings.py`:
-
-- `MODEL_API_URL` (**required** for model API translation path)
-- `TRANSLATION_DEFAULT_MODEL` (default: `nllb`)
-- `TRANSLATION_API_KEY` (optional; enables `deepl_fallback`)
-- `TRANSLATION_API_URL` (optional; DeepL-compatible endpoint override)
-
-Model IDs configured in Django:
+## ⚡ Performance Highlights
 
-- `nllb`
-- `nllb_1_3b`
-- `madlad`
-- `deepl_fallback` (only when fallback key configured)
-
-### 5.2 Backend (`backend/.env`)
-
-See `backend/.env.example` for optional engine keys:
-
-- `GEMINI_API_KEY`
-- `GROQ_API_KEY`
-- `OLLAMA_HOST`, `OLLAMA_MODEL`
-- `CT2_DEVICE`, `CT2_COMPUTE_TYPE`
-- `MADLAD_MODEL_DIR`, related model paths
-- `CORS_ORIGINS`
+- **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.
 
 ---
 
-## 6. Local development
-
-### 6.1 Run Django app
+## 🛠️ API Usage
 
+### Health Check
 ```bash
-cd translator_app
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\Scripts\activate
-pip install -r ../requirements.txt
-python manage.py migrate
-python manage.py runserver
+GET /
 ```
 
-App URL: `http://127.0.0.1:8000/`
-
-### 6.2 Run backend API (direct)
-
+### Translate Text
 ```bash
-cd backend
-python -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-uvicorn main:app --host 0.0.0.0 --port 7860
-```
-
-API URL: `http://127.0.0.1:7860/api/health`
-
-### 6.3 Run backend API via Docker Compose
+POST /translate
+Content-Type: application/json
 
-From repo root:
-
-```bash
-docker compose up --build backend
+{
+  "model": "sunbird-nllb-3.3b",
+  "text": "Hello, how are you today?",
+  "src_lang": "eng_Latn",
+  "tgt_lang": "lug_Latn"
+}
 ```
 
-Compose maps port `7860` and mounts persistent model/cache volumes.
-
 ---
 
-## 7. Deployment (Hugging Face Space)
+## 🐳 Local Development (Docker)
 
-Backend is designed to deploy as a Docker Space (UI stays in Django app).
-
-Use helper:
+To build and test the container locally:
 
 ```bash
-HF_TOKEN=hf_your_write_token \
-SPACE_ID=your-hf-user/translator-model-api \
-python backend/deploy_hf.py
-```
-
-Detailed deployment notes are in `backend/HUGGINGFACE_DEPLOYMENT.md`.
-
-After deployment, set Django:
-
-```env
-MODEL_API_URL=https://<your-space>.hf.space/api/translate
-```
-
----
-
-## 8. Data and persistence
-
-- Django DB: `translator_app/db.sqlite3`
-- Translation history and cache live in Django DB.
-- Backend model artifacts are stored under configured model directories
-  (often mounted as Docker volumes in local/containerized runs).
-
----
-
-## 9. Current test coverage
-
-`translator/tests.py` currently covers:
-
-- translation page renders model selector
-- translation API saves history record
-- translation API rejects missing text
-
----
-
-## 10. Key integration contract (Django ↔ backend)
-
-For end-to-end translation to work:
+# Build Docker image
+docker build -t translator-api .
 
-1. Django `TRANSLATION_MODEL_ENGINES` model IDs must map to backend provider IDs.
-2. Django must map UI language codes to FLORES-200 before calling backend.
-3. `MODEL_API_URL` must point at backend `/api/translate`.
-4. Selected model is persisted in `TranslationHistory.translation_model` and shown in history.
+# Run Docker container mapping port 7860
+docker run -p 7860:7860 -v $(pwd)/data:/data translator-api
+```