README.md

---
title: PERI BERT Classifier
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: app.py
pinned: false
license: apache-2.0
---

# PERI BERT Classifier

API REST para clasificación de arquetipos éticos en reflexiones sobre IA usando BERT fine-tuneado.

## 📋 Descripción

Este espacio proporciona una API FastAPI para clasificar reflexiones éticas sobre IA en 5 arquetipos PERI:

1. **Tecnócrata Optimizador** - Confía en la eficiencia de sistemas automatizados
2. **Humanista Crítico** - Prioriza el bienestar humano y cuestiona sesgos
3. **Pragmático Equilibrado** - Busca balance entre innovación y humanidad
4. **Visionario Adaptativo** - Abraza la transformación tecnológica
5. **Escéptico Conservador** - Postura cautelosa hacia la IA

## 🚀 Características

- **MC Dropout**: Uncertainty quantification para cada predicción
- **Batch Processing**: Clasificación de múltiples textos simultáneamente
- **FastAPI Docs**: Documentación interactiva automática
- **CORS Enabled**: Listo para integración desde cualquier frontend
- **Métricas detalladas**: Confidence, uncertainty, top-3 predictions

## 🔧 Endpoints

### `GET /`
Documentación interactiva Swagger UI

### `GET /health`
Health check del servicio
```json
{
  "status": "healthy",
  "model_loaded": true,
  "device": "cuda",
  "timestamp": 1234567890.123
}
```

### `GET /info`
Información del modelo
```json
{
  "model_name": "bert-base-multilingual-cased (fine-tuned)",
  "num_classes": 5,
  "max_length": 512,
  "device": "cuda",
  "mc_dropout_samples": 10,
  "archetypes": [...]
}
```

### `POST /predict`
Clasificar una reflexión individual

**Request:**
```json
{
  "text": "La automatización mediante IA representa...",
  "use_mc_dropout": true
}
```

**Response:**
```json
{
  "archetype": {
    "id": "TECNOCRATA_OPTIMIZADOR",
    "name": "Tecnócrata Optimizador",
    "description": "Confía en la eficiencia y objetividad..."
  },
  "confidence": 0.87,
  "uncertainty": 0.23,
  "top3_predictions": [
    {
      "archetype_id": "TECNOCRATA_OPTIMIZADOR",
      "archetype_name": "Tecnócrata Optimizador",
      "probability": 0.87
    },
    {
      "archetype_id": "PRAGMATICO_EQUILIBRADO",
      "archetype_name": "Pragmático Equilibrado",
      "probability": 0.08
    },
    {
      "archetype_id": "VISIONARIO_ADAPTATIVO",
      "archetype_name": "Visionario Adaptativo",
      "probability": 0.03
    }
  ],
  "inference_time_ms": 245.6,
  "method": "bert-mc-dropout"
}
```

### `POST /predict-batch`
Clasificar múltiples reflexiones (máx 50)

**Request:**
```json
{
  "texts": ["Reflexión 1...", "Reflexión 2...", "..."],
  "use_mc_dropout": true
}
```

**Response:**
```json
{
  "predictions": [...],
  "total_inference_time_ms": 1234.5
}
```

## 🛠️ Uso desde JavaScript/TypeScript

```typescript
// Clasificar una reflexión
async function classifyReflection(text: string) {
  const response = await fetch('https://your-space.hf.space/predict', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      text: text,
      use_mc_dropout: true
    })
  });

  const result = await response.json();
  console.log('Arquetipo:', result.archetype.name);
  console.log('Confianza:', result.confidence);
  console.log('Incertidumbre:', result.uncertainty);
  return result;
}
```

## 📦 Deployment en HuggingFace Space

### Paso 1: Crear Space

1. Ir a https://huggingface.co/spaces
2. Click "Create new Space"
3. Configurar:
   - **Name**: `peri-bert-classifier`
   - **License**: MIT
   - **Space SDK**: Docker
   - **Hardware**: CPU basic (o T4 small para GPU)

### Paso 2: Subir archivos

Estructura del repositorio:
```
peri-bert-classifier/
├── app.py                    # API FastAPI
├── requirements.txt          # Dependencias Python
├── Dockerfile               # Configuración Docker
├── README.md                # Esta documentación
└── model/                   # Modelo BERT fine-tuneado
    ├── config.json
    ├── pytorch_model.bin
    ├── tokenizer_config.json
    └── vocab.txt
```

### Paso 3: Dockerfile

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Copiar archivos
COPY requirements.txt .
COPY app.py .
COPY model/ ./model/

# Instalar dependencias
RUN pip install --no-cache-dir -r requirements.txt

# Exponer puerto
EXPOSE 7860

# Comando de inicio
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
```

### Paso 4: Git push

```bash
# Clonar el space
git clone https://huggingface.co/spaces/YOUR_USERNAME/peri-bert-classifier
cd peri-bert-classifier

# Copiar archivos
cp app.py requirements.txt Dockerfile README.md .
cp -r ../../../models/peri-bert/best_model ./model

# Push
git add .
git commit -m "Initial deployment"
git push
```

## 🧪 Testing Local

```bash
# Instalar dependencias
pip install -r requirements.txt

# Ejecutar servidor
python app.py

# Acceder a:
# - Docs: http://localhost:7860
# - Health: http://localhost:7860/health
```

## 📊 Performance

- **Latencia (sin GPU)**: ~200-300ms por reflexión
- **Latencia (con GPU T4)**: ~50-100ms por reflexión
- **Throughput batch**: ~10 reflexiones/segundo (GPU)
- **Memoria**: ~2GB RAM + ~1GB VRAM (GPU)

## 🔒 Seguridad

- Input validation con Pydantic
- CORS configurado (ajustar origins en producción)
- Rate limiting recomendado para producción
- Longitud máxima de texto: 5000 caracteres

## 📈 Métricas del Modelo

- **Test Accuracy**: ~84%
- **MC Dropout Accuracy**: ~86%
- **Mean Uncertainty**: 0.32
- **F1-Score (macro avg)**: 0.84

## 📞 Soporte

Para issues o preguntas sobre el modelo:
- GitHub: [PERI Project](https://github.com/...)
- Paper: [Ver documentación científica]

---

**Generado con ❤️ para el proyecto PERI**
**Deep Learning Conference 2025**