# PRD: Arandu Inspector — Test Harness Standalone

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

## Problem

Não existe uma forma visual de testar o write pipeline do Arandu SDK de ponta a ponta. Hoje, pra verificar se extração, entity resolution, reconciliação e upsert funcionam corretamente, o dev precisa: (1) escrever um script Python, (2) ler o banco manualmente, (3) interpretar logs. Não dá pra ver as decisões intermediárias (que entidades foram resolvidas, quais fatos foram ADD vs UPDATE vs NOOP, quais relações foram vinculadas a quais fatos) sem debugar.

Além disso, a documentação do SDK precisa ser validada na prática. A melhor forma de testar se um dev consegue integrar o Arandu é fazendo a integração num repo separado, seguindo apenas a documentação pública. Problemas de DX (developer experience) — imports errados, parâmetros não documentados, erros de setup — só aparecem quando alguém tenta usar o SDK de verdade.

## Target Audience

1. **Maintainer do SDK (Pedro)** — testar features novas, validar o write pipeline visualmente, detectar bugs.
2. **Desenvolvedor avaliando o SDK** — entender o que acontece dentro do `memory.write()` antes de integrar.
3. **Agente Claude na outra sessão** — vai construir isso seguindo a doc, servindo como teste de DX.

## Proposed Solution

Uma aplicação web standalone (repo separado) que:

1. Instala `arandu` via PyPI (`pip install arandu`)
2. Sobe PostgreSQL + pgvector via Docker Compose
3. Oferece uma interface web onde o dev envia mensagens como se fosse um usuário
4. Após cada `memory.write()`, mostra o resultado completo do pipeline com breakdown visual por step

A interface mostra, para cada mensagem processada:

- **Input**: mensagem enviada, user_id, config usada
- **Extraction**: entidades, fatos e relações extraídos (com confidence), modo usado
- **Entity Resolution**: como cada entidade foi resolvida (exact/fuzzy/LLM/new), com scores
- **Reconciliation**: decisões por fato (ADD/UPDATE/NOOP/DELETE), fato matched, confidence
- **Upsert**: fatos criados/atualizados, relações criadas, evidence linkage, mirror facts
- **Timing**: duração de cada step em ms
- **Knowledge Graph**: estado atual das entidades, fatos ativos e relações (com indicação de invalidados)

Usa `verbose=True` do SDK que retorna `PipelineTrace` com todos os dados intermediários.

Não precisa ser tempo real — resultado após completar o pipeline, mas com detalhe total.

## Success Criteria

1. Dev na outra sessão consegue montar o app seguindo apenas a documentação pública do Arandu (getting-started, write-pipeline, configuration, data-types, database).
2. A interface mostra todas as decisões do pipeline para cada mensagem enviada.
3. É possível enviar 10+ mensagens e ver o knowledge graph evoluir (incluindo cascata de invalidação quando fatos mudam).
4. Problemas de DX encontrados durante a construção são documentados como issues.

## Scope v0

- **Docker Compose**: PostgreSQL 16 + pgvector, com schema do Arandu aplicado
- **Backend**: FastAPI (Python), instala `arandu` via pip
- **Frontend**: A critério do implementador (Jinja2 templates, htmx, React — o que for mais produtivo). Resultado final deve ser limpo e navegável.
- **Páginas/Views**:
  - **Write**: textarea pra mensagem + botão send → mostra pipeline trace completo expandido por step
  - **Knowledge Graph Browser**: lista entidades ativas, fatos ativos (com valid_from/valid_to), relações ativas + invalidadas
  - **History**: lista de mensagens enviadas com link pro trace de cada uma
- **Endpoints**:
  - `POST /api/write` — recebe `{user_id, message}`, chama `memory.write(verbose=True)`, retorna `WriteResult` + `PipelineTrace`
  - `GET /api/facts?user_id=X` — lista fatos do banco (ativos + invalidados com flag)
  - `GET /api/entities?user_id=X` — lista entidades
  - `GET /api/relations?user_id=X` — lista relações (com evidence_fact_id e status)
  - `GET /api/events?user_id=X` — histórico de mensagens
- **Config**: `.env` com `DATABASE_URL`, `OPENAI_API_KEY`, `USER_ID` (default "inspector-user")
- **Setup**: `docker compose up -d` + `pip install -r requirements.txt` + migrations + `uvicorn app:app`

## Anti-scope

- **Sem read pipeline** — só write. Read é outra feature futura.
- **Sem autenticação** — test harness local, sem login.
- **Sem deploy em cloud** — roda local only.
- **Sem testes automatizados no inspector** — o inspector É o teste.
- **Sem background jobs** — clustering, consolidation, memify, sleep-time ficam de fora.
- **Sem edição/deleção manual de fatos** — read-only visualization, write só via mensagem.
- **Sem streaming/WebSocket** — espera pipeline completar, mostra tudo de uma vez.
- **Sem custom providers** — OpenAI only (shipped com o SDK).
- **Sem mobile responsive** — desktop only.

## Technical Context

### SDK Integration (o que o implementador precisa saber)

```python
from arandu import MemoryClient, MemoryConfig
from arandu.providers.openai import OpenAILLMProvider, OpenAIEmbeddingProvider

# Setup
config = MemoryConfig(
    extraction_mode="multi_pass",
    extraction_model="gpt-4o",
)
llm = OpenAILLMProvider(api_key="...", model="gpt-4o")
embeddings = OpenAIEmbeddingProvider(api_key="...")
memory = MemoryClient(
    database_url="postgresql+asyncpg://arandu:arandu@localhost:5432/arandu_inspector",
    llm=llm,
    embeddings=embeddings,
    config=config,
)

# Write com verbose trace
result = await memory.write(user_id="inspector-user", message="...", verbose=True)

# result.pipeline contém PipelineTrace
# result.pipeline.to_dict() → JSON-serializável
# result.pipeline.steps → list[PipelineStep(name, duration_ms, data)]
```

### PipelineTrace (dados disponíveis para visualização)

Cada step do `PipelineTrace` tem `name`, `duration_ms`, e `data` (dict):

```
extraction:       {mode, entities[], facts[], relations[], entity_count, fact_count, relation_count}
entity_resolution: {entities[{name, key, method, is_new, fuzzy_score}], entity_count}
reconciliation:   {decisions[{fact_text, subject, action, matched_fact_id, matched_fact_text, confidence}],
                   action_counts{ADD, UPDATE, NOOP, DELETE}}
upsert:           {added, updated, confirmed, deleted}
```

### Docker Compose

```yaml
services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: arandu_inspector
      POSTGRES_USER: arandu
      POSTGRES_PASSWORD: arandu
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
```

### Documentação pública (referências para o implementador)

O implementador deve seguir APENAS estas docs:
- `docs/en/getting-started.md` — setup inicial
- `docs/en/concepts/write-pipeline.md` — como o write funciona
- `docs/en/configuration.md` — MemoryConfig params
- `docs/en/advanced/data-types.md` — schemas e modelos
- `docs/en/advanced/database.md` — setup do banco
- `docs/en/custom-providers.md` — OpenAI provider setup

**Se algo não estiver documentado ou estiver errado, isso é um gap de DX a ser reportado.**

## Open Questions

- **Alembic vs create_all**: A doc de getting-started recomenda qual abordagem? Se não recomenda, é gap de DX.
- **Visualização do grafo**: Tabela é suficiente pra v0. Grafo visual (vis.js, d3-force) é nice-to-have futuro.
