Wiki

Wiki#

Rotas /v1/cloudwiki/* · owner/admin · gated por CLOUDWIKI_ENABLED (off → 404)

O que é#

Uma base de conhecimento gerenciada: espaços de páginas em Markdown (frontmatter + corpo), organizados em pastas, com busca híbrida (semântica + lexical), perguntas com resposta fundamentada (ask, RAG com fontes citadas), ingestão de arquivos e o Knowledge Refinery — um destilador assíncrono que transforma o espaço em FAQ cards. Cada página é indexada na escrita (sem passo de rebuild).

O que dá pra fazer#

• Criar espaços por projeto (opcionalmente por tenant) e organizá-los em pastas numa árvore.
• Upsert de páginas por path (PUT …/pages/<path>) com Markdown — a página fica pesquisável na hora.
• Buscar (search) com fusão híbrida RRF e perguntar (ask) com resposta fundamentada + páginas-fonte.
• Ingerir arquivos (PDF, DOCX, MD…) como fontes do espaço, com re-chunk, habilitar/desabilitar e reindexar.
• Rodar o Refinery (FAQ cards destilados) e listar os cards.
• Auditar: graph de wikilinks (resolvidos/quebrados) e audit (páginas sem fonte, links quebrados, órfãs).

Fluxo em 5 minutos#

KEY="X-API-Key: ctc_…" ; B=https://data-api.catcher.one ; JS='Content-Type: application/json'

# 1. Criar um espaço no projeto
SID=$(curl -sX POST $B/v1/cloudwiki/projects/$PID/spaces -H "$KEY" -H "$JS" \
  -d '{ "name": "Base de conhecimento" }' | jq -r .id)

# 2. Escrever uma página (indexada na hora)
curl -sX PUT "$B/v1/cloudwiki/spaces/$SID/pages/politicas/reembolso" -H "$KEY" -H "$JS" \
  -d '{ "markdown": "---\ntitle: Política de reembolso\n---\n\n# Política de reembolso\n\nPlano anual: 30 dias…" }'

# 3. Buscar (híbrido)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/search -H "$KEY" -H "$JS" \
  -d '{ "q": "reembolso plano anual", "hybrid": true, "limit": 5 }'

# 4. Perguntar (RAG com fontes)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/ask -H "$KEY" -H "$JS" \
  -d '{ "question": "qual o prazo de reembolso do plano anual?" }'
# → { "answer": "…", "sources": [{ "path": "politicas/reembolso", … }] }

# 5. Ingerir um arquivo como fonte (multipart)
curl -sX POST $B/v1/cloudwiki/spaces/$SID/sources -H "$KEY" \
  -F "file=@contrato-padrao.pdf"

Busca e ask — parâmetros#

POST /v1/cloudwiki/spaces/{sid}/search:

Cada hit informa como foi encontrado: match: "semantic" | "lexical" | "both" — debug de retrieval é parte do contrato.

POST /v1/cloudwiki/spaces/{sid}/ask aceita question + os mesmos ajustes (qa_first, lexical_weight, rerank, k_overfetch, path_prefixes); a recuperação do RAG é sempre híbrida. A resposta traz answer + sources.

Fontes (arquivos ingeridos)#

Knowledge Refinery (FAQ cards)#

O Refinery destila o espaço em cards de pergunta-resposta com fontes — um processo assíncrono com status acompanhável:

curl -sX POST $B/v1/cloudwiki/spaces/$SID/refinery/runs -H "$KEY"      # dispara
curl -s $B/v1/cloudwiki/spaces/$SID/refinery/runs -H "$KEY"           # status dos runs
curl -s $B/v1/cloudwiki/spaces/$SID/faq -H "$KEY"                     # cards prontos

Com qa_first: true na busca/ask, perguntas recorrentes acertam o card direto em vez de costurar chunks. Config por espaço em GET/PATCH /spaces/{sid}/refinery/config.

Organização e governança#

• Árvore: GET /projects/{pid}/tree (pastas + espaços); POST/GET/DELETE /projects/{pid}/folders; PATCH /spaces/{sid} renomeia/move.
• Graph: GET /spaces/{sid}/graph — arestas de wikilinks ([[caminho/da-pagina]]), resolvidos e quebrados.
• Audit: GET /spaces/{sid}/audit — páginas sem fonte, links quebrados, órfãs. Meta saudável: tudo zero.

Boas práticas#

• Páginas são síntese, não transcript: uma página por conceito, com wikilinks entre vizinhas — o graph/audit é seu detector de deriva.
• Escreva na mesma operação em que aprendeu: a página já sai indexada; não existe "rebuild depois".
• Para agentes de IA, exponha o espaço via MCP (wiki_ask, wiki_search, wiki_upsert_page) com escopos wiki:read/wiki:write.