# Deployment Guide: Handling Large Model Files

O modelo treinado (`model.safetensors`) tem ~638MB, o que excede o limite do GitHub (100MB). Este guia apresenta diferentes soluções para deploy em produção.

---

## 🤗 Opção 1: HuggingFace Hub - ⭐ RECOMENDADO (Você tem HF Pro!)

**Vantagens:**
- ✅ **Grátis e ilimitado** (com HF Pro)
- ✅ Modelo **privado** (só você acessa)
- ✅ Download automático no primeiro uso
- ✅ Versionamento automático
- ✅ Cache local (~/.cache/huggingface/)
- ✅ Sem limites de bandwidth

### 📖 Guia Completo

**Ver:** [HUGGINGFACE_SETUP.md](HUGGINGFACE_SETUP.md) - Passo a passo detalhado

### Quick Start

```bash
# 1. Login no HuggingFace
pip install huggingface_hub
huggingface-cli login

# 2. Editar e fazer upload do modelo
# Editar upload_to_hf.py: mudar SEU_USERNAME para seu username real
python upload_to_hf.py

# 3. Editar model_loader.py
# Mudar HF_REPO_ID = "seu-username/denes-domain-classifier"

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

### Deploy em Produção

```bash
# No servidor
pip install huggingface_hub
huggingface-cli login  # Uma vez apenas

# Instalar package (modelo baixa automaticamente)
cd denes-backend-python
uv add ../denes-router-classifier
```

---

## 🎯 Opção 2: Git LFS (Large File Storage)

**Vantagens:**
- ✅ Versionamento completo do modelo
- ✅ Integração nativa com Git/GitHub
- ✅ Download automático durante clone

**Desvantagens:**
- ⚠️ GitHub Free: 1GB storage + 1GB bandwidth/mês
- ⚠️ GitHub Pro: 2GB storage + 10GB bandwidth/mês
- 💰 Custos extras se exceder limites

### Setup

```bash
# 1. Instalar Git LFS
brew install git-lfs  # macOS
# ou
sudo apt-get install git-lfs  # Linux

# 2. Inicializar Git LFS no repositório
cd denes-router-trainning
git lfs install

# 3. Rastrear arquivos grandes
git lfs track "denes-router-classifier/models/domain-classifier/*.safetensors"
git lfs track "denes-router-classifier/models/domain-classifier/*.bin"

# 4. Commit do .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS for model files"

# 5. Adicionar e commitar o modelo
git add denes-router-classifier/models/
git commit -m "Add trained domain classifier model"
git push origin main
```

### Deploy em Produção

```bash
# Clone normal funciona (Git LFS baixa automaticamente)
git clone https://github.com/yourusername/denes-router-trainning.git
cd denes-router-trainning

# Instalar package
cd ../denes-backend-python
uv add ../denes-router-trainning/denes-router-classifier
```

---

## 🌐 Opção 2: Cloud Storage (S3/Google Cloud Storage)

**Vantagens:**
- ✅ Sem limite de tamanho
- ✅ Baixo custo (centavos/GB)
- ✅ Download rápido

**Desvantagens:**
- ⚠️ Requer configuração de cloud
- ⚠️ Download manual durante deploy

### Setup com AWS S3

#### 1. Upload do Modelo

```bash
# Instalar AWS CLI
pip install awscli

# Configurar credenciais
aws configure

# Upload do modelo
aws s3 cp denes-router-classifier/models/domain-classifier/ \
    s3://seu-bucket/denes-models/domain-classifier/ \
    --recursive \
    --acl private
```

#### 2. Script de Download Automático

Criar `denes-router-classifier/download_model.py`:

```python
#!/usr/bin/env python3
"""Download trained model from S3 if not present locally."""

import os
import subprocess
from pathlib import Path

MODEL_DIR = Path(__file__).parent / "models" / "domain-classifier"
S3_BUCKET = "seu-bucket"
S3_PREFIX = "denes-models/domain-classifier/"

def download_model():
    """Download model from S3 if not present."""
    if MODEL_DIR.exists() and (MODEL_DIR / "model.safetensors").exists():
        print(f"✓ Model already exists at {MODEL_DIR}")
        return

    print(f"Downloading model from S3...")
    MODEL_DIR.mkdir(parents=True, exist_ok=True)

    # Download via AWS CLI
    cmd = [
        "aws", "s3", "sync",
        f"s3://{S3_BUCKET}/{S3_PREFIX}",
        str(MODEL_DIR),
        "--quiet"
    ]

    result = subprocess.run(cmd, capture_output=True, text=True)

    if result.returncode == 0:
        print(f"✓ Model downloaded successfully to {MODEL_DIR}")
    else:
        print(f"✗ Error downloading model: {result.stderr}")
        raise Exception("Model download failed")

if __name__ == "__main__":
    download_model()
```

#### 3. Integração no Backend

Modificar `denes_router_classifier/model_loader.py`:

```python
def get_model() -> AutoModelForSequenceClassification:
    """Get loaded model (singleton pattern)."""
    global _model, _loaded

    if not _loaded:
        model_path = get_model_path()

        # Auto-download if not present
        if not model_path.exists():
            logger.warning(f"Model not found at {model_path}, downloading...")
            from .download_model import download_model
            download_model()

        # ... rest of loading logic
```

#### 4. Deploy

```bash
# No servidor de produção
cd denes-backend-python
uv add ../denes-router-classifier

# Modelo será baixado automaticamente no primeiro uso
```

---

## 📦 Opção 3: HuggingFace Hub

**Vantagens:**
- ✅ Grátis e ilimitado
- ✅ Versionamento automático
- ✅ API simples

**Desvantagens:**
- ⚠️ Modelos públicos por padrão (private requer HF Pro)

### Setup

```bash
# 1. Instalar huggingface_hub
pip install huggingface_hub

# 2. Login
huggingface-cli login
```

#### Upload do Modelo

```python
from huggingface_hub import HfApi

api = HfApi()

# Upload do modelo para HuggingFace
api.upload_folder(
    folder_path="denes-router-classifier/models/domain-classifier",
    repo_id="seu-usuario/denes-domain-classifier",
    repo_type="model",
)
```

#### Download Automático

Modificar `model_loader.py`:

```python
from huggingface_hub import snapshot_download

def get_model():
    model_path = get_model_path()

    if not model_path.exists():
        logger.info("Downloading model from HuggingFace Hub...")
        snapshot_download(
            repo_id="seu-usuario/denes-domain-classifier",
            local_dir=str(model_path),
            local_dir_use_symlinks=False
        )

    # ... rest of loading logic
```

---

## 🔧 Opção 4: Build-time Download (Docker)

**Vantagens:**
- ✅ Modelo incluído na imagem Docker
- ✅ Deploy simplificado

**Desvantagens:**
- ⚠️ Imagem Docker grande (~2GB)
- ⚠️ Rebuilds lentos

### Dockerfile

```dockerfile
FROM python:3.10-slim

WORKDIR /app

# Install dependencies
COPY pyproject.toml ./
RUN pip install -e .

# Download model during build
ARG MODEL_URL
RUN wget -O /tmp/model.tar.gz ${MODEL_URL} && \
    tar -xzf /tmp/model.tar.gz -C /app/models/ && \
    rm /tmp/model.tar.gz

# Copy application
COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
```

### Build

```bash
# Comprimir modelo
cd denes-router-classifier
tar -czf domain-classifier.tar.gz models/domain-classifier/

# Upload para servidor temporário
scp domain-classifier.tar.gz user@server:/var/www/models/

# Build Docker
docker build \
    --build-arg MODEL_URL=https://server.com/models/domain-classifier.tar.gz \
    -t denes-backend .
```

---

## 📊 Comparação de Opções

| Opção | Custo | Complexidade | Versionamento | Recomendado |
|-------|-------|--------------|---------------|-------------|
| **Git LFS** | $ (após limites) | Baixa | ✅ Sim | ✅ Para repositórios privados |
| **S3/Cloud** | $$ (centavos/GB) | Média | ⚠️ Manual | ✅ Para produção escalável |
| **HuggingFace** | Grátis | Baixa | ✅ Sim | ⚠️ Só se público |
| **Docker Build** | $ (storage) | Alta | ⚠️ Por imagem | ⚠️ Para deploys esporádicos |

---

## 🎯 Recomendação Final

### Para o projeto Denes:

**1. Desenvolvimento:** Git LFS
```bash
git lfs track "*.safetensors"
git add .gitattributes denes-router-classifier/models/
git commit -m "Add model with Git LFS"
```

**2. Produção:** Cloud Storage (S3) + Download Automático
- Modelo fica em S3 privado
- Backend baixa automaticamente no primeiro uso
- Custo: ~$0.02/mês (storage) + $0.001/download

**3. Alternativa Budget:** HuggingFace Hub (se modelo pode ser público)
- Grátis e ilimitado
- Download automático via `transformers`

---

## 🚀 Script de Deploy Recomendado

Criar `deploy.sh`:

```bash
#!/bin/bash
set -e

echo "🚀 Deploying Denes Router Classifier..."

# 1. Check if model exists locally
if [ ! -f "denes-router-classifier/models/domain-classifier/model.safetensors" ]; then
    echo "📥 Downloading model from S3..."
    python denes-router-classifier/download_model.py
fi

# 2. Install package
echo "📦 Installing package..."
cd denes-backend-python
uv add ../denes-router-classifier

# 3. Run tests
echo "✅ Running tests..."
uv run pytest tests/test_classifier.py

echo "✓ Deployment complete!"
```

---

## 📝 Next Steps

1. Escolher opção de deploy (Git LFS ou S3)
2. Configurar download automático
3. Testar em staging
4. Deploy em produção
5. Monitorar uso e performance
