docs/ARCHITECTURE.md

# Arquitetura do AetherMap

Este documento descreve o desenho técnico do AetherMap como sistema de cartografia semântica e RAG híbrido.

## Visão Geral

O AetherMap tem duas capacidades principais:

1. Cartografia semântica: transformar um corpus em um mapa 3D navegável, com clusters, métricas textuais, duplicados e entidades.
2. RAG híbrido: responder perguntas usando documentos recuperados por busca semântica e lexical, com reranking e citações.

O backend fica concentrado em [../app.py](../app.py). Ele expõe uma API FastAPI, mantém jobs em cache de memória e usa modelos locais para embeddings/reranking, além de APIs externas para geração e busca web.

## Fluxo de Ingestão

```text
Upload TXT/CSV
  -> leitura inteligente do arquivo
  -> seleção da coluna textual, quando CSV
  -> lista de textos
  -> embeddings SentenceTransformer
  -> UMAP ou PCA para 3D
  -> HDBSCAN para clusters
  -> normalização dos embeddings
  -> índice FAISS
  -> índice BM25
  -> métricas globais
  -> análise de duplicados
  -> análise TF-IDF por cluster
  -> cache em memória por job_id
```

O endpoint responsável é `/process/`.

### Saídas principais de `/process/`

| Campo | Significado |
| --- | --- |
| `job_id` | Identificador do processamento salvo em cache |
| `metadata.num_documents_processed` | Total de documentos processados |
| `metadata.num_clusters_found` | Número de clusters HDBSCAN sem contar ruído |
| `metadata.num_noise_points` | Pontos classificados como ruído (`-1`) |
| `metrics.riqueza_lexical` | Tamanho do vocabulário filtrado |
| `metrics.top_tfidf_palavras` | Palavras mais relevantes por TF-IDF global |
| `metrics.entropia` | Entropia de Shannon das contagens de termos |
| `duplicates` | Duplicados exatos e pares semanticamente muito similares |
| `cluster_analysis` | Top termos por cluster |
| `plot_data` | Coordenadas 3D, cluster e texto para visualização |

## Fluxo de Busca RAG

```text
Query + job_id
  -> validação do job em cache
  -> expansão opcional da query via LLM
  -> embedding da query
  -> busca FAISS
  -> busca BM25
  -> fusão RRF quando híbrido
  -> reranking CrossEncoder quando habilitado
  -> top documentos como contexto
  -> prompt de resposta com regras de citação e honestidade
  -> resposta via OpenRouter
```

O endpoint responsável é `/search/`.

### Modos de Ablação

| Modo | Uso |
| --- | --- |
| `faiss_only` | Mede a força da recuperação semântica pura |
| `bm25_only` | Mede a força da busca lexical pura |
| `hybrid` | Mede o ganho da fusão FAISS + BM25 por RRF |
| `hybrid_rerank` | Mede o ganho do CrossEncoder sem expansão de query |
| `full` | Mede o pipeline completo |

Esses modos são valiosos porque permitem responder a uma pergunta de engenharia importante: cada componente está pagando seu custo de latência com ganho real de qualidade?

## Escolhas Técnicas

### FAISS + BM25

FAISS cobre similaridade semântica: bom para sinônimos, paráfrases e linguagem natural. BM25 cobre correspondência lexical: bom para nomes próprios, termos raros, códigos, siglas e consultas onde a palavra exata importa. A fusão por RRF reduz a dependência de uma única fonte de ranking.

### Reranker CrossEncoder

O reranker avalia pares `(query, documento)` diretamente. Isso custa mais que cosine similarity, mas tende a melhorar precisão nos top resultados, que são justamente os documentos que entram no prompt do LLM.

### UMAP/PCA + HDBSCAN

UMAP cria uma projeção 3D mais fiel para exploração visual, mas pode ser caro em datasets grandes. O `fast_mode` troca UMAP por PCA para reduzir o custo. HDBSCAN encontra clusters por densidade sem exigir um número fixo de grupos.

### Cache em Memória

O `cache` global guarda `df`, embeddings, índices FAISS/BM25 e dados auxiliares por `job_id`. Isso simplifica o MVP e acelera buscas depois do upload, mas não é persistente. Em produção, uma evolução natural seria persistir os artefatos em disco, Redis, Postgres/pgvector, Qdrant, Milvus ou outro banco vetorial.

## Dependências Externas

| Serviço | Onde entra |
| --- | --- |
| OpenRouter | Geração de resposta, expansão de query e descrição de clusters |
| Tavily | Busca web em `/search_web/` |
| Hugging Face / SentenceTransformers | Download/carregamento dos modelos locais |
| spaCy | NER PT/EN para grafo de entidades |