# PRD: Arandu Inspector — Debug visual da SDK

> Generated via /vibeflow:discover on 2026-03-18

## Problem

O arandu tem um pipeline de write com 4 estágios (Extract → Entity Resolution → Reconcile → Upsert) e um pipeline de read com 3 sinais (Semantic + Keyword + Recency → Rerank → Format), mas quem usa a SDK só vê o input e o output. Não dá pra saber o que foi extraído, como as entidades foram resolvidas, quais decisões de reconciliação foram tomadas (ADD/UPDATE/NOOP/DELETE), como os scores foram calculados, ou por que um fato foi rankeado acima de outro.

Hoje, pra debugar, o dev do arandu precisa colocar prints no código-fonte, olhar logs, ou fazer queries SQL manuais. Não existe uma forma visual de ver o pipeline funcionando passo a passo.

O Arandu Inspector é um debugger visual web que mostra cada etapa dos pipelines de write e retrieve em tempo real, com todos os dados intermediários expostos. É uma ferramenta permanente de desenvolvimento — não um demo descartável.

## Target Audience

O desenvolvedor do arandu (Pedro). Ferramenta pessoal de desenvolvimento e debug. Secundariamente, pode servir como demo visual pra mostrar a devs interessados como o arandu funciona por dentro.

## Proposed Solution

Uma web app com duas telas principais:

### 1. Write Inspector
- Campo de texto pra enviar uma mensagem (simula um usuário mandando mensagem)
- Após o write, mostra o pipeline completo em etapas visuais:
  - **Extract:** fatos extraídos pelo LLM (entidade, atributo, valor, confiança)
  - **Entity Resolution:** como cada entidade foi resolvida (exact match? fuzzy? LLM?) e o score de match
  - **Reconcile:** decisão por fato (ADD/UPDATE/NOOP/DELETE) com justificativa
  - **Upsert:** resultado final — o que foi salvo no banco
- Tempo de execução de cada etapa

### 2. Retrieve Inspector
- Campo de busca pra fazer uma query de retrieve
- Mostra o pipeline de scoring:
  - **Candidatos:** todos os fatos encontrados (semantic search + keyword)
  - **Scores:** score semântico, keyword, recency, importância — pra cada fato
  - **Reranker:** resultado do LLM reranker (quando ativo)
  - **Contexto final:** o texto formatado que seria entregue ao agente

### 3. Memory Browser
- Lista de todas as entidades e fatos armazenados
- Filtro por user_id e por entidade
- Visualização dos dados brutos (fato, confiança, timestamps, embedding preview)

## Success Criteria

1. O desenvolvedor envia uma mensagem pelo Write Inspector e vê cada etapa do pipeline com dados intermediários em menos de 10s
2. O desenvolvedor faz uma query no Retrieve Inspector e vê os scores de cada fato candidato
3. O Memory Browser mostra todos os fatos armazenados com filtros funcionais
4. O setup é `docker compose up` e funciona (Postgres + pgvector + app)

## Scope v0

- [ ] Backend FastAPI que wrapa o arandu SDK e expõe dados intermediários dos pipelines
- [ ] Frontend React (Vite) com as 3 telas: Write Inspector, Retrieve Inspector, Memory Browser
- [ ] Docker Compose com Postgres+pgvector e a app
- [ ] Write Inspector: enviar mensagem, ver pipeline completo (extract → entity res → reconcile → upsert)
- [ ] Retrieve Inspector: fazer query, ver scores e ranking de cada fato
- [ ] Memory Browser: listar entidades e fatos com filtro por user_id
- [ ] Config de API key da OpenAI via variável de ambiente

## Anti-scope

- **Background jobs** (clustering, consolidation, memify, sleep_time) — v0 é só write + retrieve
- **Config editor na UI** — usar MemoryConfig defaults ou env vars
- **Multi-user auth** — é ferramenta local, sem login
- **Deploy em produção / hosting** — roda local com Docker
- **Mobile responsive** — é ferramenta de dev, desktop only
- **Testes automatizados** — é um projeto de debug, não precisa de CI
- **SSE/WebSocket pra streaming** — v0 espera o pipeline completar e mostra tudo de uma vez
- **Edição/deleção de fatos pela UI** — v0 é read-only no browser, write só via mensagem
- **Custom providers** — v0 usa OpenAI only
- **Graphs/charts bonitos** — v0 usa tabelas e cards, não precisa de D3/charts

## Technical Context

- **arandu SDK:** `pip install arandu[openai]` — MemoryClient com `write()` e `retrieve()`
- **Dados intermediários:** O SDK precisa expor dados de cada etapa. Opções:
  - Instrumentar o SDK com hooks/callbacks
  - Ou chamar as funções internas diretamente (write/extract, write/entity_resolution, etc.) — o código é modular em `src/arandu/write/` e `src/arandu/read/`
- **Stack sugerida:**
  - Backend: FastAPI (já é optional dep do arandu)
  - Frontend: React + Vite + Tailwind (rápido de montar, visual clean)
  - DB: Docker Compose com `pgvector/pgvector:pg16` image
- **Repo separado:** Projeto novo, instala arandu como dependência via `pip install arandu[openai]`
- **Provider:** OpenAI (já implementado no arandu como OpenAIProvider)

## Open Questions

Nenhuma. Todas as decisões foram tomadas.

## Decisão: Modo Verbose na SDK

O SDK será estendido com um parâmetro `verbose=True` em `write()` e `retrieve()`. Quando ativo, o resultado inclui `pipeline_steps` com dados intermediários de cada etapa. A API pública existente não muda — verbose é opt-in. Isso requer uma mudança no arandu SDK antes de construir o Inspector (ou em paralelo). O Inspector consome os dados verbose via API, sem acoplar a funções internas.
