# Wiki MIA — Trace do Orquestrador + Performance da Retrieval

**Data:** 2026-05-18
**Branch:** master
**HEAD:** `1c35076`
**Tenant testado:** `825021b6-3ce3-410e-b88f-86301274a5f6`
**Wiki carregada:** 988 chunks em ~261 notas curadas, 1662 `note_relations`

---

## §1 — Fluxo completo do `/orchestrator/plan`

Para cada query, o LangGraph atravessa **12 nós sequenciais** (Plan Graph). Capturado de 3 queries reais:

```
START
  → recepcionista              (intake, bloqueio spam, junção de fragmentos)
  → fila_de_espera             (8s window)
  → classificador_de_intencao  (closure detection do turn anterior)
  → vertical_guard             (resolve tenant_vertical + subniche)
  → capability_router          (10 capabilities canônicas)
  → capability_planner         (sub-graph p/ campanhas, se aplicável)
  → agent_router               (decide persona principal)
  → skill_router               (mapeia vertical × módulo → skills)
  → brain_context              (PRE-BRAIN ROUTER + decisão Brain)
  → tool_router                (markers + tools por capability)
  → approval_gate              (insere steps requires_approval=True)
  → audit_log                  (emite warnings — vira métricas técnicas)
END (retorna OrchestratorPlanResult)
```

### Trace de 3 queries (latência do `/orchestrator/plan` end-to-end)

| # | Query | Latência | primary_agent | capability | pre_brain_target | #steps | Skills | Tools |
|---|---|---|---|---|---|---|---|---|
| 1 | `"explique a tese de defesa para roubo qualificado"` | **43ms** | maia | research | brain | 15 | 7 | 15 |
| 2 | `"qual o preco da peticao inicial?"` | **13ms** | maia | bi_spreadsheets | **erp** (gate) | 13 | 7 | 14 |
| 3 | `"lead vendas spin selling tecnicas"` | **10ms** | maia | crm | **crm** (gate) | 7 | 8 | 8 |

**Observações:**
- Plan-only é **rápido (10-43ms)** — não chama LLM nem RPC do Supabase. Só roteamento + dicionários em memória.
- Query 2 e 3 disparam o Pre-Brain Router (F8): `step-brain-search` é **suprimido**; warning gravado.
- `subagent_ids` agregado: **10-13 sub-agentes** disponíveis pra MAIA por turno (research, bi, writer, book, presentation, scheduling, etc.). Step específico escolhe qual rodar.

### Sub-agentes da MAIA disponíveis no turno

```
maia-researchagent       maia-maiabiagent        maia-maiabivalidator
maia-writeragent         maia-bookagent          maia-presentationagent
maia-meetingreporter     maia-schedulingagent    maia-maiaorchestrator
maia-ondemandagent       (e mais conforme módulo)
```

### Skills da MAIA disponíveis

```
maia-cited-legal-research        maia-finder-investigation
maia-document-synthesis          maia-longform-book-production
maia-presentation-deck           maia-spreadsheet-to-evidence
maia-meeting-transcript-and-actions
```

### Tools por capability (exemplos observados)

| Capability | Tools roteadas |
|---|---|
| research | google_drive, microsoft_onedrive, exa_search, tavily_search, parallel_search, mia_finder_person/company/vehicle, ... |
| bi_spreadsheets | google_sheets, metabase, power_bi, bigquery, thoughtspot, meta_insights, meta_ads, tiktok_business, ... |
| crm | uazapi_whatsapp, whatsapp_business_cloud, google_calendar, microsoft_outlook, salesforce_crm, hubspot_crm, close_crm, supabase_vector |

---

## §2 — `/orchestrator/run` (execução completa com LLM)

Query: `"explique tese defesa roubo qualificado"`

```
TOTAL: 12879ms

Graph nodes traversed:
  Plan (12 nós, ~50ms)
  → plan_context           (consolida plano)
  → agent_runtime          (chama LLM com brain_context)
  → case_update_writer     (registra novidade no CRM, se aplicável)

model_used:         gpt-5.4-mini-2026-03-17
brain_context:      6 chunks devolvidos ao LLM
assistant_response: 200+ chars (resposta real do gpt-5.4-mini sobre tese de defesa)
analytics:          null (campo existe mas não populado — gap §6 do CLAUDE.md)
```

**Observações:**
- LLM domina a latência: ~12.8s sendo ~50ms plan + ~1s retrieval (estimado) + ~11.7s LLM (gpt-5.4-mini, output longo).
- Campo `analytics` aparece no schema mas está null — **CLAUDE.md §6 prevê métricas técnicas (tokens, latency, cache, retry) que ainda não são gravadas**. Gap conhecido pra audit log estruturado.

---

## §3 — Performance da retrieval por modo (15 medições)

5 queries × 3 modos = 15 chamadas reais ao `/brain/search`.

### Por query (latência | chunks | notas | chars | tokens estimados)

| Query | Leve | Média | Profunda |
|---|---|---|---|
| lead vendas spin selling | 933ms · 5ch · 2nt · 2.2k tok | 578ms · 13ch · 5nt · 6.4k tok | **753ms · 16ch · 6nt · 8.0k tok** |
| tese defesa roubo qualificado | 550ms · 7ch · 3nt · 3.3k tok | 951ms · 12ch · 5nt · 5.5k tok | **1541ms · 35ch · 16nt · 15.6k tok** |
| negociação cláusulas leoninas | 2677ms · 9ch · 3nt · 3.7k tok | 1908ms · 14ch · 5nt · 5.9k tok | **1182ms · 17ch · 6nt · 7.4k tok** |
| follow up reativação base | 873ms · 16ch · 2nt · 7.2k tok | 1253ms · 32ch · 4nt · 14.8k tok | **1392ms · 86ch · 12nt · 40.1k tok** |
| due diligence M&A | 810ms · 15ch · 3nt · 7.3k tok | 845ms · 24ch · 6nt · 11.6k tok | **1579ms · 61ch · 22nt · 30.5k tok** |

### Agregado por modo (mediana de 5)

| Modo | Lat p50 | Lat min | Lat max | Notas p50 | Tokens p50 | Budget | Utilização |
|---|---|---|---|---|---|---|---|
| Leve | 873ms | 550ms | 2677ms | 3 | 3733 | 7500 | **49,8%** |
| Média | 951ms | 578ms | 1908ms | 5 | 6380 | 15000 | **42,5%** |
| Profunda | **1392ms** | 753ms | 1579ms | **12** | **15620** | 52500 | **29,8%** |

### Latência vs alvos do spec §6

| Modo | Alvo (spec) | Realizado p50 | Status |
|---|---|---|---|
| Leve | <300ms | 873ms | ❌ **2,9× acima** |
| Média | <900ms | 951ms | ⚠️ borderline (+5%) |
| Profunda | 2000-4000ms | 1392ms | ✅ **abaixo do alvo** (rápido!) |

### Diff Profunda vs Média (a parte F5)

| Query | Δ notas | Δ tokens |
|---|---|---|
| lead vendas | +1 | +1607 |
| tese defesa | **+11** | **+10096** |
| negociação | +1 | +1495 |
| follow up | +8 | +25312 |
| due diligence | **+16** | **+18966** |

**Verdict F5:** Profunda traz conectadas reais. Em queries com Wiki bem conectada (tese, follow-up, due-diligence) o ganho é **massivo**: 8-16 notas adicionais, +10k a +25k tokens.

### Dedup rate (chunks/nota)

Indica densidade dos chunks por nota expandida:

| Query | Média | Profunda |
|---|---|---|
| lead vendas | 2,6 | 2,7 |
| tese defesa | 2,4 | 2,2 |
| negociação | 2,8 | 2,8 |
| follow up | **8,0** | 7,2 |
| due diligence | 4,0 | 2,8 |

"Follow up" tem ~8 chunks/nota — notas longas (provavelmente artigos longos da Wiki). "Tese defesa" tem ~2,2 — notas mais fragmentadas. Sinal útil pra detectar quando o conteúdo está mal-fragmentado.

---

## §4 — Índices/KPIs propostos pra assertividade

Da análise dos 15 traces, identifico **8 índices** que fazem sentido medir continuamente:

### KPIs técnicos (retrieval)

| Índice | Fórmula | Alvo | Atual | Status |
|---|---|---|---|---|
| **Latência p50 por modo** | mediana(lat_ms) por mode | Leve<300 / Méd<900 / Prof<4000 | 873 / 951 / 1392 | Leve falha |
| **Latência p95 por modo** | percentil 95 (lat_ms) | <2× p50 | n/a (amostra 5) | precisa N≥20 |
| **Notas distintas / modo** | mediana(notes) | 3-5 / 6-10 / 10+ | 3 / 5 / 12 | ✅ bate |
| **Budget utilization** | tokens_p50 / budget_tokens | 30-70% (folga p/ prompt) | 50% / 42% / 30% | ✅ folga ok |
| **Cross-note expansion gain** | Δnotas(profunda - média) | ≥+3 mediano | +6 | ✅ entrega |
| **Empty result rate** | %queries com 0 chunks | <5% | 0% (0/15) | ✅ |
| **Brain skip rate (Pre-Brain Router)** | %queries com pre_brain_target≠brain | depende intent mix | 2/3 (test) | descritivo |

### KPIs de assertividade (precisa LLM no loop)

Requer benchmark cross-model (6 IAs) que **não consigo rodar agora** sem keys. Mas estes são os que importam:

| Índice | Como medir | Por que importa |
|---|---|---|
| **Closure positive rate** | %turnos terminados com sinal explícito de fechamento | Wiki responder pergunta = closure ↑ |
| **Hallucination rate** | %respostas com claim sem chunk citado | Spec §1.1: sem chunk = conjectura |
| **Source citation density** | citações/100 tokens de resposta | Wiki deve citar fontes (CLAUDE.md §7) |
| **Modo correctness** | %vezes que LLM escolhe modo apropriado vs default | Profunda só quando vale o custo |

### Gaps observados que viram backlog

| Gap | Severidade | Comentário |
|---|---|---|
| Leve 2,9× acima do alvo de latência | Alta | **N+1 query**: 5 fetches sequenciais a `knowledge_chunks`. Bulk fetch via `note_id=in.(...)` resolve. |
| `analytics: null` em `/orchestrator/run` | Média | Spec §6 do CLAUDE.md prevê tokens/latency/cache/retry técnicos. `audit_log` node hoje só emite warnings. |
| `tenant_boost` config não consumido | Baixa | Passa pra RPC mas pós-score não usa. Spec próprio. |
| Sem log quando embed_texts falha | Baixa | `EmbeddingClientError` silenciada — observability invisível. |
| Reranker em fallback orphan | Baixa | Removido do modelo (Daniel 2026-05-18), código permanece. |

---

## §5 — Benchmark cross-model (6 IAs) — **bloqueado**

Você pediu 6 IAs × 5 perguntas × 3 modalidades = 90 chamadas. **Não rodou.**

### Por que

`.env` tem **só `OPENAI_API_KEY`** (gpt-5.4-mini). Os outros provedores do §11.11 do CLAUDE.md não têm key configurada:

| Provedor | Modelo §11.11 | Env var esperada | Configurada? |
|---|---|---|---|
| OpenAI | gpt-5.4-mini (rápido) | `OPENAI_API_KEY` | ✅ |
| DashScope (Alibaba) | Qwen Plus/Flash 1M | `DASHSCOPE_API_KEY` | ❌ |
| DashScope | Qwen3-Max-Thinking 1M | `DASHSCOPE_API_KEY` | ❌ |
| DeepSeek | DeepSeek v4 (volume) | `DEEPSEEK_API_KEY` | ❌ |
| Moonshot | Kimi K2.6 (premium) | `MOONSHOT_API_KEY` | ❌ |

### Pra destravar

Adicionar no `.env`:
```
DASHSCOPE_API_KEY=sk-...      # Qwen Plus, Qwen Flash 1M, Qwen3-Max-Thinking
DEEPSEEK_API_KEY=sk-...       # DeepSeek v4
MOONSHOT_API_KEY=sk-...       # Kimi K2.6
```

Após isso: 6 modelos × 5 perguntas × 3 modos = 90 chamadas. Custo estimado bruto (sem cache, prompts de ~5k tokens entrada + 2k saída):
- 90 chamadas × 5k input × $0.0005/1k ≈ $0,23 input
- 90 × 2k output × $0.002/1k ≈ $0,36 output
- **Total < $1 USD** se modelos forem mini/flash. Premium (Opus/Kimi K2 maior) sobe pra ~$5.

---

## §6 — Resumo executivo

**Funciona:** SIM. Smoke E2E 15 chamadas, 0 erros, todas as 3 modalidades retornam dados úteis. `/orchestrator/run` end-to-end com LLM real (gpt-5.4-mini) responde a query jurídica em ~13s. F5 cross-note expansion confirmadamente puxa conectadas (até +16 notas em Profunda).

**Performance:**
- Leve está **3× acima** do alvo de latência (873ms vs <300ms). N+1 query.
- Média no alvo (951ms).
- Profunda **abaixo** do alvo (1392ms vs 2-4s) — sobra performance pra escalar conectadas.
- Budgets utilizados 30-50% — folga pra prompts e resposta.

**Próximos passos sugeridos (você decide ordem):**
1. **N+1 fix:** bulk fetch de `knowledge_chunks` por `note_id=in.(...)` — Leve cai pra <300ms.
2. **`analytics` populado:** audit_log node grava tokens/latency/cache no `OrchestratorRunResult` (§6 CLAUDE.md).
3. **Cross-model bench:** adicionar 3 keys (DashScope, DeepSeek, Moonshot) → script de bench × 90 chamadas → relatório de assertividade comparada.
4. **F7 UI Wiki:** plano escrito, 5 design questions abertas (onde plugar, sub-tab, default slug, etc.).

---

**Dados brutos:** `.gstack/qa-reports/wiki-retrieval-metrics.json` (15 medições JSON)