Rewrite all docs in English

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ARCHITECTURE.md

@@ -1,79 +1,79 @@
-# Arquitectura
+# Architecture
 
-## Despliegue
+## Deployment
 
 ```
-GitHub (código fuente)
+GitHub (source code)
     │
-    └─► Hugging Face Spaces (runtime Docker)
-            │  construye y ejecuta el contenedor FastAPI
+    └─► Hugging Face Spaces (Docker runtime)
+            │  builds and runs the FastAPI container
             │
-            ├─► al iniciar: descarga el modelo desde HF Hub
+            ├─► on startup: downloads model from HF Hub
             │       huggingface.co/cmeneses99/sms-classifier
             │       (model.safetensors, tokenizer, config — ~520MB)
             │
-            └─► expone la API en el puerto 7860
+            └─► serves API on port 7860
                     https://cmeneses99-sms-classifier-api.hf.space
 
-cron-job.org ──GET /health cada 10min──► HF Spaces (keep-alive)
+cron-job.org ──GET /health every 10min──► HF Spaces (keep-alive)
 ```
 
-## Flujo de una solicitud
+## Request flow
 
 ```
-Cliente
+Client
   │
   ▼
-FastAPI (routers/)
+FastAPI
   │
-  ├── pages.py      → respuestas HTML (/, /classify, /classify/batch, /categories)
-  ├── inference.py  → POST /classify, POST /classify/batch
-  └── meta.py       → GET /health, GET /api/categories
+  ├── web/pages.py      → HTML responses (/, /classify, /classify/batch, /categories)
+  ├── api/inference.py  → POST /classify, POST /classify/batch
+  └── api/meta.py       → GET /health, GET /api/categories
         │
         ▼
 services/classifier.py
   │
-  ├── Cache LRU (cache.py) ──hit──► retorna respuesta en caché
+  ├── LRU Cache (core/cache.py) ──hit──► return cached response
   │
-  └── miss ──► model_loader.py (pipeline de HuggingFace)
+  └── miss ──► core/model_loader.py (HuggingFace pipeline)
                     └── distilbert-base-multilingual-cased (fine-tuned)
-                            └── top_k=3 predicciones → PredictResponse
+                            └── top_k=3 predictions → PredictResponse
 ```
 
-## Modelo
+## Model
 
-| Detalle | Valor |
-|---|---|
-| Modelo base | `distilbert-base-multilingual-cased` |
-| Tarea | Clasificación de secuencias |
-| Categorías | 9 |
-| Datos de entrenamiento | 3.150 ejemplos sintéticos (350/categoría, ES + EN) |
-| Entrenamiento | 5 épocas, fine-tuning con HuggingFace Trainer API |
-| Runtime | Solo CPU (build CPU de PyTorch) |
-| Cache | LRU, máx. 512 entradas, thread-safe |
+| Detail           | Value                                                  |
+|------------------|--------------------------------------------------------|
+| Base model       | `distilbert-base-multilingual-cased`                   |
+| Task             | Sequence classification                                |
+| Categories       | 9                                                      |
+| Training data    | 3,150 synthetic examples (350/category, ES + EN)       |
+| Training         | 5 epochs, fine-tuned with HuggingFace Trainer API      |
+| Runtime          | CPU-only (PyTorch CPU build)                           |
+| Cache            | LRU, max 512 entries, thread-safe                      |
 
-## Estructura del proyecto
+## Project structure
 
 ```
 app/
-├── main.py                      # Lifespan + registro de routers
+├── main.py                      # Lifespan + router registration
 ├── utils.py                     # normalize(), read_static()
-├── core/                        # Infraestructura compartida
-│   ├── cache.py                 # Cache LRU thread-safe
-│   ├── model_loader.py          # Descarga el modelo desde HF Hub al iniciar
-│   ├── schemas.py               # Modelos Pydantic v2 para request/response
-│   └── category_meta.py         # Labels, colores y ejemplos por categoría
+├── core/                        # Shared infrastructure
+│   ├── cache.py                 # Thread-safe LRU cache
+│   ├── model_loader.py          # Downloads model from HF Hub on startup
+│   ├── schemas.py               # Pydantic v2 request/response models
+│   └── category_meta.py         # Labels, colors and examples per category
 ├── services/
-│   └── classifier.py            # Lógica de inferencia con integración de caché
-├── api/                         # Endpoints JSON
+│   └── classifier.py            # Inference logic with cache integration
+├── api/                         # JSON endpoints
 │   ├── inference.py             # POST /classify, POST /classify/batch
 │   └── meta.py                  # GET /health, GET /api/categories
-├── web/                         # Endpoints HTML
-│   └── pages.py                 # Rutas de UI
-└── templates/                   # Archivos HTML
+├── web/                         # HTML endpoints
+│   └── pages.py                 # UI routes
+└── templates/                   # HTML files
     ├── home.html
-    ├── index.html                # UI clasificador simple
-    ├── batch.html                # UI clasificador por lotes
+    ├── index.html                # Single classifier UI
+    ├── batch.html                # Batch classifier UI
     └── categories.html
 training/
 ├── config.py

README.md

@@ -1,4 +1,4 @@
----
+---
 title: SMS Classifier API
 emoji: 📱
 colorFrom: blue
@@ -10,135 +10,135 @@ pinned: false
 
 # SMS Classifier API
 
-API REST para clasificar mensajes SMS en categorías usando **DistilBERT multilingual** con fine-tuning sobre un dataset sintético multilingüe (ES + EN).
+REST API that classifies SMS messages into operational categories using **multilingual DistilBERT** fine-tuned on a synthetic bilingual dataset (ES + EN).
 
 **Live demo:** https://cmeneses99-sms-classifier-api.hf.space
 
-## Categorías
+## Categories
 
-| Categoría              | Descripción                                       |
-| ---------------------- | ------------------------------------------------- |
-| `transaction`          | Confirmaciones de pagos, débitos y transferencias |
-| `otp_verification`     | Códigos de un solo uso para verificar identidad   |
-| `promotion_offer`      | Descuentos, cupones y ofertas de comercios        |
-| `security_alert`       | Accesos no reconocidos y actividad sospechosa     |
-| `delivery_logistics`   | Estado de envíos y seguimiento de pedidos         |
-| `appointment_reminder` | Recordatorios de citas médicas y dentales         |
-| `customer_service`     | Tickets, reclamos y soporte                       |
-| `spam_advertising`     | Mensajes fraudulentos y publicidad engañosa       |
-| `billing_reminder`     | Facturas pendientes y fechas de vencimiento       |
+| Category               | Description                                          |
+| ---------------------- | ---------------------------------------------------- |
+| `transaction`          | Payment confirmations, debits and transfers          |
+| `otp_verification`     | One-time codes for identity verification             |
+| `promotion_offer`      | Discounts, coupons and merchant offers               |
+| `security_alert`       | Unrecognized access and suspicious activity          |
+| `delivery_logistics`   | Shipment status and order tracking                   |
+| `appointment_reminder` | Medical and dental appointment reminders             |
+| `customer_service`     | Tickets, claims and support updates                  |
+| `spam_advertising`     | Fraudulent messages and misleading advertising       |
+| `billing_reminder`     | Pending invoices and payment due dates               |
 
-## Stack tecnológico
+## Tech stack
 
 - **Python 3.11** + **FastAPI** + **Uvicorn**
-- **DistilBERT** (`distilbert-base-multilingual-cased`) vía HuggingFace Transformers
-- **PyTorch** (CPU-only en producción)
-- **Pydantic v2** para validación
-- **Docker** para contenedorización
-- **Hugging Face Spaces** para deployment
-- **Hugging Face Hub** para hosting del modelo
+- **DistilBERT** (`distilbert-base-multilingual-cased`) via HuggingFace Transformers
+- **PyTorch** (CPU-only in production)
+- **Pydantic v2** for validation
+- **Docker** for containerization
+- **Hugging Face Spaces** for deployment
+- **Hugging Face Hub** for model hosting
 
-## Estructura del proyecto
+## Project structure
 
 ```
 app/
-├── main.py                      # App entry point
-├── utils.py                     # normalize(), read_static()
-├── core/                        # Infraestructura compartida
-│   ├── cache.py                 # LRU cache thread-safe
-│   ├── model_loader.py          # Carga del modelo al startup
-│   ├── schemas.py               # Modelos Pydantic
-│   └── category_meta.py         # Metadata de categorías
-├── services/
-│   └── classifier.py            # Lógica de inferencia + caché LRU
-├── api/                         # Endpoints JSON
-│   ├── inference.py             # POST /classify, POST /classify/batch
-│   └── meta.py                  # GET /health, GET /api/categories
-├── web/                         # Endpoints HTML
-│   └── pages.py                 # Rutas de UI
-└── templates/                   # Archivos HTML
-    ├── home.html
-    ├── index.html
-    ├── batch.html
-    └── categories.html
+├── main.py                      # App entry point
+├── utils.py                     # normalize(), read_static()
+├── core/                        # Shared infrastructure
+│   ├── cache.py                 # Thread-safe LRU cache
+│   ├── model_loader.py          # Downloads and loads the model at startup
+│   ├── schemas.py               # Pydantic models
+│   └── category_meta.py         # Category metadata
+├── services/
+│   └── classifier.py            # Inference logic + LRU cache integration
+├── api/                         # JSON endpoints
+│   ├── inference.py             # POST /classify, POST /classify/batch
+│   └── meta.py                  # GET /health, GET /api/categories
+├── web/                         # HTML endpoints
+│   └── pages.py                 # UI routes
+└── templates/                   # HTML files
+    ├── home.html
+    ├── index.html
+    ├── batch.html
+    └── categories.html
 training/
-├── config.py                    # Hiperparámetros
-├── generate_dataset.py          # Genera training/data/sms_dataset.csv
-├── train.py                     # Fine-tuning script
-└── eval_report.py               # Reporte de métricas por categoría
+├── config.py                    # Hyperparameters
+├── generate_dataset.py          # Generates training/data/sms_dataset.csv
+├── train.py                     # Fine-tuning script
+└── eval_report.py               # Per-category metrics report
 ```
 
-## Correr localmente
+## Run locally
 
-### Requisitos
+### Requirements
 
 - Python 3.11+
-- Modelo entrenado en `./model/` (ver sección de entrenamiento)
+- Trained model in `./model/` (see training section)
 
 ```bash
-# Crear entorno virtual
+# Create virtual environment
 python -m venv .venv
 .venv\Scripts\activate        # Windows
 source .venv/bin/activate     # Linux/Mac
 
-# Instalar dependencias
+# Install dependencies
 pip install -r requirements.txt
 pip install torch --index-url https://download.pytorch.org/whl/cpu
 
-# Levantar API
+# Start API
 uvicorn app.main:app --reload
 ```
 
-API disponible en `http://localhost:8000`
+API available at `http://localhost:8000`
 
-### Con Docker
+### With Docker
 
 ```bash
 docker compose up --build
 ```
 
-## Entrenar el modelo
+## Train the model
 
 ```bash
 pip install -r requirements-training.txt
 
 cd training
-python generate_dataset.py   # genera training/data/sms_dataset.csv
-python train.py              # fine-tuning → guarda modelo en ./model/
-python eval_report.py        # reporte de métricas por categoría
+python generate_dataset.py   # generates training/data/sms_dataset.csv
+python train.py              # fine-tuning → saves model to ./model/
+python eval_report.py        # per-category metrics report
 ```
 
 ## Endpoints
 
-| Método | Ruta              | Descripción                          |
-| ------ | ----------------- | ------------------------------------ |
-| `GET`  | `/`               | Home con descripción de la API       |
-| `GET`  | `/classify`       | Clasificador interactivo (UI)        |
-| `GET`  | `/classify/batch` | Clasificador por lotes (UI)          |
-| `GET`  | `/categories`     | Vista de categorías con ejemplos     |
-| `POST` | `/classify`       | Clasificar un texto (JSON)           |
-| `POST` | `/classify/batch` | Clasificar múltiples textos (JSON)   |
-| `GET`  | `/api/categories` | Lista de categorías (JSON)           |
-| `GET`  | `/health`         | Estado del servicio y stats de caché |
+| Method | Route             | Description                        |
+| ------ | ----------------- | ---------------------------------- |
+| `GET`  | `/`               | Home with API description          |
+| `GET`  | `/classify`       | Interactive single classifier (UI) |
+| `GET`  | `/classify/batch` | Batch classifier (UI)              |
+| `GET`  | `/categories`     | Categories view with examples      |
+| `POST` | `/classify`       | Classify one message (JSON)        |
+| `POST` | `/classify/batch` | Classify multiple messages (JSON)  |
+| `GET`  | `/api/categories` | List categories (JSON)             |
+| `GET`  | `/health`         | Service status and cache stats     |
 
 ### POST /classify
 
 ```bash
 curl -X POST http://localhost:8000/classify \
   -H "Content-Type: application/json" \
-  -d '{"text": "Tu código OTP es 482910. No lo compartas."}'
+  -d '{"text": "Your OTP code is 482910. Do not share it."}'
 ```
 
 ```json
 {
-  "text": "Tu código OTP es 482910. No lo compartas.",
+  "text": "Your OTP code is 482910. Do not share it.",
   "prediction": {
     "category": "otp_verification",
     "confidence": 0.9821
   },
   "top_3": [
     { "category": "otp_verification", "confidence": 0.9821 },
-    { "category": "security_alert", "confidence": 0.0091 },
+    { "category": "security_alert",   "confidence": 0.0091 },
     { "category": "customer_service", "confidence": 0.0044 }
   ],
   "cached": false
@@ -150,7 +150,7 @@ curl -X POST http://localhost:8000/classify \
 ```bash
 curl -X POST http://localhost:8000/classify/batch \
   -H "Content-Type: application/json" \
-  -d '{"texts": ["Tu código OTP es 482910.", "Se debitó $45.000 en Falabella."]}'
+  -d '{"texts": ["Your OTP code is 482910.", "Your card was charged $45 at Amazon."]}'
 ```
 
 ```json
@@ -161,15 +161,16 @@ curl -X POST http://localhost:8000/classify/batch \
 }
 ```
 
-## Despliegue en Hugging Face Spaces
+## Deploy on Hugging Face Spaces
 
-1. Crea un Space en [huggingface.co/new-space](https://huggingface.co/new-space) con SDK: **Docker**
-2. Sube el código al repo del Space:
+1. Create a Space at [huggingface.co/new-space](https://huggingface.co/new-space) with SDK: **Docker**
+2. Push the code to the Space repo:
    ```bash
    git remote add hfspace https://USER:TOKEN@huggingface.co/spaces/USER/SPACE-NAME
    git push hfspace main
    ```
-3. HF Spaces detecta el `Dockerfile` automáticamente y hace el build
-4. Al iniciar, el modelo se descarga desde HF Hub (~520MB, solo la primera vez)
+3. HF Spaces detects the `Dockerfile` automatically and builds the image
+4. On startup, the model is downloaded from HF Hub (~520MB, first time only)
+
+Model hosted at [huggingface.co/cmeneses99/sms-classifier](https://huggingface.co/cmeneses99/sms-classifier).
 
-El modelo está en [huggingface.co/cmeneses99/sms-classifier](https://huggingface.co/cmeneses99/sms-classifier).

USAGE.md

@@ -1,54 +1,54 @@
-# Guía de uso
+# Usage Guide
 
-URL base: `https://cmeneses99-sms-classifier-api.hf.space`
+Base URL: `https://cmeneses99-sms-classifier-api.hf.space`
 
 ---
 
-## Desde el navegador (UI)
+## Via Browser (UI)
 
 ### Home
-Abre `https://cmeneses99-sms-classifier-api.hf.space` — vas a ver una descripción de la API con todos los endpoints disponibles y ejemplos de respuesta. Desde ahí puedes navegar al resto de las vistas con los botones.
+Open `https://cmeneses99-sms-classifier-api.hf.space` to see a description of the API with all available endpoints and response examples. From there you can navigate to any view using the buttons.
 
 ---
 
-### Clasificar un mensaje
-1. Haz click en **"Clasificador Simple"** desde el home (o navega directo a `/classify`)
-2. Escribe el mensaje en el campo de texto
-3. Haz click en **"Clasificar"** o presiona **Enter**
-4. El resultado muestra la categoría detectada, el nivel de confianza y el top 3 de categorías más probables
-5. Si el mismo texto ya fue consultado antes, aparece el badge **"caché activo"**
+### Classify a single message
+1. Click **"Clasificador Simple"** from the home (or navigate directly to `/classify`)
+2. Type the message in the text field
+3. Click **"Clasificar"** or press **Enter**
+4. The result shows the detected category, confidence score and the top 3 most likely categories
+5. If the same text was already classified before, a **"caché activo"** badge appears
 
 ---
 
-### Clasificar múltiples mensajes
-1. Haz click en **"Clasificador por Lotes"** desde el home (o navega directo a `/classify/batch`)
-2. Escribe un mensaje por línea en el área de texto
-3. El contador en tiempo real te muestra cuántos mensajes cargaste (máx. 50)
-4. Haz click en **"Clasificar todo"**
-5. Los resultados aparecen uno por uno con su categoría y confianza
-6. En la barra de resumen inferior puedes ver cuántos vinieron desde caché
+### Classify multiple messages
+1. Click **"Clasificador por Lotes"** from the home (or navigate directly to `/classify/batch`)
+2. Type one message per line in the text area
+3. A real-time counter shows how many messages you have loaded (max 50)
+4. Click **"Clasificar todo"**
+5. Results appear one by one with their category and confidence
+6. The summary bar at the bottom shows how many results came from cache
 
 ---
 
-### Ver categorías disponibles
-1. Haz click en **"Categorías"** desde el home (o navega directo a `/categories`)
-2. Cada categoría muestra su descripción y un ejemplo en español e inglés
+### Browse available categories
+1. Click **"Categorías"** from the home (or navigate directly to `/categories`)
+2. Each category shows its description and an example in Spanish and English
 
 ---
 
-## Desde la API (curl)
+## Via API (curl)
 
-### Clasificar un mensaje
+### Classify one message
 
 ```bash
 curl -X POST https://cmeneses99-sms-classifier-api.hf.space/classify \
   -H "Content-Type: application/json" \
-  -d '{"text": "Tu código OTP es 482910. No lo compartas."}'
+  -d '{"text": "Your OTP code is 482910. Do not share it."}'
 ```
 
 ```json
 {
-  "text": "Tu código OTP es 482910. No lo compartas.",
+  "text": "Your OTP code is 482910. Do not share it.",
   "prediction": { "category": "otp_verification", "confidence": 0.9821 },
   "top_3": [
     { "category": "otp_verification", "confidence": 0.9821 },
@@ -59,18 +59,18 @@ curl -X POST https://cmeneses99-sms-classifier-api.hf.space/classify \
 }
 ```
 
-**Límite:** máx. 512 caracteres por mensaje.
+**Limit:** max 512 characters per message.
 
 ---
 
-### Clasificar múltiples mensajes
+### Classify multiple messages
 
 ```bash
 curl -X POST https://cmeneses99-sms-classifier-api.hf.space/classify/batch \
   -H "Content-Type: application/json" \
   -d '{
     "texts": [
-      "Se debitó $45.000 en Falabella.",
+      "Your card was charged $45 at Amazon.",
       "Your package will arrive tomorrow between 2-4pm.",
       "Pay your bill today and avoid penalties."
     ]
@@ -80,7 +80,7 @@ curl -X POST https://cmeneses99-sms-classifier-api.hf.space/classify/batch \
 ```json
 {
   "results": [
-    { "text": "Se debitó $45.000 en Falabella.", "prediction": { "category": "transaction", "confidence": 0.97 }, "top_3": [...], "cached": false },
+    { "text": "Your card was charged $45 at Amazon.", "prediction": { "category": "transaction", "confidence": 0.97 }, "top_3": [...], "cached": false },
     { "text": "Your package will arrive tomorrow...", "prediction": { "category": "delivery_logistics", "confidence": 0.95 }, "top_3": [...], "cached": false },
     { "text": "Pay your bill today...", "prediction": { "category": "billing_reminder", "confidence": 0.91 }, "top_3": [...], "cached": false }
   ],
@@ -89,11 +89,11 @@ curl -X POST https://cmeneses99-sms-classifier-api.hf.space/classify/batch \
 }
 ```
 
-**Límite:** máx. 50 mensajes por request.
+**Limit:** max 50 messages per request.
 
 ---
 
-### Listar categorías
+### List categories
 
 ```bash
 curl https://cmeneses99-sms-classifier-api.hf.space/api/categories
@@ -123,16 +123,16 @@ curl https://cmeneses99-sms-classifier-api.hf.space/health
 
 ---
 
-## Categorías
-
-| Categoría | Ejemplos |
-|---|---|
-| `transaction` | "Se debitó $45.000 en Falabella" / "Payment of $120 confirmed" |
-| `otp_verification` | "Tu código OTP es 482910" / "Your verification code is 774321" |
-| `promotion_offer` | "30% de descuento este fin de semana" / "Exclusive offer just for you" |
-| `security_alert` | "Acceso no reconocido desde Berlín" / "Failed login attempt detected" |
-| `delivery_logistics` | "Tu pedido está en camino" / "Your package will arrive tomorrow" |
-| `appointment_reminder` | "Recordatorio: cita médica mañana a las 10am" / "Dental appointment confirmed" |
-| `customer_service` | "Tu ticket #4821 fue resuelto" / "Your case has been escalated" |
-| `spam_advertising` | "Ganaste un premio, haz clic aquí" / "You have been selected for a reward" |
-| `billing_reminder` | "Tu factura vence el 15 de mayo" / "Pay your bill today and avoid penalties" |
+## Categories
+
+| Category               | Examples                                                                          |
+|------------------------|-----------------------------------------------------------------------------------|
+| `transaction`          | "Your card was charged $45 at Amazon" / "Se debitó $45.000 en Falabella"         |
+| `otp_verification`     | "Your OTP code is 482910" / "Tu código OTP es 482910"                            |
+| `promotion_offer`      | "Exclusive offer just for you" / "30% de descuento este fin de semana"           |
+| `security_alert`       | "Failed login attempt detected" / "Acceso no reconocido desde Berlín"            |
+| `delivery_logistics`   | "Your package will arrive tomorrow" / "Tu pedido está en camino"                 |
+| `appointment_reminder` | "Dental appointment confirmed" / "Recordatorio: cita médica mañana a las 10am"  |
+| `customer_service`     | "Your case has been escalated" / "Tu ticket #4821 fue resuelto"                  |
+| `spam_advertising`     | "You have been selected for a reward" / "Ganaste un premio, haz clic aquí"       |
+| `billing_reminder`     | "Pay your bill today and avoid penalties" / "Tu factura vence el 15 de mayo"     |