# 🔌 Integração com Backend - Guia Completo

Este guia explica **exatamente** o que acontece quando você instala o `denes-router-classifier` no `denes-backend-python`.

---

## 🤔 Suas Dúvidas Respondidas

### ❓ "Não entendi o que eu devo fazer sobre instalar package"

**Resposta:** Quando você roda `uv add ../denes-router-classifier`, o que acontece é:

1. ✅ O **código Python** do package é instalado em `.venv/lib/python3.x/site-packages/`
2. ✅ As **dependências** (torch, transformers, pydantic) são instaladas
3. ❌ O **modelo NÃO** é copiado para o backend

**O modelo fica em:**
- 📁 **Desenvolvimento:** `denes-router-classifier/models/domain-classifier/` (local)
- ☁️ **Produção:** HuggingFace Hub → baixado para `~/.cache/huggingface/hub/`

### ❓ "Como vai ficar com o GitHub? Vai gerar problema ao sincronizar?"

**Resposta:** **NÃO vai gerar problema!**

O modelo (~638MB) **NUNCA** vai para o repositório `denes-backend-python`:

```
denes-backend-python/         ← Repositório GitHub
├── .venv/                     ← .gitignore (não vai pro Git)
│   └── lib/.../denes_router_classifier/  ← Código do package (só Python)
├── src/
├── .gitignore                 ← Ignora .venv/
└── ...

~/.cache/huggingface/hub/      ← Modelo baixado do HuggingFace
└── models--mlima001--denes-router/
    └── snapshots/.../model.safetensors (638MB)
```

**O que vai pro Git:**
- ✅ Código modificado (`orchestrator.py` com import do classifier)
- ✅ Dependências atualizadas (`pyproject.toml`, `uv.lock`)
- ❌ **Modelo NÃO** (fica no HuggingFace + cache local)

---

## 📦 O que é o "Package"?

O `denes-router-classifier` é um **package Python** que contém:

```
denes-router-classifier/
├── src/
│   └── denes_router_classifier/
│       ├── __init__.py         ← Exports (classify_domain, etc.)
│       ├── classifier.py       ← Lógica de classificação
│       ├── model_loader.py     ← Download automático do HuggingFace
│       └── schemas.py          ← Tipos Pydantic
├── pyproject.toml              ← Configuração do package
└── models/                     ← Modelo (NÃO instalado no backend!)
    └── domain-classifier/
```

**Quando você instala o package:**
- ✅ Arquivos `.py` são copiados para `.venv/`
- ❌ Pasta `models/` **NÃO** é copiada

---

## 🚀 Instalação Passo a Passo

### 1️⃣ Instalar o Package

```bash
cd denes-backend-python

# Opção A: De caminho local (desenvolvimento)
uv add ../denes-router-trainning/denes-router-classifier

# Opção B: De Git (futuro)
uv add git+https://github.com/yourusername/denes-router-trainning.git#subdirectory=denes-router-classifier
```

**O que acontece:**
```
✓ Código Python instalado em .venv/lib/.../denes_router_classifier/
✓ Dependências instaladas (torch, transformers, pydantic)
✓ pyproject.toml atualizado
✓ uv.lock atualizado
```

### 2️⃣ Configurar Variáveis de Ambiente

Editar `denes-backend-python/.env`:

```bash
# BERT Classifier Configuration
USE_DENES_CLASSIFIER=true              # true=BERT, false=LLM (default: true)

# HuggingFace Configuration (se modelo não estiver local)
DENES_USE_HF_HUB=true                  # Habilitar download do HuggingFace
DENES_MODEL_REPO=mlima001/denes-router # Seu repositório HuggingFace
```

### 3️⃣ Login no HuggingFace (Servidor de Produção)

**⚠️ Apenas uma vez no servidor:**

```bash
pip install huggingface_hub
huggingface-cli login
```

Isso salva o token em `~/.huggingface/token`.

### 4️⃣ Testar

```bash
cd denes-backend-python

# Testar importação
uv run python -c "from denes_router_classifier import classify_domain; print('✅ Package instalado!')"

# Primeira chamada baixará o modelo (~1-2 minutos)
uv run python -c "from denes_router_classifier import classify_domain; r = classify_domain('test'); print(f'✅ Modelo carregado: {r.primary}')"
```

---

## 🏗️ Arquitetura Completa

```
┌─────────────────────────────────────────────────────────────┐
│ GitHub Repository: denes-backend-python                     │
├─────────────────────────────────────────────────────────────┤
│ src/services/orchestrator.py                                │
│   ↓ import denes_router_classifier                          │
│   ↓ classify_domain(text, threshold=0.7)                    │
└─────────────────────────────────────────────────────────────┘
           │
           │ (importa de .venv/)
           ↓
┌─────────────────────────────────────────────────────────────┐
│ .venv/lib/python3.x/site-packages/                          │
│ denes_router_classifier/                                    │
│   ├── __init__.py                                           │
│   ├── classifier.py                                         │
│   ├── model_loader.py  ← Faz download se necessário        │
│   └── schemas.py                                            │
└─────────────────────────────────────────────────────────────┘
           │
           │ (1ª chamada: baixa modelo)
           ↓
┌─────────────────────────────────────────────────────────────┐
│ ☁️ HuggingFace Hub                                          │
│ https://huggingface.co/mlima001/denes-router               │
│                                                              │
│ 🔒 Modelo Privado (só você acessa)                         │
│ model.safetensors (638MB)                                   │
│ tokenizer.json, config.json, etc.                           │
└─────────────────────────────────────────────────────────────┘
           │
           │ (download automático)
           ↓
┌─────────────────────────────────────────────────────────────┐
│ ~/.cache/huggingface/hub/                                   │
│ models--mlima001--denes-router/                             │
│   └── snapshots/abc123/                                     │
│       ├── model.safetensors  (638MB)                        │
│       ├── tokenizer.json                                    │
│       └── config.json                                       │
│                                                              │
│ ✅ Cache local (próximas chamadas = instantâneas)          │
└─────────────────────────────────────────────────────────────┘
```

---

## ⚙️ Configuração via Variáveis de Ambiente

### `USE_DENES_CLASSIFIER` (orchestrator.py)

Controla qual classificador usar:

```bash
# BERT Classifier (rápido, ~36ms)
USE_DENES_CLASSIFIER=true   # ← Default

# LLM Classifier (comportamento original)
USE_DENES_CLASSIFIER=false
```

**Quando usar BERT:**
- ✅ Produção (rápido, econômico)
- ✅ Alto volume de requests
- ✅ Domínios fixos (Web_Search, TI, Generic)

**Quando usar LLM:**
- ⚠️ Desenvolvimento/testes
- ⚠️ Domínios customizados (além dos 3 treinados)
- ⚠️ Casos especiais com contexto complexo

### `DENES_USE_HF_HUB` (model_loader.py)

Controla download do HuggingFace:

```bash
# Habilitar download automático do HuggingFace
DENES_USE_HF_HUB=true   # ← Default

# Usar apenas modelo local (desenvolvimento)
DENES_USE_HF_HUB=false
```

### `DENES_MODEL_REPO` (model_loader.py)

Repositório HuggingFace:

```bash
DENES_MODEL_REPO=mlima001/denes-router
```

---

## 🔄 Workflow Completo

### Desenvolvimento (MacBook)

```bash
cd denes-backend-python

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

# 2. Modelo já existe em ../denes-router-classifier/models/
#    (não precisa baixar do HuggingFace)

# 3. Testar
uv run python -c "from denes_router_classifier import classify_domain; print(classify_domain('test'))"

# ✅ Usa modelo local instantaneamente
```

### Produção (Servidor)

```bash
cd denes-backend-python

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

# 2. Login no HuggingFace (uma vez)
pip install huggingface_hub
huggingface-cli login

# 3. Configurar .env
echo "USE_DENES_CLASSIFIER=true" >> .env
echo "DENES_USE_HF_HUB=true" >> .env
echo "DENES_MODEL_REPO=mlima001/denes-router" >> .env

# 4. Primeira chamada (baixa modelo)
uv run python -c "from denes_router_classifier import classify_domain; print(classify_domain('test'))"
# → Baixa modelo para ~/.cache/huggingface/ (~1-2 minutos)

# 5. Próximas chamadas (instantâneas)
# ✅ Usa cache local
```

---

## 📊 Comparação: BERT vs LLM

| Aspecto | BERT Classifier | LLM Classifier |
|---------|----------------|----------------|
| **Latência** | ~36ms | ~500-2000ms |
| **Custo** | Grátis (CPU local) | $$ (chamadas LLM) |
| **Domínios** | 3 fixos (Web_Search, TI, Generic) | Flexível |
| **Contexto** | Sem histórico | Com histórico |
| **Accuracy** | 100% (test set) | Variável |
| **Configuração** | `USE_DENES_CLASSIFIER=true` | `USE_DENES_CLASSIFIER=false` |

---

## 🆘 Troubleshooting

### "ModuleNotFoundError: No module named 'denes_router_classifier'"

```bash
# Reinstalar package
cd denes-backend-python
uv add ../denes-router-classifier --force
```

### "Model not found at..."

```bash
# Verificar variáveis de ambiente
echo $DENES_USE_HF_HUB     # Deve ser "true"
echo $DENES_MODEL_REPO     # Deve ser "mlima001/denes-router"

# Verificar login HuggingFace
huggingface-cli whoami

# Re-fazer login se necessário
huggingface-cli logout
huggingface-cli login
```

### "Modelo está indo pro Git!"

```bash
# Verificar .gitignore
cat denes-backend-python/.gitignore | grep ".venv"

# Deve ter:
.venv/
__pycache__/
*.pyc

# O modelo NUNCA vai estar em denes-backend-python/
# Ele fica em ~/.cache/huggingface/
```

### "GitHub rejeitou push (arquivo grande)"

**Isso NÃO deve acontecer porque o modelo não está no repositório!**

Se aconteceu:
```bash
# Verificar o que está no stage
git status

# Se modelo estiver staged:
git reset HEAD models/
git reset HEAD denes-router-classifier/models/

# Adicionar ao .gitignore
echo "models/" >> .gitignore
echo "denes-router-classifier/models/" >> .gitignore
```

---

## ✅ Checklist de Integração

- [ ] Package instalado (`uv add ../denes-router-classifier`)
- [ ] `orchestrator.py` importa `classify_domain` ✅ (já feito!)
- [ ] Variável `USE_DENES_CLASSIFIER=true` em `.env`
- [ ] Login no HuggingFace (servidor): `huggingface-cli login`
- [ ] Variável `DENES_MODEL_REPO=mlima001/denes-router` em `.env`
- [ ] Testado localmente
- [ ] Testado em staging
- [ ] Deploy em produção
- [ ] Verificado que modelo NÃO foi pro Git

---

## 🎉 Resultado Final

Após integração completa:

```python
# Em denes-backend-python/src/services/orchestrator.py

# ✅ Import adicionado (linha 14)
from denes_router_classifier import classify_domain

# ✅ Flag configurável (linhas 23-32)
USE_DENES_CLASSIFIER = os.getenv("USE_DENES_CLASSIFIER", "true").lower() == "true"

# ✅ Classificação BERT (linhas 182-222)
if USE_DENES_CLASSIFIER:
    result = classify_domain(text=request.message, threshold=0.7)
    classified_domain = domain_mapping.get(result.primary, "GENERIC")
    # ~36ms de latência ⚡
```

**Benefícios:**
- ⚡ **18x mais rápido** (36ms vs 500-2000ms)
- 💰 **Economia** (sem chamadas LLM para classificação)
- 🔒 **Privado** (modelo no HuggingFace privado)
- 🚀 **Configurável** (liga/desliga via env var)
- ✅ **Sem problemas no Git** (modelo no HuggingFace, não no repo)

---

**Dúvidas resolvidas?** 🎯
