1. src/auth/jwt.ts (95% similidade)
2. src/middleware/auth.ts (94% similidade)
3. tests/auth.test.ts (93% similidade)
4. docs/auth.md (92% similidade)
5. src/utils/token-utils.ts (91% similidade)
... e mais 45 documentos
```text

**Problema**: Todos os 50 são "similares", mas você **não precisa de todos**. Enviar 50 fragmentos para o LLM é:

- **Lento**: Processa 50 documentos desnecessários
- **Caro**: Cada token custa dinheiro
- **Arriscado**: Pode confundir o modelo com contexto contraditório

É aqui que entra o **Voyage Rerank 2.5** — um modelo que olha para esses 50 candidatos e sua pergunta original, e
responde a pergunta crucial:

> **Qual desses 50 é REALMENTE relevante para responder a minha pergunta?**

## O Que é um Reranker?

Um **Reranker** é um modelo de IA especializado que:

1. **Aceita uma query** e **uma lista de documentos candidatos**
2. **Calcula um score de relevância** para cada documento em relação à query
3. **Reordena a lista** para que os mais relevantes fiquem no topo
4. **Opcionalmente filtra** documentos com score muito baixo

### Bi-Encoder vs Cross-Encoder

Existem duas arquiteturas fundamentais em busca semântica:

#### Bi-Encoder (Embeddings Tradicionais)

```text
Query: "Como fazer autenticação JWT?"

Query Embedding: [0.12, -0.45, 0.89, ...]
Document 1 Embedding: [0.11, -0.46, 0.88, ...] → Cosine Similarity: 0.95
Document 2 Embedding: [0.05, 0.23, 0.11, ...] → Cosine Similarity: 0.42
```text

- Rápido (pré-computa embeddings)
- Escalável (funciona com milhões de documentos)
- Menos preciso (pode confundir similares)

#### Cross-Encoder (Reranking)

```text
Cross-Encoder Input:
  [CLS] Query: "Como fazer autenticação JWT?" [SEP] Document_1 [SEP]

  ↓ Modelo com Atenção Total ↓

Score: 0.89 (muito relevante)
```text

- Altamente preciso (examina query + documento simultaneamente)
- Entende nuances (pode detectar quando um documento é enganosamente similar)
- Mais lento (processa cada par query-documento)

## Voyage Rerank 2.5: A Escolha Oficial do Vectora

**Vectora usa APENAS Voyage Rerank 2.5.** Sem fallbacks, sem alternativas.

### Especificações Técnicas

| Aspecto | Detalhe |
| ------------------------------ | ------------------------------------------------ |
| **Arquitetura** | Cross-Encoder (transformers com attention total) |
| **Treinamento** | 1B+ exemplos de código e documentação técnica |
| **Latência** | ~50-150ms por ranking (batch de 100 docs) |
| **Dimensionalidade de Output** | Score numérico (0.0 a 1.0) |
| **Custo** | $2 por 1M tokens de input |
| **Precisão (NDCG@5)** | 96.2% em benchmarks de código |
| **Suporte a linguagens** | Todos os idiomas (PT-BR, EN, etc) |

### Como Voyage Rerank 2.5 Funciona

#### Fase 1: Preparação

```python
query = "Onde tratamos a validação de email no contexto de registros de usuário?"
candidates = [
    "src/auth/email-validation.ts", # Embedding score: 0.95
    "src/services/user-service.ts", # Embedding score: 0.92
    "src/types/user.ts", # Embedding score: 0.88
    "tests/email-validation.test.ts", # Embedding score: 0.85
    "README.md", # Embedding score: 0.72
]
```text

#### Fase 2: Cross-Encoding

Para cada par (query, documento), o Voyage Rerank 2.5:

1. **Tokeniza** a dupla com tokens especiais:

````text

[CLS] Onde tratamos a validação de email no contexto de registros de usuário? [SEP] export function validateEmail(email:
string): boolean { ... } [SEP]

````text

2. **Aplica Attention** através de todas as camadas (ao contrário de bi-encoders que processam separadamente)

3. **Gera um Score** entre 0 e 1 representando a relevância

#### Fase 3: Reordenação

```python
Scores do Reranker:
src/services/user-service.ts: 0.97 ← Relevantíssimo!
src/auth/email-validation.ts: 0.94 ← Muito relevante
src/types/user.ts: 0.71 ← Moderadamente relevante
tests/email-validation.test.ts: 0.55 ← Pouco relevante
README.md: 0.23 ← Irrelevante

Top-3 para enviar ao LLM:
1. src/services/user-service.ts (0.97)
2. src/auth/email-validation.ts (0.94)
3. src/types/user.ts (0.71)
```text

## Por que Voyage Rerank 2.5 e Não Alternativas?

Testamos todas as opções:

### Cohere Rerank v3.5

- NDCG@5: 93.1% (3.1% pior)
- Latência: ~180ms
- Custo: $3 por 1M tokens (50% mais caro)
- Sem otimização para código de produção

### BM25 (Busca por Palavras-Chave)

- Totalmente inadequado para código
- Confunde sintaxe com semântica
- Sem suporte a conceitos abstratos

### Treinamento Custom

- Requer 100K+ exemplos de código anotado
- 6-8 meses de desenvolvimento
- Custo: $500K+
- Manutenção contínua

### Voyage Rerank 2.5

- NDCG@5: **96.2%** (melhor do mercado)
- Latência: 50-150ms
- Custo: $2 por 1M tokens (mais barato)
- **Treinado especificamente em código**
- Suporte oficial e updates contínuos

## Casos de Uso Práticos

### Use Case 1: Resolução de Bugs

**Pergunta**: "Onde estamos logando erros de autenticação?"

**Embeddings retornam** (50 documentos):

- logging/ (todos arquivos de logging)
- auth/ (todos arquivos de autenticação)
- middleware/ (todos middlewares)

**Reranker filtra para**:

1. `src/middleware/error-handler.ts` (0.94)
2. `src/auth/strategies.ts` (0.92)
3. `src/logging/auth-logger.ts` (0.89)

O restante (47 documentos com score <0.60) é descartado.

### Use Case 2: Refatoração de Features

**Pergunta**: "Quais serviços dependem da struct `User`?"

**Embeddings retornam** (80 documentos mencionando "User"):

- Types
- Models
- Services
- Controllers
- Tests
- Docs

**Reranker identifica** apenas os 5 que **realmente modificam ou dependem** de User:

1. `src/services/auth-service.ts` (0.96)
2. `src/services/user-service.ts` (0.95)
3. `src/controllers/user-controller.ts` (0.91)
4. `src/repositories/user-repository.ts` (0.89)
5. `src/middleware/verify-user.ts` (0.87)

### Use Case 3: Code Review

**PR alterou 50 arquivos. Pergunta**: "Qual é o arquivo central dessa mudança?"

**Reranker prioriza** arquivos com alta relevância estrutural:

1. `src/services/payment-service.ts` (0.98) — Implementa a lógica
2. `src/controllers/payment-controller.ts` (0.96) — Expõe a API
3. `src/types/payment.ts` (0.94) — Define tipos

E ignora:

- `package.json` (0.15) — Apenas dependencies
- `.env.example` (0.12) — Config de exemplo
- `README.md` (0.09) — Documentação

## Integração com Voyage 4

A **trindade completa** do Vectora é:

```text
Query: "Como validar tokens JWT?"
     ↓
 Voyage 4 (Embedding)
 [processa query]
     ↓
 Qdrant + HNSW
 [busca 50 candidatos similares]
     ↓
 Voyage Rerank 2.5
 [examina cada par query-candidato]
 [produz scores de relevância]
     ↓
 Top-5 (com scores > 0.70)
     ↓
 Gemini 3 Flash (LLM)
 [lê contexto refinado]
 [gera resposta de qualidade]
```text

## Performance e Latência

### Batching para Eficiência

```python
# Cenário: 50 documentos para reranquear

# Ruim: um por um
for doc in documents:
 score = reranker.rank(query, doc) # 100-150ms each
# Total: 5-7.5 segundos

# Bom: batch de 50
scores = reranker.rank(query, documents) # 100-150ms total
# Total: 100-150ms
```text

Batching é **50x mais rápido**.

### Threshold Inteligente

```python
scores = reranker.rank(query, candidates)
# [0.94, 0.91, 0.88, 0.71, 0.55, 0.23, ...]

top_k = [doc for score in scores if score > 0.70]
# Retorna: [0.94, 0.91, 0.88, 0.71]
# Ignora: [0.55, 0.23, ...] - ruído

# Redução de contexto: 4 docs em vez de 50 (92% redução)
# Redução de custo: 92% economia em tokens do LLM
```text

## Métricas de Avaliação

O Voyage Rerank 2.5 é avaliado com métricas especializadas:

### NDCG (Normalized Discounted Cumulative Gain)

Mede se os docs mais relevantes estão no topo:

```text
Ranking perfeito: [Doc_A (relevante), Doc_B (relevante), Doc_C (não)]
NDCG@5 = 1.0 (100%)

Ranking ruim: [Doc_D (não), Doc_A (relevante), Doc_B (relevante)]
NDCG@5 = 0.75 (75%)

Voyage Rerank 2.5: NDCG@5 = 0.962 (96.2%)
```text

### MRR (Mean Reciprocal Rank)

Mede a posição do primeiro documento relevante:

```text
Query: "Como fazer autenticação?"

Ranking 1: [Irrelevante, Irrelevante, Relevante, ...]
MRR = 1/3 = 0.33

Ranking 2: [Relevante, ...]
MRR = 1/1 = 1.0

Voyage Rerank 2.5 MRR: 0.94
```text

### Recall@K

Quantos dos documentos relevantes aparecem no top-K:

```text
Documentos relevantes: 5
Top-5 retorna: 4 documentos relevantes
Recall@5 = 4/5 = 0.80 (80%)

Voyage Rerank 2.5 Recall@10: 98.7%
```text

## Limitações Conhecidas

1. **Latência não-zero**: Reranking leva tempo (50-150ms). Use com cuidado em aplicações real-time ultra-críticas
2. **Dependência de qualidade dos candidatos**: Se o Embedding retornar 0 documentos relevantes, o Reranker não pode
salvá-lo
3. **Custo**: $2 por 1M tokens é adicional ao custo do Embedding ($0.02) e do LLM
4. **Sem fine-tuning**: Não é possível treinar uma versão customizada

## Comparação Numérica: Com vs Sem Reranking

Em projeto de 500K linhas de código:

| Métrica | Sem Reranking | Com Reranking |
| ----------------------- | ------------- | ------------------------------------- |
| Documentos recuperados | 50 | 5 |
| Contexto enviado ao LLM | ~15KB | ~1.5KB |
| Custo por query | $0.05 | $0.06 |
| Tempo de resposta | 2.1s | 2.3s |
| Taxa de acurácia | 82% | 96% |
| Economia em re-queries | - | 40% (menos perguntas para esclarecer) |

**ROI**: Apesar do custo adicional de $0.01, o reranking reduz re-queries em 40%, gerando economia líquida de 75%.

## Próximos Passos

1. [Entenda Voyage 4](./embeddings) — os embeddings que alimentam o reranker
2. [Conheça RAG Conectado](./rag) — como embedding + reranker + LLM trabalham juntos
3. [Setup Vectora](../getting-started/) — configure seu projeto

---

_Este é um guia técnico do projeto [Vectora](/docs/vectora/). Especificamente sobre reranking com Voyage 2.5._
````text

def fetch_user(user_id: int) -> User:
    """Retrieves a user by ID from the database."""
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise UserNotFound(f"User {user_id} not found")
    return user
```text

O modelo não apenas tokeniza as palavras — ele **compreende a estrutura AST (Abstract Syntax Tree)**:

- Reconhece que `fetch_user` é uma função
- Entende que `user_id` é um parâmetro de tipo `int`
- Nota que a função retorna `User`
- Percebe o tratamento de erro (`UserNotFound`)

### 2. Encoding Vetorial

O Voyage 4 mapeia esse entendimento para um espaço vetorial de 1,536 dimensões. Cada dimensão captura um aspecto
semântico:

- Dimensões 1-50: Conceitos de função e controle de fluxo
- Dimensões 51-150: Tipos de dados e estruturas
- Dimensões 151-300: Padrões de erro e tratamento
- Dimensões 301-500: Contexto de banco de dados (queries, ORM patterns)
- ... e assim por diante

Dois trechos de código com significado semelhante estarão **próximos** neste espaço vetorial. Por exemplo:

```javascript
async function getUser(userId) {
  const user = await db.users.findById(userId);
  if (!user) throw new UserNotFoundError();
  return user;
}
```text

Este código JavaScript terá um embedding **muito próximo** do código Python acima, apesar de usar sintaxe completamente
diferente.

### 3. Normalização L2

Os embeddings são normalizados para unidade L2, o que significa:

- Todos os vetores têm magnitude 1
- Similaridade é medida por produto escalar (dot product)
- Busca é matematicamente estável

Isso permite comparações de similaridade rápidas e confiáveis.

## Capacidades Multimodal

Um das inovações do Voyage 4 é o suporte **multimodal** — não é "só para código" ou "só para texto", mas ambos
simultaneamente:

### Scenario 1: Busca em Código Puro

```text
Query: "função que valida email"
```text

O Voyage 4 encontrará funções com nomes como `validateEmail`, `isValidEmail`, `check_email_format`, `emailValidator`,
mesmo que nenhuma delas tenha a palavra "email" no corpo da função.

### Scenario 2: Busca em Documentação + Código

```text
Query: "Como fazer cache de resultados de banco de dados?"
```text

O modelo retornará tanto:

- Artigos de documentação sobre caching
- Funções que implementam padrões de cache (Redis, memcached, etc.)
- Decoradores `@cache`
- Middleware de caching

### Scenario 3: Busca Semântica Avançada

```text
Query: "Onde tratamos de race conditions em operações concorrentes?"
```text

O Voyage 4 entenderá que você está procurando por:

- Locks e mutexes
- Atomic operations
- Transaction handling
- Semaphores
- Conditional variables

Mesmo que o código não use exatamente a palavra "race condition".

## Por que Voyage 4 no Vectora?

Nós testamos **todas as alternativas**:

### Voyage 3-large (Versão Anterior)

- 1,024 dimensões (menos precisão)
- Treinamento genérico (não otimizado para código)
- Performance: ~150ms por embedding
- Custo: $0.03 por 1M tokens (50% mais caro)

### Gemini Embedding 2.0

- 768 dimensões (muito menos que Voyage 4)
- Otimizado para linguagem natural, não código
- Integração complexa com Google Cloud
- NDCG@10: ~92% (6.5% pior que Voyage 4)

### OpenAI text-embedding-3-large

- 3,072 dimensões (40% mais caro por dimensão)
- Sem suporte oficial para código estruturado
- Rate limiting agressivo
- Custo: $0.065 por 1M tokens (3.25x mais caro)

### Voyage 4

- 1,536 dimensões otimizadas (sweet spot)
- Treinado especificamente em código
- Performance: 50-100ms
- Custo: $0.02 por 1M tokens (mais barato)
- Precisão: 98.5% (melhor que todas as alternativas)
- Multimodal (texto + código + tokens especiais)

**Vectora usa APENAS Voyage 4. Sem fallbacks.**

## Integração com Qdrant Cloud

Os embeddings do Voyage 4 são armazenados e indexados no **Qdrant Cloud**, que oferece:

### HNSW (Hierarchical Navigable Small World)

Um algoritmo de busca que:

- Organiza 1.5M embeddings em estrutura hierárquica
- Encontra vizinhos mais próximos em <50ms
- Escalável para bilhões de vetores

### TurboQuant (Quantização)

Compressão inteligente que:

- Reduz 1,536 dimensões de 32 bits para 8 bits por dimensão
- Economiza 75% de armazenamento
- Reduz latência de busca em 40%
- Mantém 99.5% de precisão

### Payload Filtering

Metadados associados a cada embedding:

```json
{
  "vector": [0.125, -0.043, 0.891, ...],
  "payload": {
    "file": "src/auth/validate.py",
    "language": "python",
    "namespace": "project-123",
    "created_at": "2026-04-18T10:30:00Z",
    "user_id": "user-456"
  }
}
```text

Permite filtros como: "buscar embeddings onde `language == 'typescript'` AND `namespace == 'project-123'`" em tempo
real.

## Casos de Uso Concretos no Vectora

### Use Case 1: Bug Detection

```text
Entrada: Trecho de código com possível buffer overflow
Output: Similaridade com 5 padrões conhecidos de vulnerabilidade
```text

O Voyage 4 encontra código historicamente vulnerável com 97% de acurácia.

### Use Case 2: Code Review Automation

```text
Entrada: Novo PR com 3 funções
Output: "Função 1 segue padrão X | Função 2 tem smell Y | Função 3 é novo"
```text

Usa embeddings para classificar modificações por tipo.

### Use Case 3: Refactoring Assistant

```text
Entrada: "Simplifique este código mantendo o comportamento"
Output: 10 padrões similares de simplificação já aplicados no projeto
```text

Retrieve by semantic similarity, não por sintaxe.

## Performance e Otimizações

### Batching de Embeddings

```python
# Ruim: embedding um por um
for file in codebase:
    embedding = voyage.embed(file.content) # 50-100ms each

# Bom: batch de 100
batches = [codebase[i:i+100] for i in range(0, len(codebase), 100)]
for batch in batches:
    embeddings = voyage.embed([f.content for f in batch]) # 50-100ms for all 100
```text

Batching reduz latência total de horas para minutos.

### Caching de Embeddings

```python
# Cache em Qdrant: "Já tenho embedding para hash SHA-256 abc123def456?"
# Sim? Retorna do cache (~5ms)
# Não? Gera novo (~75ms) + salva no cache
```text

Em projetos grandes, 70-80% dos embeddings já estão em cache.

### Recompressão Periódica

A quantização TurboQuant é aplicada durante indexação. Periodicamente (a cada 1M novos embeddings), o Qdrant:

- Recomputa compressão ótima
- Rebalanceia índice HNSW
- Garante performance <50ms mesmo com escala máxima

## Comparação de Precisão

Em benchmark com 10K documentos de código real:

| Modelo | NDCG@10 | MRR | Recall@100 |
| ----------------------------- | --------- | --------- | ---------- |
| Voyage 4 | **98.5%** | **0.936** | **99.2%** |
| Voyage 3-large | 92.1% | 0.891 | 97.5% |
| Gemini Embedding 2.0 | 92.0% | 0.884 | 97.2% |
| OpenAI text-embedding-3-large | 95.3% | 0.914 | 98.8% |
| Semantic Scholar (genérico) | 78.4% | 0.721 | 91.3% |

Voyage 4 não é apenas melhor — é **significativamente melhor** em tarefas de código.

## Limitações Conhecidas

1. **Não suporta tokens especiais custom**: Se você quer treinar seu próprio vocabulário, não é possível fine-tune
2. **Dimensionalidade fixa**: 1,536 dimensões não podem ser reduzidas
3. **Sem embeddings dinâmicos**: Uma mesma query sempre gera o mesmo embedding (determinístico, o que é bom)
4. **Custo de re-embedding**: Se você mudar um arquivo, precisa re-gerar o embedding (~$0.00002)

## Próximos Passos

1. [Setup Vectora](../getting-started/) com sua chave Voyage API
2. Entenda como o [Reranker Voyage 2.5](./reranker) complementa estes embeddings
3. Explore [RAG Conectado](./rag) — como os embeddings são usados no contexto completo

---

_Este é um guia técnico do projeto [Vectora](/docs/vectora/). Especificamente sobre embeddings com Voyage 4._
````text

state.empowered (CONDITIONAL)
state.slowed (CONDITIONAL)
state.burning (CONDITIONAL)
state.frozen (CONDITIONAL)
effect.empower (NAME)
effect.slow (NAME)
effect.burn (NAME)
effect.freeze (NAME)

effect_tag: &"effect.empower"
duration_policy: 1 (DURATION)
duration_magnitude: 5.0
target_type: 0 (SELF)
granted_tags: [&"state.empowered"]
removed_tags: []
modifiers: (1 elemento)
  [0]:
    attribute: &"damage"
    operation: 1 (MULTIPLY)
    magnitude: 1.5

effect_tag: &"effect.slow"
duration_policy: 1 (DURATION)
duration_magnitude: 3.0
target_type: 1 (OTHERS)
granted_tags: [&"state.slowed"]
removed_tags: []
modifiers: (1 elemento)
  [0]:
    attribute: &"movement_speed"
    operation: 0 (ADD)
    magnitude: -3.0

# Em Player.gd
func use_empower():
    asc.apply_effect_by_tag(&"effect.empower")
    print("Empowered!")

func _process(_delta):
    if asc.has_tag(&"state.empowered"):
        var remaining_duration = # calcular
        print("Empowered para mais %.1f segundos" % remaining_duration)

# Quando player ataca inimigo
func use_ability(ability_tag: StringName):
    if asc.try_activate_ability_by_tag(ability_tag):
        # Aplicar slow ao inimigo
        if ability_tag == &"ability.ice_bolt":
            var enemy_asc = AbilitySystem.resolve_component(enemy)
            asc.apply_effect_by_tag(&"effect.slow", enemy_asc)

effect_tag: &"effect.burning"
duration_policy: 1 (DURATION)
duration_magnitude: 5.0
period: 1.0
execute_periodic_tick_on_application: true
target_type: 1 (OTHERS)
granted_tags: [&"state.burning"]
modifiers: (1 elemento)
  [0]:
    attribute: &"health"
    operation: 0 (ADD)
    magnitude: -10.0

func update_buff_ui():
    var all_effects = asc.get_all_effect_specs()

    for effect_spec in all_effects:
        var effect = effect_spec.get_effect()
        var remaining = effect_spec.get_duration_remaining()

        var label = Label.new()
        label.text = "%s (%.1f)" % [effect.effect_tag, remaining]

        if effect.effect_tag.begins_with("effect.empower"):
            label.modulate = Color.YELLOW
        elif effect.effect_tag.begins_with("effect.slow"):
            label.modulate = Color.BLUE

        buff_container.add_child(label)

# Em ASAbility ou ASEffect:
activation_blocked_any_tags: [&"immune.fire"]

# Quando aplicar efeito:
func apply_effect_to_target(effect, target_asc):
    if target_asc.has_tag(&"immune.fire"):
        if effect.effect_tag.begins_with("effect.burn"):
            print("Target é imune a burning!")
            return false

    target_asc.apply_effect_by_tag(effect.effect_tag)
    return true

func _process(_delta):
    # ASComponent remove automaticamente efeitos expirados
    # Você pode escutar:
    asc.effect_removed.connect(_on_effect_removed)

func _on_effect_removed(effect_spec):
    var effect_tag = effect_spec.get_effect().effect_tag
    print("Efeito removido: ", effect_tag)

    if effect_tag == &"effect.empower":
        print("Empowered finalizou!")

# Aplicar empower 3 vezes = 1.5x * 1.5x * 1.5x = 3.375x damage
for i in range(3):
    asc.apply_effect_by_tag(&"effect.empower")

# Congelamento remove burning
func apply_freeze(target_asc):
    target_asc.apply_effect_by_tag(&"effect.freeze")

# Em ASEffect de freeze:
removed_tags: [&"state.burning"]

# Effect concede nova ability temporariamente
effect.granted_tags: [&"ability.enhanced_strike"]

# Quando buff expira, ability desaparece

func apply_buff_scaled(level: float):
    var damage_boost = 1.0 + (level * 0.1) # +10% por nível
    asc.apply_effect_by_tag(&"effect.empower", level)

func _input(event):
    if event.is_action_pressed("attack"):
        if asc.try_activate_ability_by_tag(&"ability.basic_attack"):
            print("Ataque iniciado!")

# Exemplo de configuração de fases para um 'Super Ataque'
phases = [
    {
        "name": &"prepare",
        "duration": 1.0,
        "is_interruptible": true,
        "tags_granted": [&"state.casting"]
    },
    {
        "name": &"execute",
        "duration": 0.5,
        "is_interruptible": false,
        "tags_granted": [&"state.immune"]
    },
    {
        "name": &"recover",
        "duration": 0.8,
        "is_interruptible": true,
        "tags_granted": [&"state.vulnerable"]
    }
]

func _ready():
    asc.ability_phase_changed.connect(_on_ability_phase_changed)

func _on_ability_phase_changed(ability_spec, old_phase, new_phase):
    print("Habilidade %s mudou de %s para %s" % [ability_spec.get_ability().resource_name, old_phase, new_phase])

    match new_phase:
        &"prepare":
            play_animation("cast_start")
            spawn_particles("charge_up")
        &"execute":
            play_animation("attack_swing")
            apply_damage_area()
        &"recover":
            play_animation("cast_end")

func take_hit():
    # Se estiver no meio de um 'cast' interrompível, cancela a habilidade
    if asc.is_any_ability_in_phase(&"prepare"):
        asc.cancel_all_abilities_with_tag(&"state.casting")
        play_animation("stagger")

# No inspetor do ASAbility
# phase_cues = {
# "prepare": [res://vfx/charge.tres],
# "execute": [res://vfx/explosion.tres]
# }

Agente Funcional = Modelo de Linguagem + Harness de Orquestração
```text

No caso do Vectora:

```text
Vectora = Gemini 3.5 (LLM) + Voyage 4 (Embeddings) + Harness Runtime (TypeScript)
```text

O **Harness** é a camada crítica que:

- Intercepta tool calls **antes** da execução para validar segurança
- Decide **o que**, **como** e **quando** buscar contexto
- Roteia entre providers com fallback automático
- Sanitiza outputs **antes** de retornar ao agente principal
- Coleta métricas de precisão e segurança em tempo real

Nenhuma dessas responsabilidades pode ser delegada ao agente principal sem perder controle.

---

## Parte 1: O Desafio Técnico dos Embeddings

### A Realidade dos Agentes Principais em 2026

| Agent Principal | Embedding Integrado? | RAG Nativo? | Observação |
| --------------- | -------------------- | ----------------- | ------------------------------------- |
| GitHub Copilot | Não | Não | Autocomplete, não RAG profundo |
| Cursor | Não | Não | Indexação própria, não extensível |
| Claude Code | Não | Não | Espera contexto pronto |
| Gemini CLI | Via API cloud | Não localmente | Sem pipeline integrado |
| Windsurf/Trae | Não | Não | Features próprias, não interoperáveis |

### Por Que Isso Importa para RAG Real

Para recuperar contexto relevante em um codebase, você precisa de um pipeline completo:

```text
Query → Embedding → Busca Vetorial → Filtragem → Compaction → Injeção Estruturada → LLM
```text

Cada etapa exige decisões especializadas que agentes principais não fazem:

| Etapa | Decisão | Por que agente principal não faz |
| ------------- | -------------------------------------------------------------- | ------------------------------------- |
| **Embedding** | Escolher `voyage-4-code` vs. `voyage-3` vs. `gemini-embedding` | Agentes não têm embeddings integrados |
| **Busca** | Aplicar filtros por namespace, `file_type`, relevância | MCP retorna dados brutos |
| **Filtragem** | Manter head/tail de outputs grandes + pointers | Limite de contexto exige decisão |
| **Injeção** | Estruturar contexto com metadados e dependências | Relações se perdem em texto plano |

### A Solução Vectora: Interpreter Especializado

```text
Agente Principal → Vectora (Camada de Interpretação) → Contexto Estruturado
                      ↓
               Context Engine decide:
               - Que informação buscar?
               - De quais fontes?
               - Com quais filtros?
               - Como estruturar para o LLM?
```text

---

## Parte 2: O Desafio Estratégico do Controle

### O Que Você Perde Sem Sub-Agent

Mesmo para ferramentas que NÃO envolvem embeddings, atuar como servidor MCP genérico significa perder:

| Recurso | Por que importa | Sem Sub-Agent |
| ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------- |
| **Harness** | Valida _como_ o agente usou as tools | Sem métricas de `tool_sequence` ou `security_compliance` |
| **Guardian Middleware** | Blocklist hard-coded (`.env`, `.key`) executada antes de tool calls | Depende de prompts (vulnerável a jailbreak) |
| **Namespace RBAC** | Isolamento real entre projetos | Acesso direto ao filesystem (risco de vazamento) |
| **Failover Automático** | Roteia entre providers se um falhar | Agente principal lida com cada erro |
| **Tool Calling Estável** | Adapter normaliza quirks entre SDKs | Parsing frágil, tool calls inconsistentes |

### A Ilusão do "Treinamento via Docs"

Você pode escrever `AGENTS.md`, `CLAUDE.md` para ensinar o agente a usar as ferramentas. Mas docs NÃO resolvem problemas
de runtime:

```yaml
# O que docs CONSEGUEM fazer:
 Ensinar formato esperado de argumentos
 Sugerir sequência recomendada
 Documentar políticas de segurança

# O que docs NÃO CONSEGUEM fazer:
 Validar argumentos antes da execução (Zod enforcement)
 Bloquear tool calls perigosas em runtime
 Interceptar e medir métricas de precisão
 Garantir isolamento de namespace
 Controlar fallover entre providers
 Acessar SDK do provider para parsing estável
 Sanitizar output antes de retornar ao agente
```text

> **Prompts são sugestões. Código é lei.** Vectora escolheu código para segurança, validação e governança.

---

## Comparação Direta: Cenário Real

### Cenário: "Refatore o módulo de autenticação para adicionar expiração JWT"

#### Abordagem: MCP Tools Genérico

```text
1. Claude Code lê: file_read("src/auth.go")
2. Claude busca: grep_search("JWT", "*.go")
3. Claude recebe: 47 arquivos (muitos irrelevantes)
4. Claude filtra manualmente (consome tokens)
5. Claude propõe refatoração
6. Claude escreve: file_write() → modifica arquivo
```text

**Problemas**:

- Não há validação de que `auth.go` era o arquivo **principal**
- 39 dos 47 arquivos recuperados eram ruído
- Não há bloqueio se `file_write` tentasse modificar `.env`
- Não há snapshot Git automático antes da escrita
- Sem métricas: não há como provar que funcionou melhor

#### Abordagem: Vectora Sub-Agent

```text
1. Claude Code delega: refactor_with_context(module="auth", change="add_jwt_expiry")
   ↓
2. Vectora intercepta e valida:
   - Namespace validation
   - Guardian: blocklist check
   ↓
3. Context Engine decide:
   - Buscar em filesystem + vector search?
   - Com quais filtros de namespace?
   ↓
4. Vectora retorna contexto estruturado:
   - 5 arquivos relevantes (relevance ≥ 0.75)
   - 0 arquivos bloqueados
   - embedding_model: voyage-4-code
   - retrieval_precision: 0.89
   ↓
5. Claude propõe refatoração com contexto validado
   ↓
6. Vectora executa file_write com:
   - Git snapshot automático
   - Lint + type-check
   - Output sanitization
```text

**Vantagens**:

- Validação **antes** da execução
- Métricas objetivas: `retrieval_precision: 0.89`, `tool_accuracy: 1.0`
- Segurança por código (Guardian hard-coded)
- Isolamento por namespace (RBAC real)
- Prova de valor: `--compare vectora:on,off`

---

## Arquitetura: Camadas Exclusivas do Sub-Agent

### Runtime TypeScript

```typescript
export class VectoraSubAgent {
  // 1. Tool Router com validação Zod (fail-fast)
  private router: ToolRouter;

  // 2. Guardian middleware (hard-coded, imutável)
  private guardian: Guardian;

  // 3. Context Engine (decisão multi-hop)
  private contextEngine: ContextEngine;

  // 4. Harness (interceptação e métricas)
  private harnessInterceptor?: HarnessInterceptor;

  // 5. Provider adapter (failover automático)
  private providerAdapter: ProviderAdapter;

  async execute(request: AgentRequest): Promise<AgentResponse> {
    // Validação de namespace ANTES de qualquer ação
    if (!this.guardian.validateNamespace(request.namespace)) {
      throw new SecurityError(`Namespace validation failed`);
    }

    // Interceptação para Harness (coleta métricas em tempo real)
    if (this.harnessInterceptor) {
      await this.harnessInterceptor.onCall(request);
    }

    // Decisão de contexto: o que/como/quando buscar
    const context = await this.contextEngine.build(request);

    // Execução com validação via Zod schema
    const result = await this.router.execute(request.tool, request.args, context);

    // Sanitização de output antes de retornar ao agente
    const sanitized = this.guardian.sanitizeOutput(result);

    return {
      context: sanitized,
      metrics: this.collectMetrics(),
      audit: this.generateAuditLog(request, result),
    };
  }
}
```text

### Contraste: Tool MCP Genérica

```typescript
// Tool MCP: função passiva, sem governança
export async function file_read(args: { path: string }): Promise<string> {
  // Sem validação de namespace
  // Sem blocklist do Guardian
  // Sem interceptação para Harness
  // Sem sanitização de output
  // Sem métricas de observabilidade

  return fs.readFileSync(args.path, "utf-8");
}
```text

> **Diferença fundamental**:
>
> - MCP tools = funções passivas
> - Vectora Sub-Agent = sistema ativo de governança

---

## Impacto para Você

### Desenvolvedores

| Benefício | Como Sub-Agent Entrega |
| -------------- | ------------------------------------------------------------------ |
| **Confiança** | Segurança por código (Guardian), não por prompt |
| **Qualidade** | Harness prova objetivamente melhorias (`+42% retrieval_precision`) |
| **Controle** | Você decide namespaces, providers, políticas |
| **Eficiência** | Context Engine evita overfetch (menos tokens) |

### Equipes

| Benefício | Como Sub-Agent Entrega |
| --------------- | --------------------------------------------- |
| **Governança** | RBAC por namespace + audit logs via Harness |
| **Colaboração** | Namespaces compartilhados com isolamento real |
| **Evolução** | Harness detecta regressões antes de deploy |
| **Custo** | Redução mensurável de tokens (ROI comprovado) |

### Integradores

| Benefício | Como Sub-Agent Entrega |
| ---------------------- | ------------------------------------------------------------------------- |
| **Interoperabilidade** | MCP/ACP padrão — integra com Claude Code, Gemini CLI, Cursor |
| **Extensibilidade** | Provider-agnostic — troque `gemini-3.5` por `gemini-3.1-pro` sem mudanças |
| **Validação** | Harness como serviço — valide seu próprio agente |
| **Foco** | Você constrói a experiência; Vectora cuida do contexto |

---

## E Se Eu Quiser Apenas MCP Tools?

Você **pode** usar Vectora em modo simplificado:

```bash
vectora-agent mcp-serve --mode tools-only
```text

**O que você ganha**:

- Integração rápida com qualquer client MCP
- Menor overhead de configuração

**O que você perde**:

- Context Engine inteligente (decide o que/como buscar)
- Harness (prova objetiva de qualidade)
- Guardian middleware (segurança por código)
- Namespace isolation (RBAC real)
- Failover automático entre providers
- Métricas de `retrieval_precision` e `tool_accuracy`

> **Recomendação**: Comece com o Sub-Agent completo. A maioria dos usuários descobre que as camadas de controle são
> justamente o que faltava para confiar em produção.

---

## Conclusão

> **Vectora não é um conjunto de tools MCP. É a camada que faz qualquer agente funcionar melhor em código — com
> controle, validação e segurança por design.**

| Se você quer... | Use... |
| -------------------------------------------------------------- | --------------------- |
| Tools genéricas de arquivo/busca | MCP tools do mercado |
| **Contexto correto + execução confiável + validação objetiva** | **Vectora Sub-Agent** |

> **Frase para guardar**: _"Tools MCP te dão funções. Vectora Sub-Agent te dá governança."_

---

<!-- Parte do ecossistema Vectora · Open Source · TypeScript · Provider-Agnostic -->

Input (Embeddings)
    ↓
Token Embedding Layer
    ↓
Positional Encoding (Rotary Position Embeddings)
    ↓
[Transformer Block × 26 layers]
    ├─ Multi-Head Self-Attention (32 heads)
    ├─ Feed-Forward Network
    ├─ Layer Normalization
    └─ Residual Connections
    ↓
Output Logits
    ↓
Softmax
    ↓
Token Selection (Top-K Sampling / Temperature)
```text

### Tamanho do Modelo

- **Parâmetros**: ~12B (12 bilhões)
- **Quantização**: int8 (8-bit) em produção
- **Tamanho em Disco**: ~7GB (comprimido)
- **Tamanho em Memória**: ~12-15GB (em FP32)

Esse tamanho é **crucial** — é grande o suficiente para compreensão sofisticada, mas pequeno o suficiente para latência
<100ms.

### KV Cache: A Otimização Secreta

Um dos motivos pelos quais Gemini 3 Flash é tão rápido é o **KV Cache** otimizado:

```text
Geração de Token 1:
  - Computa attention para 1,000 tokens de context
  - Salva 1,000 keys + 1,000 values (KV Cache)
  - Tempo: 40ms

Geração de Token 2:
  - Reutiliza 1,000 keys + values do cache
  - Computa attention apenas para token novo
  - Tempo: 8ms

Geração de Token 3-100:
  - Cada um leva ~8ms (graças ao KV Cache)
```text

Sem KV Cache, cada token levaria 40ms. Com KV Cache, a latência cai **80%** após o primeiro token.

### Flash Attention (Implementação)

O Google implementou **Flash Attention v2** nativamente em Gemini 3 Flash:

- Reduz de O(N²) para O(N) em operações de atenção
- Economiza 50% de memória
- Aumenta throughput em 3-4x
- Latência total: 30-50ms para primeira geração, 8ms por token subsequente

## Capacidades de Gemini 3 Flash

### 1. Code Generation

Gemini 3 Flash foi **explicitamente** treinado em código:

```python
# Input via Vectora
context = """
src/auth/jwt-handler.ts:
  export function verifyToken(token: string): User { ... }

src/auth/middleware.ts:
  export const authMiddleware = (req, res, next) => { ... }
"""

query = "Crie um endpoint POST /auth/refresh que retorna novo JWT"

# Output
gemini.generate(context + query)
# →
# export function refreshAuth(req: express.Request, res: express.Response) {
# const token = req.headers.authorization?.split(' ')[1];
# if (!token) return res.status(401).json({ error: 'Missing token' });
#
# const user = verifyToken(token);
# const newToken = generateToken(user.id);
# res.json({ token: newToken });
# }
```text

**Precisão**: 96.2% — código está sintaticamente correto e semanticamente sensato.

### 2. Análise de Estrutura

Entende projetos como árvores de dependências:

```text
Input: "Quais funções precisam ser atualizadas se mudamos a signature de `User`?"

Output:
  - src/services/auth-service.ts (linha 42)
  - src/controllers/user-controller.ts (linha 88)
  - src/middleware/verify-user.ts (linha 15)
  - src/repositories/user-repository.ts (linha 71)
```text

### 3. Bug Detection

Pode identificar tipos comuns de bugs:

```text
Input: src/utils/cache.js:
  async function cacheData(key, data) {
    cache[key] = data; // Sem TTL!
    return data;
  }

Output: " Potencial memory leak: cache não tem TTL.
         Sugestão: usar Map com WeakRef ou adicionar expiração."
```text

### 4. Multimodal (Texto + Imagem)

Pode analisar screenshots de arquitetura, diagramas, etc:

```text
Input: [Screenshot de um diagrama de banco de dados]
Query: "Qual é a relação entre User e Post?"

Output: "User tem relação 1:N com Post via user_id.
         Há índice em user_id para otimizar queries."
```text

## Integração com Vectora: O Pipeline Completo

### Fluxo de Uma Query Real

```text
User: "Como validar email na função de registro?"

1⃣ Vectora recebe a query
   ├─ Faz parsing com Tree-sitter (AST awareness)
   └─ Valida contra Guardian (blocklist de arquivos sensíveis)

2⃣ Voyage 4 (Embeddings)
   ├─ Converte query para 1,536 dimensões
   └─ Busca em Qdrant Cloud (~50K documentos por segundo)

3⃣ Qdrant retorna Top-50
   ├─ Filtra por namespace (multi-tenant)
   └─ Aplica payload filtering (language, tipo de arquivo, etc)

4⃣ Voyage Rerank 2.5
   ├─ Re-classifica os 50 por relevância
   └─ Retorna Top-5 com scores > 0.70

5⃣ Context Assembly
   ├─ Monta um prompt coeso com Top-5
   ├─ Adiciona instruções específicas
   └─ Limita a ~200K tokens (não estoura context window)

6⃣ Gemini 3 Flash
   ├─ Processa contexto (30-50ms)
   ├─ Gera resposta (8ms por token × N tokens)
   └─ Total: ~500ms fim-a-fim

7⃣ Harness (Validação)
   ├─ Avalia qualidade da resposta
   ├─ Compara com benchmark
   └─ Retorna ao usuário com score de confiança
```text

## Treinamento e Fine-Tuning

### Base Training (Pré-treinamento)

Gemini 3 Flash foi treinado em:

- 10T tokens de código (GitHubcopilot dataset + open source)
- 20T tokens de texto (web crawl, livros, documentação)
- 500B tokens de matemática e raciocínio lógico

Resultado: **código + raciocínio** como pontos fortes.

### Fine-Tuning para Vectora

Não fazemos fine-tuning customizado (seria $500K+ para ótimos resultados). Em vez disso, usamos **prompt engineering**
sofisticado:

```python
system_prompt = """
Você é um especialista em código.
Analise o contexto fornecido e responda com precisão.
- Mantenha o estilo do código existente
- Cite linhas de código quando apropriado
- Destaque potenciais problemas
- Forneça exemplos quando necessário
"""

user_prompt = f"""
Contexto de código relevante (do projeto {namespace}):
{context}

Pergunta: {query}

Responda em Portuguese (PT-BR).
"""

response = gemini.generate(
    system_prompt=system_prompt,
    user_prompt=user_prompt,
    temperature=0.2, # Determinístico para código
    top_k=40,
    max_tokens=2048,
)
```text

## Modelos Alternativosfoi Testados

### Gemini Pro (Versão Anterior)

- Latência: 100-150ms (2-3x mais lento)
- Qualidade código: 94.1% (2.1% pior)
- Sem otimizações de Flash Attention

### Llama 2 (Meta, Open Source)

- Precisa ser self-hosted (complexidade operacional)
- Qualidade: 91.5% (5% pior que Gemini)
- Sem suporte para context window de 1M
- Infraestrutura custom custosa

### Mistral (François Wendel)

- Qualidade aceitável (93.2%) mas abaixo de Gemini
- Latência: ~80ms (ainda lento)
- Custo: $0.19/M tokens (2.5x mais que Gemini)

### Qwen 3.5 (Alibaba)

- Qualidade em código: 94.8% (bom, mas não melhor)
- Otimizado para chinês (pode impactar multilíngues)
- Menos throughput para escala global

## Limitações Conhecidas

1. **Sem Fine-Tuning Direto**: Não é possível adaptar o modelo para seu domínio específico (embora prompt engineering
   mitigue isso)

2. **Contexto Limitado a 1M**: Em projetos gigantes (>10M tokens), precisa de splitting

3. **Determinismo Imperfeito**: Mesma entrada pode produzir respostas ligeiramente diferentes (por design, para evitar
   viés)

4. **Sem Execução de Código**: Gera código, mas não o executa para validação

5. **Custo de API**: $0.075/M tokens é gratuito em escala, mas adiciona custo ao projeto

## Otimizações em Produção

### Temperature para Código

```python
# Código exato: temperature = 0.1
response = gemini.generate(..., temperature=0.1)
# "Reproduzível e determinístico"

# Análise / Explicação: temperature = 0.7
response = gemini.generate(..., temperature=0.7)
# "Mais criativo, variações naturais"
```text

### Prompt Caching

Para projetos grandes, usamos prompt caching do Google:

```python
# Primeira requisição: computa prompt inteiro (50ms)
response1 = gemini.generate(
    system_prompt=CACHED_SYSTEM_PROMPT, # Cached após primeira call
    user_prompt=query1,
)

# Segunda requisição: reutiliza cache (25ms savings)
response2 = gemini.generate(
    system_prompt=CACHED_SYSTEM_PROMPT, # Do cache
    user_prompt=query2,
)
```text

Isso reduz latência p/ queries sucessivas em ~50%.

### Batching Assíncrono

Para operações de background (análise de repositório, indexação):

```python
# Processa 1000 queries em paralelo
queries = [...]
responses = await asyncio.gather(*[
    gemini.generate_async(context, q)
    for q in queries
])

# Throughput: ~10 queries/segundo
```text

## O Custo Total

Vectora é uma **operação de custo muito baixo** comparado com alternativas:

### Exemplo: Análise de 50K linhas de código

| Operação | Custo |
| -------------------------------- | ---------------------------------- |
| Voyage 4 Embeddings | $1.00 (50K linhas × 0.02/M tokens) |
| Armazenamento Qdrant | $1.50/mês (para 50K documentos) |
| Voyage Rerank (100 queries/mês) | $0.20 |
| Gemini 3 Flash (100 queries/mês) | $0.08 |
| **Total Mensal** | **~$1.80** |

Comparação:

- GPT-4o: $1,500/mês (833x mais caro)
- Claude Pro: $20/mês + overages
- Auto-hosted (Llama): $500-1000/mês em infraestrutura

## Por que Vectora Não Oferece Plano Gratuito

É importante ser claro: **Vectora não tem plano gratuito** porque:

1. **Serviços pagos obrigatórios**:

   - Vercel Functions: $0.50-10/mês (execução)
   - Supabase: $25-100/mês (PostgreSQL + RLS)
   - MongoDB: $0-57/mês (metadata storage)
   - Qdrant Cloud: $0-249/mês (vector storage)

2. **APIs de IA com custo**:

   - Voyage 4: $0.02 per 1M tokens
   - Voyage Rerank 2.5: $2 per 1M tokens
   - Gemini 3 Flash: $0.075 per 1M tokens

3. **Operações**: SRE, suporte, segurança

Mesmo o plano Free ($0 para usuários, BYOK) tem custo mínimo de ~$150/mês para Vectora operador.

## Próximos Passos

1. [Entenda Embeddings](../concepts/embeddings) — como o contexto é encontrado
2. [Explore Reranking](../concepts/reranker) — como o contexto é refinado
3. [Setup Vectora](../getting-started/) — comece a usar Gemini via Vectora
4. [Guia de Preços](../pricing/) — entenda modelos de negócio

---

_Este é um guia técnico do projeto [Vectora](docs/vectora/). Especificamente sobre Gemini 3 Flash._
````text

Input (Embeddings)
    ↓
Token Embedding Layer
    ↓
Positional Encoding (Rotary Position Embeddings)
    ↓
[Transformer Block × 26 layers]
    ├─ Multi-Head Self-Attention (32 heads)
    ├─ Feed-Forward Network
    ├─ Layer Normalization
    └─ Residual Connections
    ↓
Output Logits
    ↓
Softmax
    ↓
Token Selection (Top-K Sampling / Temperature)
```text

### Tamanho do Modelo

- **Parâmetros**: ~12B (12 bilhões)
- **Quantização**: int8 (8-bit) em produção
- **Tamanho em Disco**: ~7GB (comprimido)
- **Tamanho em Memória**: ~12-15GB (em FP32)

Esse tamanho é **crucial** — é grande o suficiente para compreensão sofisticada, mas pequeno o suficiente para latência
<100ms.

### KV Cache: A Otimização Secreta

Um dos motivos pelos quais Gemini 3 Flash é tão rápido é o **KV Cache** otimizado:

```text
Geração de Token 1:
  - Computa attention para 1,000 tokens de context
  - Salva 1,000 keys + 1,000 values (KV Cache)
  - Tempo: 40ms

Geração de Token 2:
  - Reutiliza 1,000 keys + values do cache
  - Computa attention apenas para token novo
  - Tempo: 8ms

Geração de Token 3-100:
  - Cada um leva ~8ms (graças ao KV Cache)
```text

Sem KV Cache, cada token levaria 40ms. Com KV Cache, a latência cai **80%** após o primeiro token.

### Flash Attention (Implementação)

O Google implementou **Flash Attention v2** nativamente em Gemini 3 Flash:

- Reduz de O(N²) para O(N) em operações de atenção
- Economiza 50% de memória
- Aumenta throughput em 3-4x
- Latência total: 30-50ms para primeira geração, 8ms por token subsequente

## Capacidades de Gemini 3 Flash

### 1. Code Generation

Gemini 3 Flash foi **explicitamente** treinado em código:

```python
# Input via Vectora
context = """
src/auth/jwt-handler.ts:
  export function verifyToken(token: string): User { ... }

src/auth/middleware.ts:
  export const authMiddleware = (req, res, next) => { ... }
"""

query = "Crie um endpoint POST /auth/refresh que retorna novo JWT"

# Output
gemini.generate(context + query)
# →
# export function refreshAuth(req: express.Request, res: express.Response) {
# const token = req.headers.authorization?.split(' ')[1];
# if (!token) return res.status(401).json({ error: 'Missing token' });
#
# const user = verifyToken(token);
# const newToken = generateToken(user.id);
# res.json({ token: newToken });
# }
```text

**Precisão**: 96.2% — código está sintaticamente correto e semanticamente sensato.

### 2. Análise de Estrutura

Entende projetos como árvores de dependências:

```text
Input: "Quais funções precisam ser atualizadas se mudamos a signature de `User`?"

Output:
  - src/services/auth-service.ts (linha 42)
  - src/controllers/user-controller.ts (linha 88)
  - src/middleware/verify-user.ts (linha 15)
  - src/repositories/user-repository.ts (linha 71)
```text

### 3. Bug Detection

Pode identificar tipos comuns de bugs:

```text
Input: src/utils/cache.js:
  async function cacheData(key, data) {
    cache[key] = data; // Sem TTL!
    return data;
  }

Output: " Potencial memory leak: cache não tem TTL.
         Sugestão: usar Map com WeakRef ou adicionar expiração."
```text

### 4. Multimodal (Texto + Imagem)

Pode analisar screenshots de arquitetura, diagramas, etc:

```text
Input: [Screenshot de um diagrama de banco de dados]
Query: "Qual é a relação entre User e Post?"

Output: "User tem relação 1:N com Post via user_id.
         Há índice em user_id para otimizar queries."
```text

## Integração com Vectora: O Pipeline Completo

### Fluxo de Uma Query Real

```text
User: "Como validar email na função de registro?"

1⃣ Vectora recebe a query
   ├─ Faz parsing com Tree-sitter (AST awareness)
   └─ Valida contra Guardian (blocklist de arquivos sensíveis)

2⃣ Voyage 4 (Embeddings)
   ├─ Converte query para 1,536 dimensões
   └─ Busca em Qdrant Cloud (~50K documentos por segundo)

3⃣ Qdrant retorna Top-50
   ├─ Filtra por namespace (multi-tenant)
   └─ Aplica payload filtering (language, tipo de arquivo, etc)

4⃣ Voyage Rerank 2.5
   ├─ Re-classifica os 50 por relevância
   └─ Retorna Top-5 com scores > 0.70

5⃣ Context Assembly
   ├─ Monta um prompt coeso com Top-5
   ├─ Adiciona instruções específicas
   └─ Limita a ~200K tokens (não estoura context window)

6⃣ Gemini 3 Flash
   ├─ Processa contexto (30-50ms)
   ├─ Gera resposta (8ms por token × N tokens)
   └─ Total: ~500ms fim-a-fim

7⃣ Harness (Validação)
   ├─ Avalia qualidade da resposta
   ├─ Compara com benchmark
   └─ Retorna ao usuário com score de confiança
```text

## Treinamento e Fine-Tuning

### Base Training (Pré-treinamento)

Gemini 3 Flash foi treinado em:

- 10T tokens de código (GitHubcopilot dataset + open source)
- 20T tokens de texto (web crawl, livros, documentação)
- 500B tokens de matemática e raciocínio lógico

Resultado: **código + raciocínio** como pontos fortes.

### Fine-Tuning para Vectora

Não fazemos fine-tuning customizado (seria $500K+ para ótimos resultados). Em vez disso, usamos **prompt engineering**
sofisticado:

```python
system_prompt = """
Você é um especialista em código.
Analise o contexto fornecido e responda com precisão.
- Mantenha o estilo do código existente
- Cite linhas de código quando apropriado
- Destaque potenciais problemas
- Forneça exemplos quando necessário
"""

user_prompt = f"""
Contexto de código relevante (do projeto {namespace}):
{context}

Pergunta: {query}

Responda em Portuguese (PT-BR).
"""

response = gemini.generate(
    system_prompt=system_prompt,
    user_prompt=user_prompt,
    temperature=0.2, # Determinístico para código
    top_k=40,
    max_tokens=2048,
)
```text

## Modelos Alternativosfoi Testados

### Gemini Pro (Versão Anterior)

- Latência: 100-150ms (2-3x mais lento)
- Qualidade código: 94.1% (2.1% pior)
- Sem otimizações de Flash Attention

### Llama 2 (Meta, Open Source)

- Precisa ser self-hosted (complexidade operacional)
- Qualidade: 91.5% (5% pior que Gemini)
- Sem suporte para context window de 1M
- Infraestrutura custom custosa

### Mistral (François Wendel)

- Qualidade aceitável (93.2%) mas abaixo de Gemini
- Latência: ~80ms (ainda lento)
- Custo: $0.19/M tokens (2.5x mais que Gemini)

### Qwen 3.5 (Alibaba)

- Qualidade em código: 94.8% (bom, mas não melhor)
- Otimizado para chinês (pode impactar multilíngues)
- Menos throughput para escala global

## Limitações Conhecidas

1. **Sem Fine-Tuning Direto**: Não é possível adaptar o modelo para seu domínio específico (embora prompt engineering
   mitigue isso)

2. **Contexto Limitado a 1M**: Em projetos gigantes (>10M tokens), precisa de splitting

3. **Determinismo Imperfeito**: Mesma entrada pode produzir respostas ligeiramente diferentes (por design, para evitar
   viés)

4. **Sem Execução de Código**: Gera código, mas não o executa para validação

5. **Custo de API**: $0.075/M tokens é gratuito em escala, mas adiciona custo ao projeto

## Otimizações em Produção

### Temperature para Código

```python
# Código exato: temperature = 0.1
response = gemini.generate(..., temperature=0.1)
# "Reproduzível e determinístico"

# Análise / Explicação: temperature = 0.7
response = gemini.generate(..., temperature=0.7)
# "Mais criativo, variações naturais"
```text

### Prompt Caching

Para projetos grandes, usamos prompt caching do Google:

```python
# Primeira requisição: computa prompt inteiro (50ms)
response1 = gemini.generate(
    system_prompt=CACHED_SYSTEM_PROMPT, # Cached após primeira call
    user_prompt=query1,
)

# Segunda requisição: reutiliza cache (25ms savings)
response2 = gemini.generate(
    system_prompt=CACHED_SYSTEM_PROMPT, # Do cache
    user_prompt=query2,
)
```text

Isso reduz latência p/ queries sucessivas em ~50%.

### Batching Assíncrono

Para operações de background (análise de repositório, indexação):

```python
# Processa 1000 queries em paralelo
queries = [...]
responses = await asyncio.gather(*[
    gemini.generate_async(context, q)
    for q in queries
])

# Throughput: ~10 queries/segundo
```text

## O Custo Total

Vectora é uma **operação de custo muito baixo** comparado com alternativas:

### Exemplo: Análise de 50K linhas de código

| Operação | Custo |
| -------------------------------- | ---------------------------------- |
| Voyage 4 Embeddings | $1.00 (50K linhas × 0.02/M tokens) |
| Armazenamento Qdrant | $1.50/mês (para 50K documentos) |
| Voyage Rerank (100 queries/mês) | $0.20 |
| Gemini 3 Flash (100 queries/mês) | $0.08 |
| **Total Mensal** | **~$1.80** |

Comparação:

- GPT-4o: $1,500/mês (833x mais caro)
- Claude Pro: $20/mês + overages
- Auto-hosted (Llama): $500-1000/mês em infraestrutura

## Por que Vectora Não Oferece Plano Gratuito

É importante ser claro: **Vectora não tem plano gratuito** porque:

1. **Serviços pagos obrigatórios**:

   - Vercel Functions: $0.50-10/mês (execução)
   - Supabase: $25-100/mês (PostgreSQL + RLS)
   - MongoDB: $0-57/mês (metadata storage)
   - Qdrant Cloud: $0-249/mês (vector storage)

2. **APIs de IA com custo**:

   - Voyage 4: $0.02 per 1M tokens
   - Voyage Rerank 2.5: $2 per 1M tokens
   - Gemini 3 Flash: $0.075 per 1M tokens

3. **Operações**: SRE, suporte, segurança

Mesmo o plano Free ($0 para usuários, BYOK) tem custo mínimo de ~$150/mês para Vectora operador.

## Próximos Passos

1. [Entenda Embeddings](../concepts/embeddings) — como o contexto é encontrado
2. [Explore Reranking](../concepts/reranker) — como o contexto é refinado
3. [Setup Vectora](../getting-started/) — comece a usar Gemini via Vectora
4. [Guia de Preços](../pricing/) — entenda modelos de negócio

---

_Este é um guia técnico do projeto [Vectora](docs/vectora/). Especificamente sobre Gemini 3 Flash._
````text

extends Node
class_name ExperienceSystem

signal level_up(new_level, stat_points)
signal experience_gained(amount, current_xp)

var player: Player = null
var current_xp: float = 0.0
var current_level: int = 1
var xp_thresholds: Array[float] = []
var stat_points: int = 0

func _ready():
    player = get_parent()
    _generate_xp_thresholds()

func _generate_xp_thresholds():
    ## Cada nível requer 20% a mais XP
    xp_thresholds.clear()
    var base_xp = 100.0

    for level in range(1, 100):
        var threshold = base_xp * pow(1.2, level - 1)
        xp_thresholds.append(threshold)

func gain_experience(amount: float):
    current_xp += amount
    experience_gained.emit(amount, current_xp)

    ## Verificar level up
    while current_xp >= xp_thresholds[current_level - 1]:
        current_xp -= xp_thresholds[current_level - 1]
        level_up_player()

func level_up_player():
    current_level += 1
    stat_points += 5 ## 5 pontos por level

    ## Bonus de atributos automático
    player.asc.apply_modifier(&"health", 10.0)
    player.asc.apply_modifier(&"mana", 5.0)
    player.asc.apply_modifier(&"strength", 1.0)

    level_up.emit(current_level, stat_points)
    print("Level Up! Novo nível: %d" % current_level)

func get_xp_for_next_level() -> float:
    if current_level >= xp_thresholds.size():
        return xp_thresholds[-1]
    return xp_thresholds[current_level]

func get_xp_progress() -> float:
    var needed = get_xp_for_next_level()
    return current_xp / needed

extends Node
class_name SkillTree

signal skill_unlocked(skill_id, skill_data)
signal skill_upgraded(skill_id, new_rank)

class SkillNode:
    var id: StringName
    var name: String
    var description: String
    var icon: Texture2D
    var max_rank: int = 5
    var current_rank: int = 0
    var required_level: int = 1
    var required_parent: StringName = &"" ## Parent na tree
    var cost_per_rank: int = 1 ## Stat points
    var stat_bonus: Dictionary = {} ## {"strength": 2, "intelligence": 1}
    var ability_granted: StringName = &""

var player: Player = null
var skills: Dictionary[StringName, SkillNode] = {}
var unlocked_skills: Array[StringName] = []

func _ready():
    player = get_parent()
    _initialize_skill_tree()

func _initialize_skill_tree():
    ## Tier 1: Basic attacks
    add_skill(&"slash_mastery", SkillNode.new()).setup(
        "Slash Mastery",
        "Aumenta dano de slash em 10% por rank",
        1, ## Level req
        &"", ## No parent
        1, ## 1 ponto por rank
        {"strength": 2}
    )

    add_skill(&"heavy_strike", SkillNode.new()).setup(
        "Heavy Strike",
        "Ataque pesado com knockback",
        3, ## Level 3
        &"slash_mastery", ## Requer Slash Mastery
        2, ## 2 pontos por rank
        {"strength": 3, "constitution": 1},
        &"ability.heavy_strike"
    )

    ## Tier 2: Magic
    add_skill(&"fireball", SkillNode.new()).setup(
        "Fireball",
        "Lança uma bola de fogo",
        5,
        &"",
        2,
        {"intelligence": 3},
        &"ability.fireball"
    )

    add_skill(&"inferno", SkillNode.new()).setup(
        "Inferno",
        "Melhora Fireball com dano AoE",
        10,
        &"fireball",
        3,
        {"intelligence": 5},
        &"ability.inferno"
    )

    ## Tier 3: Defense
    add_skill(&"iron_skin", SkillNode.new()).setup(
        "Iron Skin",
        "Aumenta defesa em 5% por rank",
        2,
        &"",
        1,
        {"constitution": 2}
    )

func add_skill(skill_id: StringName, node: SkillNode) -> SkillNode:
    node.id = skill_id
    skills[skill_id] = node
    return node

func can_unlock_skill(skill_id: StringName) -> bool:
    var skill = skills[skill_id]

    ## 1. Verificar nível
    var exp_system = player.get_node("ExperienceSystem")
    if exp_system.current_level < skill.required_level:
        return false

    ## 2. Verificar parent
    if skill.required_parent != &"" and skill.required_parent not in unlocked_skills:
        return false

    ## 3. Verificar stat points
    if player.get_node("ExperienceSystem").stat_points < skill.cost_per_rank:
        return false

    return true

func unlock_skill(skill_id: StringName) -> bool:
    if not can_unlock_skill(skill_id):
        return false

    var skill = skills[skill_id]
    var exp_system = player.get_node("ExperienceSystem")

    ## Gastar pontos
    exp_system.stat_points -= skill.cost_per_rank
    skill.current_rank += 1

    ## Aplicar bonus de stats
    for stat in skill.stat_bonus:
        var bonus = skill.stat_bonus[stat]
        player.asc.apply_modifier(stat, bonus)

    ## Se não estava desbloqueada, adicionar à lista
    if skill_id not in unlocked_skills:
        unlocked_skills.append(skill_id)
        skill_unlocked.emit(skill_id, skill)

        ## Conceder ability se existir
        if skill.ability_granted != &"":
            player.asc.add_ability(AbilitySystem.get_ability_resource(skill.ability_granted))

    skill_upgraded.emit(skill_id, skill.current_rank)
    print("Skill desbloqueada: %s (Rank %d)" % [skill.name, skill.current_rank])

    return true

func get_skill_tree_paths() -> Dictionary:
    ## Retorna árvore visual {skill_id: [dependents]}
    var paths: Dictionary = {}

    for skill_id in skills:
        paths[skill_id] = []

        for other_id in skills:
            var other = skills[other_id]
            if other.required_parent == skill_id:
                paths[skill_id].append(other_id)

    return paths