README.md

---
title: MSL Internal API
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
license: other
---

# bert-api/

Backend Python Flask que sirve el clasificador BERT propio de MuseSceneLab para los comandos NLP de MEHEARSAL.

**Origen:** copiado de `D:\XDev.Projects\MEHEARSAL-NLP-CONTROLLER-RMIT\mehearsal_v5_and_v6\bert-api\` con 3 modificaciones mínimas para HF Spaces Docker (ver §"Adaptaciones" más abajo).

**Despliegue actual:** HuggingFace Space `MuseSceneLab/msl-internal-api` (Docker SDK). Ver doc 33 §8 Fase R4-R7.

> **Nota sobre el frontmatter YAML del principio:** lo leen los Spaces de HuggingFace para configurar el deploy (título, SDK, puerto). `app_port: 7860` es crítico — sin él HF no sabe qué puerto exponer y el Space queda en "config error". En cualquier otro contexto (lectura local, repo de GitHub) el frontmatter se ignora o se renderiza como bloque inicial.

**Despliegue futuro:** AWS App Runner cuando se cumplan los disparadores de doc 33 §13.4.

---

## Estructura

```
bert-api/
├── bert_api.py           Flask app. Carga modelo en arranque, expone /classify y /health
├── requirements.txt      flask, flask-cors, transformers, torch, huggingface_hub, python-dotenv
├── Dockerfile            Imagen para HF Spaces. Python 3.11-slim, expone 7860
├── .dockerignore         Excluye venv, __pycache__, README, etc. de la imagen
└── README.md             Este archivo
```

---

## Endpoints

| Método | Path | Body | Devuelve |
|---|---|---|---|
| `POST` | `/classify` | `{ "utterance": "mute the guitar" }` | `{ intent_label, locale, target, params_json, confidence, model }` |
| `GET` | `/health` | — | `{ status, model }` |

---

## Variables de entorno

| Var | Default | Para qué |
|---|---|---|
| `HF_TOKEN` | _(obligatorio)_ | Auth para descargar el modelo privado de HF. En HF Spaces se configura como Secret del Space |
| `BERT_MODEL_NAME` | `MuseSceneLab/mehearsal-nlp-v6` | Cambiar para usar v5 u otro modelo |
| `PORT` | `7860` | Puerto del servidor Flask. HF Spaces inyecta `7860` automáticamente |

---

## Desarrollo local

```bash
cd bert-api
python -m venv venv
.\venv\Scripts\activate            # Windows PowerShell: .\venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:HF_TOKEN = "hf_..."           # tu token con permiso de lectura sobre el modelo
python bert_api.py
```

Levanta en `http://localhost:7860`. Probar con:

```bash
curl -X POST http://localhost:7860/classify -H "Content-Type: application/json" -d '{"utterance":"mute the guitar"}'
```

**Nota:** la primera ejecución descarga el modelo (~500 MB) desde HF a la caché local (`~/.cache/huggingface/`). Ejecuciones posteriores son instantáneas.

---

## Despliegue como Space (proceso R4-R7 de doc 33)

1. Crear Space en `huggingface.co/new-space`:
   - Owner: `MuseSceneLab`
   - Name: `mehearsal-bert-api`
   - SDK: **Docker**
   - Hardware: CPU Basic (free)
   - Visibility: Public _(el contenedor; los pesos del modelo siguen privados)_

2. En el Space, ir a Settings → Repository secrets → añadir `HF_TOKEN`.

3. Clonar el repo del Space y empujar el contenido de esta carpeta:

   ```bash
   git clone https://huggingface.co/spaces/MuseSceneLab/mehearsal-bert-api
   cd mehearsal-bert-api
   cp -r ../MEHEARSAL2025/bert-api/* .
   git add .
   git commit -m "Initial BERT API for MEHEARSAL"
   git push
   ```

4. HF construye la imagen (~3-5 min). Verificar logs en la UI del Space.

5. URL pública: `https://musescenelab-mehearsal-bert-api.hf.space/classify`.

---

## Adaptaciones respecto al código fuente

Tres diffs vs `mehearsal_v5_and_v6/bert-api/bert_api.py`:

1. **Import `os`** al principio del archivo.
2. **`MODEL_NAME` configurable** vía env var (default `v6`). El fuente lo tenía hardcoded a `v5`.
3. **Puerto y debug** en `app.run()`: puerto leído de env var `PORT` (default 7860, requisito de Spaces), `debug=False` para producción.

La lógica de `extract_entities()`, `INTENT_METADATA` y el upgrade de intents en `/classify` está **intacta**. Esto evita cualquier divergencia funcional respecto al desarrollo original.

---

## Roadmap

- **Ahora:** HF Spaces Docker (este folder = código fuente, sin cambios entre dev local y prod Space)
- **Futuro:** migración a AWS App Runner. Ver doc 33 §13. El Dockerfile actual sirve igual sin cambios.