# 🚀 Quick Start Guide

Guia rápido para testar e fazer deploy do `denes-router-classifier`.

---

## 📋 Você está aqui porque...

Você completou a **FASE 5** e agora tem:
- ✅ Package funcional em `denes-router-classifier/`
- ✅ Modelo treinado em `models/domain-classifier/` (638MB)
- ✅ Testes passando com ~36ms de latência

**Próximos passos:**
1. Testar o package localmente
2. Fazer upload do modelo para HuggingFace
3. Integrar no backend de produção

---

## 1️⃣ Testar Localmente (CLI)

```bash
cd denes-router-classifier

# Modo interativo (recomendado)
python classify_cli.py interactive

# Ou testar queries individuais
python classify_cli.py classify "Busca el clima en Asunción"
python classify_cli.py classify "No tengo internet"
python classify_cli.py classify "¿Qué es Python?"

# Ver informações
python classify_cli.py version
```

---

## 2️⃣ Deploy: Upload para HuggingFace

**Por que HuggingFace?**
- GitHub não aceita arquivos > 100MB
- Você tem HF Pro = modelos privados grátis!
- Download automático em produção

### Passo a Passo

```bash
cd denes-router-classifier

# 1. Instalar HuggingFace CLI
pip install huggingface_hub

# 2. Login (abrirá navegador)
huggingface-cli login

# 3. Editar USERNAME no upload_to_hf.py
nano upload_to_hf.py
# Mudar: REPO_ID = "SEU_USERNAME/denes-domain-classifier"
# Para:   REPO_ID = "seu-username-real/denes-domain-classifier"

# 4. Upload do modelo (1-2 minutos)
python upload_to_hf.py

# 5. Editar model_loader.py
nano src/denes_router_classifier/model_loader.py
# Mudar linha 28: HF_REPO_ID = "seu-username-real/denes-domain-classifier"

# 6. Testar download
python test_hf_download.py
```

**Resultado esperado:**
```
✅ SUCCESS!
HuggingFace Hub integration is working correctly!
```

---

## 3️⃣ Integrar no Backend

### No `denes-backend-python`:

```bash
cd ../denes-backend-python

# 1. Instalar package
uv add ../denes-router-trainning/denes-router-classifier

# 2. Configurar .env (se usando HF Hub)
echo "DENES_USE_HF_HUB=true" >> .env
echo "DENES_MODEL_REPO=seu-username/denes-domain-classifier" >> .env

# 3. Login no HuggingFace (servidor produção)
pip install huggingface_hub
huggingface-cli login
```

### Modificar `src/services/orchestrator.py`:

```python
from denes_router_classifier import classify_domain

# Substituir chamada LLM cara por BERT (linha ~168)
# ANTES:
# classified_domain = await domain_classifier.classify(...)

# DEPOIS:
result = classify_domain(
    text=request.message,
    threshold=0.7,
    multi_label=False
)
classified_domain = result.primary

logger.info(
    "🎯 Domain classified (BERT)",
    domain=classified_domain,
    confidence=result.confidence,
    includes_generic=result.includes_generic
)
```

---

## 📚 Documentação Completa

- **[HUGGINGFACE_SETUP.md](HUGGINGFACE_SETUP.md)** - Guia detalhado de HuggingFace
- **[DEPLOYMENT.md](DEPLOYMENT.md)** - Todas as opções de deployment
- **[README.md](README.md)** - Documentação completa da API
- **[CLI_COMMANDS.md](../CLI_COMMANDS.md)** - Comandos do CLI principal

---

## 🆘 Troubleshooting

### "Model not found"
```bash
# Verificar se upload funcionou
huggingface-cli repo-info seu-username/denes-domain-classifier

# Re-fazer upload se necessário
python upload_to_hf.py
```

### "Authentication required"
```bash
# Re-fazer login
huggingface-cli logout
huggingface-cli login
```

### "SEU_USERNAME not configured"
```bash
# Editar os arquivos:
# 1. upload_to_hf.py: linha ~6
# 2. model_loader.py: linha 28
# 3. test_hf_download.py: linha ~12
```

---

## ✅ Checklist Completo

- [ ] Testei CLI localmente (`python classify_cli.py interactive`)
- [ ] Fiz login no HuggingFace (`huggingface-cli login`)
- [ ] Editei `upload_to_hf.py` com meu username
- [ ] Fiz upload do modelo (`python upload_to_hf.py`)
- [ ] Editei `model_loader.py` com meu username
- [ ] Testei download (`python test_hf_download.py`)
- [ ] Instalei package no backend (`uv add ../denes-router-classifier`)
- [ ] Modifiquei `orchestrator.py` para usar BERT
- [ ] Testei em desenvolvimento
- [ ] Deploy em produção! 🚀

---

**🎉 Sucesso!** Agora você tem um classificador BERT rápido (36ms) e eficiente rodando em produção!
