docs/SPACES_SECRETS.md

# Secrets para Hugging Face Spaces

Guia completo para configurar secrets no Hugging Face Spaces para o RAG Template.

---

## Como Configurar Secrets

1. Acesse seu Space no Hugging Face
2. Va para **Settings**
3. Role ate a secao **Repository secrets**
4. Clique em **New secret** para cada secret necessario
5. Adicione nome e valor
6. Clique em **Add secret**

---

## Secrets Obrigatorios

### DATABASE_URL

**Obrigatorio**: Sim

Connection string do PostgreSQL com pgvector.

**Formato**:
```
postgresql://user:password@host:port/database
```

**Exemplos**:

```bash
# Supabase
postgresql://postgres:sua_senha@db.xxxxxxxxxxxxx.supabase.co:5432/postgres

# Neon
postgresql://user:senha@ep-xxx-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require

# Railway
postgresql://postgres:senha@containers-us-west-xxx.railway.app:5432/railway
```

**Importante**:
- Certifique-se de que a senha esta URL-encoded se conter caracteres especiais
- Para Neon, inclua `?sslmode=require`
- Teste a conexao antes de adicionar ao Space

**Como obter**:
- [Supabase Setup](SUPABASE_SETUP.md)
- [Neon Setup](NEON_SETUP.md)
- [Railway Setup](RAILWAY_SETUP.md)

---

## Secrets de LLM Providers

Voce precisa de **pelo menos um** destes para usar o chat:

### HF_TOKEN (Recomendado para Spaces)

**Obrigatorio**: Nao, mas recomendado

Token da Hugging Face para usar Inference API.

**Como obter**:
1. Va para [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
2. Crie novo token com permissao "read"
3. Copie o token

**Formato**:
```
hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Vantagens**:
- Gratuito (com limites)
- Sem necessidade de infraestrutura
- Varios modelos disponiveis

**Limites Free Tier**:
- ~30k tokens/hora
- Pode ter queue em horarios de pico

---

### OPENAI_API_KEY

**Obrigatorio**: Nao

Chave de API da OpenAI para usar GPT-4, GPT-3.5, etc.

**Como obter**:
1. Crie conta em [platform.openai.com](https://platform.openai.com)
2. Va para [API Keys](https://platform.openai.com/api-keys)
3. Crie nova secret key
4. Copie a chave (aparece apenas uma vez!)

**Formato**:
```
sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Custos** (Fevereiro 2024):
- GPT-3.5-turbo: $0.50 / 1M tokens input
- GPT-4-turbo: $10 / 1M tokens input
- GPT-4o: $5 / 1M tokens input

---

### ANTHROPIC_API_KEY

**Obrigatorio**: Nao

Chave de API da Anthropic para usar Claude.

**Como obter**:
1. Crie conta em [console.anthropic.com](https://console.anthropic.com)
2. Va para API Keys
3. Crie nova key
4. Copie a chave

**Formato**:
```
sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

**Custos** (Fevereiro 2024):
- Claude 3 Haiku: $0.25 / 1M tokens input
- Claude 3 Sonnet: $3 / 1M tokens input
- Claude 3 Opus: $15 / 1M tokens input

---

### OLLAMA_BASE_URL

**Obrigatorio**: Nao

URL do servidor Ollama para usar modelos locais.

**Como configurar**:
1. Instale Ollama localmente ou em servidor
2. Exponha via ngrok ou similar (para Spaces)
3. Use URL publica

**Formato**:
```
https://seu-servidor.com
```

**Nota**: Nao recomendado para Spaces publicos (requer servidor proprio).

---

## Secrets Opcionais

### EMBEDDING_MODEL_ID

**Default**: `sentence-transformers/all-MiniLM-L6-v2`

Modelo para gerar embeddings.

**Alternativas**:
```
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2  # Multilingue
sentence-transformers/all-mpnet-base-v2  # Melhor qualidade (768d)
BAAI/bge-small-en-v1.5  # Eficiente
```

---

### TOP_K

**Default**: `4`

Numero de documentos a recuperar na busca.

**Range**: 1-20

---

### TEMPERATURE

**Default**: `0.3`

Criatividade do LLM (0 = deterministico, 1 = criativo).

**Range**: 0.0-1.0

---

### MAX_TOKENS

**Default**: `512`

Tamanho maximo da resposta do LLM.

**Range**: 100-4096

---

## Exemplo Completo

```bash
# Obrigatorio
DATABASE_URL=postgresql://postgres:senha@db.xxx.supabase.co:5432/postgres

# LLM (escolha pelo menos um)
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# Opcional
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
TOP_K=4
TEMPERATURE=0.3
MAX_TOKENS=512
```

---

## Validacao de Secrets

Apos configurar, o app validara os secrets na inicializacao:

### Validacoes:
1. **DATABASE_URL**: Testa conexao e verifica extensao pgvector
2. **HF_TOKEN**: Testa autenticacao (se fornecido)
3. **OPENAI_API_KEY**: Testa autenticacao (se fornecido)
4. **ANTHROPIC_API_KEY**: Testa autenticacao (se fornecido)

### Logs de inicializacao:
```
Conectando ao banco de dados...
  DATABASE_URL: OK
  Extensao pgvector: OK
Verificando LLM providers...
  HuggingFace: OK
  OpenAI: NAO CONFIGURADO
  Anthropic: NAO CONFIGURADO
```

---

## Seguranca

### Boas Praticas:

1. **Nunca compartilhe secrets publicamente**
   - Nao commite no Git
   - Nao coloque em codigo
   - Nao compartilhe em issues/forums

2. **Rotacao de secrets**
   - Troque secrets periodicamente
   - Revogue secrets antigos
   - Use secrets separados para dev/prod

3. **Principio do menor privilegio**
   - Use apenas permissoes necessarias
   - Para HF_TOKEN, permissao "read" e suficiente
   - Nao use tokens com permissoes de "write"

4. **Monitoring**
   - Monitore uso de API keys
   - Configure alerts de uso anormal
   - Revogue imediatamente se comprometido

---

## Troubleshooting

### "Unable to connect to database"

**Causa**: DATABASE_URL incorreto ou banco inacessivel

**Solucao**:
1. Verifique formato da URL
2. Teste conexao localmente
3. Verifique se banco esta ativo (Supabase nao pausado)

---

### "HF_TOKEN invalid"

**Causa**: Token invalido ou expirado

**Solucao**:
1. Gere novo token em huggingface.co/settings/tokens
2. Certifique-se de copiar token completo
3. Token deve comecar com `hf_`

---

### "OpenAI authentication failed"

**Causa**: OPENAI_API_KEY invalida

**Solucao**:
1. Verifique se key e valida em platform.openai.com
2. Certifique-se de ter creditos na conta
3. Key deve comecar com `sk-`

---

### "Extension 'vector' not found"

**Causa**: pgvector nao habilitado no banco

**Solucao**:
```sql
-- Execute no SQL Editor do seu provider
CREATE EXTENSION vector;
```

---

## Limitacoes do Free Tier

### Hugging Face Spaces
- Secrets podem ser vistos por administradores do Space
- Spaces publicos podem ter limite de uso
- Cold start pode demorar

### LLM Providers
- **HuggingFace**: ~30k tokens/hora
- **OpenAI**: Requer creditos ($5 minimo inicial)
- **Anthropic**: Requer creditos ($5 minimo inicial)

---

## Recursos Adicionais

- [Supabase Setup](SUPABASE_SETUP.md)
- [Neon Setup](NEON_SETUP.md)
- [Railway Setup](RAILWAY_SETUP.md)
- [Database Comparison](DATABASE_COMPARISON.md)

---

## Suporte

Se encontrar problemas:
1. Verifique logs do Space
2. Teste conexoes localmente
3. Abra issue no [GitHub](https://github.com/guifav/rag_template/issues)

---

**Feito com muito cafe**