QUICKSTART.md

# 🚀 Guía de Inicio Rápido - Aliah-Plus

## Instalación en 3 Pasos

### 1. Clonar el Repositorio

```bash
git clone https://github.com/tu-usuario/aliah-plus.git
cd aliah-plus
```

### 2. Instalar Dependencias

**Opción A: Con virtualenv**
```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium
```

**Opción B: Con Docker**
```bash
docker build -t aliah-plus .
docker run -p 8000:8000 aliah-plus
```

### 3. Ejecutar

```bash
python app.py
```

El servidor estará disponible en: http://localhost:8000

Documentación interactiva: http://localhost:8000/docs

---

## Uso Básico con cURL

### Búsqueda Completa

```bash
curl -X POST "http://localhost:8000/api/v1/search?threshold=0.75&enable_ocr=true&enable_cross_ref=true" \
  -F "file=@persona.jpg"
```

### Solo Extracción OCR

```bash
curl -X POST "http://localhost:8000/api/v1/ocr-extract" \
  -F "file=@miniatura.jpg"
```

### Comparar Dos Rostros

```bash
curl -X POST "http://localhost:8000/api/v1/compare" \
  -F "file1=@persona1.jpg" \
  -F "file2=@persona2.jpg"
```

---

## Uso con Python

```python
import requests

# Búsqueda
with open('persona.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/api/v1/search',
        files={'file': f},
        params={
            'threshold': 0.75,
            'enable_ocr': True,
            'enable_cross_ref': True
        }
    )

results = response.json()
print(f"Encontrados: {results['total_verified']} resultados verificados")

for match in results['matches'][:5]:
    print(f"• {match['domain']} - Similitud: {match['similarity']:.2%}")
```

---

## Despliegue en Hugging Face Spaces

1. Crear nuevo Space: https://huggingface.co/spaces
2. Seleccionar "Docker" como SDK
3. Subir todos los archivos del proyecto
4. El Dockerfile se ejecutará automáticamente
5. Tu Space estará en: `https://huggingface.co/spaces/tu-usuario/aliah-plus`

---

## Verificar Instalación

```bash
# Health check
curl http://localhost:8000/health

# Debería retornar:
{
  "status": "healthy",
  "version": "1.0.0",
  "components": {
    "face_processor": "ok",
    "embedding_engine": "ok",
    "stealth_search": "ok",
    "ocr_extractor": "ok",
    "cross_referencer": "ok",
    "vector_db": "ok"
  }
}
```

---

## Ejemplos Incluidos

```bash
# Ejecutar ejemplos interactivos
python examples/usage_example.py
```

---

## Troubleshooting

### Error: "No se detectó rostro"
- Asegúrate de que la imagen tenga un rostro visible y bien iluminado
- La imagen debe tener al menos 100x100 píxeles
- El rostro debe estar frontal (no de perfil)

### Error: "Playwright not installed"
```bash
playwright install chromium
playwright install-deps
```

### Error: "CUDA not available"
- El sistema funcionará con CPU, pero será más lento
- Para usar GPU, instala: `pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu118`

### Error en Hugging Face Spaces
- Verifica que el Dockerfile esté correctamente configurado
- El puerto debe ser 7860 (no 8000)
- Revisa los logs en la pestaña "Logs" del Space

---

## Configuración Avanzada

Edita `config.yaml` para ajustar:
- Umbrales de similitud
- Motores de búsqueda habilitados
- Configuración de OCR
- Timeouts y rate limits

---

## Soporte

- Issues: https://github.com/tu-usuario/aliah-plus/issues
- Discussions: https://github.com/tu-usuario/aliah-plus/discussions
- Email: support@aliah-plus.dev

---

**🎉 ¡Listo! Ya puedes usar Aliah-Plus**