teqo-backup/docs/changelog/2026-09-26-c229.md
Francisco Solla 3e8429daae feat(C229): busca por sentido no acervo de falas
Troca o motor do modo tema (Câmara + internet) de expansão lexical para
embeddings (Deep Infra, BAAI/bge-m3), com índice próprio (speechEmbedding),
ranking por proximidade em memória, evidência real do trecho mais próximo,
vazio honesto por limiar e degradação para a busca literal. Inclui a
collection oculta + migration, o CLI pnpm acervo:index (--dry-run/--limit/
--source/--force/--probe), o port do design aprovado e a suíte de testes.

Pós-rebase: o snapshot da migration seguinte (20260926_062039_add_archive_photo,
do C231 já na main) foi regenerado para incluir speech_embedding — sem ele o
próximo migrate:create recriaria a tabela.

Closes #1360
2026-09-26 11:59:21 -03:00

3.7 KiB

C229 — Busca por sentido no acervo de falas (2026-09-26): o modo "Por tema" do acervo interno (Câmara + internet) deixou de ser expansão lexical e passou a ser similaridade por sentido (embeddings), com o resultado ordenado por proximidade e a evidência real de cada fala. Motor: src/lib/speechSemantic.ts (puro — cosine, pooling, janelas de texto, hash de conteúdo, ranking com limiar SPEECH_SEMANTIC_MIN_COSINE=0.4, ordenação com relevância default e data/duração do usuário sobrepondo) e a fronteira de provider deepInfraEmbed.ts (endpoint OpenAI-compatible da Deep Infra, modelo BAAI/bge-m3, mesma DEEPINFRA_API_KEY do ASR, batches de 32, timeout, L2-normalização e contrato "nunca lança → null"; sem dependência nova). Índice: collection oculta nova speechEmbedding (kind: speech|segment|window, speech, order, startSeconds, model, dimensions, contentHash, vector json; read: canReadSpeech, escrita admin-only, admin.hidden; cascade no Speech.beforeDelete, que também corrige o rollback SQL do C155) com migration gerada 20260926_034118_add_speech_embedding — o diff gerado trazia drift das migrations de 2026-09-24 cujos snapshots perderam objetos do C215/C219, então o SQL foi hand-reduzido ao escopo e o snapshot novo repara a cadeia para as próximas migrations. Loader: mode=tema embute a query uma vez, rankeia em memória os candidatos das facetas (sem LIKE de q e sem C174), fatia a página de 25 e carrega a evidência do melhor trecho (speechSemanticSearch.ts); degradação honesta para a busca literal de hoje + aviso discreto quando o provider cai ou não há candidato indexado (anti-falso-positivo), vazio honesto abaixo do limiar, e o ator fora do gate nunca dispara o provider (fail-closed). As duas loaders compartilham um único loadSemanticSpeechPage; o provider só é consultado quando o modelo bate (vetor de outro modelo/1024 dims nunca é comparado). CLI: pnpm acervo:index (scripts/index-speeches.mjs + scripts/lib/speechIndex.mjs) idempotente por hash+modelo, com --dry-run, --limit, --source, --force, relatório (indexadas/puladas/falhas/trechos/bytes/tokens/custo) e o --probe "<tema>" read-only (top-N com score, só CLI) que calibra o limiar e verifica o aceite pós-deploy; runbook §C155/§C225 ganhou o passo de indexação. UI (Impeccable B, port do design docs/plans/acervo-busca-por-sentido-ui-design.html): selo "Tema" + "Termo exato" coexistindo, bloco "Trecho mais próximo do tema" (trecho real, sem <mark> e sem score), heading/subtítulo responsivos, seletor de ordenação da internet com "Mais relevantes" default no tema (e vocabulário literal no degradado), vazio honesto da cena 03 e selo literal no card degradado; a Câmara mantém a decisão de produto registrada de não ganhar controle de ordenação novo. Testes: unit do motor/planejamento/CLI/provider/URL/VM/cards, int do ranking/limiar/degradação/facetas/modelo/evidência/cascade/indexação ponta-a-ponta e e2e do degradado + ordenação do tema; pnpm gate:fast, knip, format:check e os 41 e2e do campaignSpeechAcervo verdes. Crítica do designer (trigger c) contra o app renderizado em três ciclos (390/1280, tema/vazio/degradado/exato): todas as cenas/estados certificados; a única divergência material — o menu aberto do "Ordenar por" é o <select> nativo aprovado no C216 e não o listbox desenhado no artefato — foi levada ao humano no gate e aceita explicitamente (conteúdo/ordem/default conferidos por DOM). Design tier: openai/gpt-5.6-sol. O aceite de produto ("combate à oposição", "impeachment") depende do corpus real: Fase 5 do impl plan no homeserver (acervo:index + --probe), com top-N/limiar/custo a registrar aqui na primeira execução.