docs/tutorials/use_cases/technical_docs_chatbot.md

# Caso de Uso: Chatbot de Documentacao Tecnica

Guia completo para criar um chatbot que responde perguntas sobre documentacao tecnica.

**Nivel**: Intermediario
**Tempo**: 30-45 minutos
**Exemplo**: Chatbot para documentacao de API

---

## Cenario

Voce tem documentacao tecnica extensa (manuais, API docs, guias) e quer:
- Responder perguntas dos desenvolvedores rapidamente
- Reduzir tempo de onboarding
- Liberar time de suporte tecnico
- Garantir respostas precisas com citacao de fontes

---

## Passo 1: Preparar Documentacao

### 1.1 Organizar Documentos

Estrutura recomendada:
```
docs/
├── api/
│   ├── authentication.md
│   ├── endpoints.md
│   └── errors.md
├── guides/
│   ├── getting_started.md
│   ├── best_practices.md
│   └── deployment.md
└── reference/
    ├── cli.md
    └── configuration.md
```

### 1.2 Converter para Formato Suportado

O RAG Template suporta:
- TXT (texto plano)
- PDF (via pypdf)

**Se sua documentacao esta em**:
- **Markdown**: Converta para TXT ou use como esta
- **HTML**: Extraia texto com BeautifulSoup
- **DOCX**: Converta para PDF ou TXT

**Exemplo de conversao MD para TXT**:
```bash
for file in docs/**/*.md; do
    pandoc "$file" -t plain -o "${file%.md}.txt"
done
```

---

## Passo 2: Otimizar Chunking para Docs Tecnicas

Documentacao tecnica tem caracteristicas especiais:
- Codigo embutido
- Listas de parametros
- Exemplos de uso
- Referencias cruzadas

### 2.1 Estrategia Recomendada

Use **chunking recursivo** com separadores customizados:

```python
# Em src/chunking.py (ja implementado)
SEPARATORS = [
    "\n## ",  # Secoes Markdown
    "\n### ", # Subsecoes
    "\n\n",   # Paragrafos
    "\n",     # Linhas
    " "       # Palavras
]
```

### 2.2 Tamanho de Chunk

Para docs tecnicas:
- **Chunk size**: 800-1000 caracteres
- **Overlap**: 150-200 caracteres

**Razao**: Preservar contexto de exemplos de codigo completos.

### 2.3 Teste de Chunking

Use a aba "Comparacao de Chunking":
1. Cole exemplo de doc tecnica
2. Compare 4 estrategias
3. Veja qual mantem codigo/listas intactos

---

## Passo 3: Configurar Embeddings para Dominio Tecnico

### 3.1 Modelo Recomendado

Para docs tecnicas em ingles:
```env
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
```

Alternativas:
- `BAAI/bge-small-en-v1.5` (melhor para docs tecnicos)
- `sentence-transformers/all-mpnet-base-v2` (mais qualidade, 768d)

Para multilingu e (PT-BR + EN):
```env
EMBEDDING_MODEL_ID=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
```

### 3.2 Ingerir Documentacao

```bash
# Inicie a aplicacao
python app.py

# Aba: Ingestao de Documentos
# 1. Upload de todos os arquivos (batch)
# 2. Estrategia: Recursivo
# 3. Chunk Size: 900
# 4. Overlap: 200
# 5. Iniciar Ingestao
```

**Tempo estimado**: ~5-10min para 100 docs

---

## Passo 4: Configurar Retrieval Otimizado

### 4.1 Hybrid Search

Documentacao tecnica se beneficia de hybrid search:
- **BM25**: Para termos tecnicos exatos (nomes de funcoes, parametros)
- **Vetorial**: Para busca semantica (conceitos)

Configure:
```env
USE_HYBRID_SEARCH=true
HYBRID_ALPHA=0.4  # Enfase em BM25 para termos exatos
```

### 4.2 Reranking

Ative reranking para melhor precisao:
```env
USE_RERANKING=true
RERANKING_TOP_K=5
```

**Pipeline**:
1. Hybrid search recupera 20 documentos
2. Reranker seleciona top 5 mais relevantes
3. LLM usa apenas os 5 melhores

---

## Passo 5: Configurar LLM para Docs Tecnicas

### 5.1 Escolher LLM

Para docs tecnicas, recomendamos:
- **GPT-4** (melhor, mas caro): Entende codigo perfeitamente
- **GPT-3.5-turbo** (bom custo-beneficio): Adequado para maioria
- **Claude 3** (excelente para textos longos)

```env
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
```

### 5.2 Ajustar Parametros

```env
TOP_K=5              # Contextos recuperados
TEMPERATURE=0.2      # Baixa = mais preciso
MAX_TOKENS=512       # Respostas concisas
```

### 5.3 Customizar Prompt

Edite `src/generation.py` para prompt especifico:

```python
SYSTEM_PROMPT = """
Voce e um assistente especializado em documentacao tecnica.

DIRETRIZES:
1. Responda APENAS com base nos contextos fornecidos
2. Se a resposta nao esta nos contextos, diga "Nao encontrei essa informacao na documentacao"
3. Cite sempre a secao/arquivo de onde veio a informacao
4. Para codigo, use formatacao markdown com ```
5. Seja preciso e tecnico, nao simplifique demais

FORMATO DE RESPOSTA:
- Resposta direta e objetiva
- Exemplo de codigo (se aplicavel)
- Referencia: [Secao X da Documentacao]
"""
```

---

## Passo 6: Testar e Refinar

### 6.1 Casos de Teste

Crie suite de perguntas comuns:

```
1. Como autenticar na API?
2. Quais sao os endpoints disponiveis?
3. Como tratar erro 401?
4. Qual o rate limit da API?
5. Como fazer deploy em producao?
```

### 6.2 Avaliar Qualidade

Para cada pergunta, verifique:
- Resposta esta correta?
- Fonte esta citada?
- Codigo de exemplo esta incluso (se relevante)?
- Resposta e completa mas concisa?

### 6.3 Iterar

Se qualidade nao e satisfatoria:
1. Ajuste chunk_size
2. Teste hybrid_alpha diferente
3. Aumente/diminua top_k
4. Melhore prompt
5. Considere modelo de LLM melhor

---

## Passo 7: Interface Customizada (Opcional)

### 7.1 Adicionar Features Especificas

Exemplo: Botao "Ver na Documentacao":

```python
# ui/chat_tab.py
def chat_tab():
    # ... codigo existente ...

    with gr.Accordion("Contextos Recuperados"):
        for ctx in contexts:
            with gr.Row():
                gr.Markdown(ctx['content'])
                gr.Button(
                    "Ver Doc Original",
                    link=f"/docs/{ctx['source']}"
                )
```

### 7.2 Adicionar Atalhos

Botoes para perguntas comuns:

```python
common_questions = [
    "Como autenticar?",
    "Quais endpoints existem?",
    "Como tratar erros?",
]

for q in common_questions:
    gr.Button(q).click(
        fn=lambda x=q: x,
        outputs=query_input
    )
```

---

## Passo 8: Deploy

### 8.1 Opcoes Recomendadas

Para chatbot de docs tecnicas:
- **Interno**: Docker em VPS privado
- **Publico**: Hugging Face Spaces ou Railway
- **Enterprise**: Kubernetes com autenticacao

### 8.2 Consideracoes de Seguranca

Se docs sao privadas:
1. Nao use Hugging Face Spaces publico
2. Configure autenticacao (Gradio auth)
3. Use VPN/firewall
4. Database privado

```python
# app.py
demo.launch(
    auth=("username", "password"),
    server_name="0.0.0.0",
    server_port=7860,
    share=False  # Nao criar link publico
)
```

---

## Passo 9: Monitoramento

### 9.1 Metricas Importantes

Track:
- **Perguntas mais comuns**: Identifique gaps na doc
- **Taxa de "nao encontrei"**: Indica docs incompletas
- **Tempo de resposta**: Otimize se >5s
- **Feedback dos usuarios**: Thumbs up/down

### 9.2 Melhorias Continuas

Baseado em dados:
1. Adicione docs para perguntas frequentes sem resposta
2. Melhore chunking se contextos estao quebrados
3. Atualize prompt baseado em feedback
4. Considere fine-tuning se volume e alto

---

## Resultados Esperados

### Antes (sem chatbot)
- Tempo medio para resposta: 30min-2h
- Desenvolvedores pesquisando em docs extensas
- Suporte sobrecarregado

### Depois (com RAG chatbot)
- Tempo medio: <30 segundos
- Auto-servico para 70-80% das perguntas
- Suporte focado em problemas complexos
- Onboarding 3x mais rapido

---

## Casos Reais

### Exemplo 1: Startup de API

**Situacao**: 500 paginas de API docs, time pequeno
**Solucao**: RAG chatbot com GPT-3.5
**Resultado**:
- 60% reducao em tickets de suporte
- NPS +15 pontos
- Tempo de onboarding: 2 semanas → 3 dias

### Exemplo 2: Empresa Enterprise

**Situacao**: Docs internas distribuidas, 10k+ paginas
**Solucao**: RAG com hybrid search + reranking
**Resultado**:
- Busca 10x mais rapida que busca nativa
- Encontra informacao cross-docs
- ROI positivo em 2 meses

---

## Proximos Passos

1. **Multi-idioma**: Adicione docs em outros idiomas
2. **Feedback loop**: Implemente thumbs up/down
3. **Analytics**: Track metricas de uso
4. **Integracoes**: Slack bot, VS Code extension

---

## Recursos

- [Tutorial: Otimizando RAG](../02_optimizing_rag.md)
- [Tutorial: Deploy em Producao](../03_production_deployment.md)
- [FAQ](../../FAQ.md)

---

**Tempo total de implementacao**: 2-4 horas
**Manutencao**: ~1h/semana (adicionar novos docs)