From 272cacdfbace9df93e97b922515df9e801e40f06 Mon Sep 17 00:00:00 2001 From: VPS 4 Builder Date: Sun, 28 Jun 2026 07:11:38 +0200 Subject: [PATCH] =?UTF-8?q?docs(newwhats):=20Secret=C3=A1ria=20IA=20?= =?UTF-8?q?=E2=80=94=20arquitetura,=20RAG=20sem=20pgvector,=20modo=20teste?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenta o plugin secretaria: agente + cérebro de nós, resposta com fallback de providers, RAG por embeddings+cosseno na aplicação (sem pgvector, com o porquê), tabela sec_knowledge_chunks, indexação lazy e fallback, kill switch em dev e cuidado com migrations Knex. Co-Authored-By: Claude Opus 4.8 --- .../newwhats.clube67.com/secretaria-ia.md | 54 +++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 projetos/newwhats.clube67.com/secretaria-ia.md diff --git a/projetos/newwhats.clube67.com/secretaria-ia.md b/projetos/newwhats.clube67.com/secretaria-ia.md new file mode 100644 index 0000000..3c1ceea --- /dev/null +++ b/projetos/newwhats.clube67.com/secretaria-ia.md @@ -0,0 +1,54 @@ +# newwhats.clube67.com — Secretária IA (plugin `secretaria`) + +> Específico deste projeto. Atendente virtual de IA do newwhats, no plugin +> `backend/plugins/secretaria/` (gerenciado por **Knex**, tabelas `sec_*`). + +## Arquitetura + +- **Agente** (`sec_agents`): define provider/modelo/temperatura/`context_window`. +- **Cérebro** = nós (`sec_brain_nodes`), tipos: `persona`, `knowledge`, + `rules`, `calendar`, `escalation`. O `brain.ts` (`buildSystemPrompt`) monta o + system prompt concatenando os nós ativos + data/hora + protocolo + resumo. +- **Resposta**: `callAI` com **fallback de providers** (config do plugin: + `openai_key`, `gemini_key`, `anthropic_key` — em Admin → Plugins → Secretária IA). +- **Conversas/mensagens**: `sec_conversations` / `sec_messages` (com telemetria + `usage_tokens`/`provider_used`/`model_used`). +- **UI**: `/secretaria` (abas Conversas, Cérebro, Agenda, Agentes, Números) + + ícone de **Ajuda** com modelos prontos por nó (botão "Usar este modelo"). + +## RAG na Base de Conhecimento (SEM pgvector) + +**Por que sem pgvector:** a extensão **não está disponível** no Postgres da +VPS3 nem na imagem do `pgdev`, e o role `newwhats` **não é superuser** +(`CREATE EXTENSION` negado). Solução adotada (decisão 28/jun/2026): + +- `embeddings.ts`: **chunking** + **embed** (OpenAI `text-embedding-3-small` + ou Gemini `text-embedding-004`, conforme a chave) + **cosseno** — tudo em Node. +- Tabela **`sec_knowledge_chunks`**: vetor serializado em **JSON/text** (sem + extensão) + índices em `agent_id`/`node_id`. +- `brain.ts`: no nó `knowledge`, injeta só os **top-4 trechos** relevantes à + pergunta. **Indexação lazy** (reindexa quando o conteúdo muda — hash MD5). +- **Fallback**: sem chave de embedding ou em qualquer erro → injeta o conteúdo + **inteiro** (comportamento anterior). Nunca regride. + +> Para bases pequenas (clínica/empresa) é rápido e suficiente. Quando a VPS3 +> tiver `pgvector`, dá para migrar a busca ao banco sem mudar a interface. + +## Modo teste / segurança + +- `DISABLE_OUTBOUND=true` (kill switch global, ver `ambiente-dev.md`) bloqueia + **todo** envio — inclusive respostas automáticas da secretária — em dev. +- ⚠️ Ao conectar uma sessão WhatsApp **real** em dev, a secretária responde + sozinha (bots/IA). Mantenha o kill switch ligado nos testes. + +## Migrations (Knex) — cuidado + +O `migrate.ts` cria tabelas `if (!hasTable)` e adiciona colunas novas com +blocos `hasColumn`/`alterTable` (idempotentes). **Ao adicionar coluna usada em +runtime, adicione também o bloco de migração** — senão bancos antigos quebram +(ex.: faltava `sec_messages.usage_tokens/provider_used/model_used` → erro 42703, +corrigido). + +## Futuro (ver doc de evolução) + +Memória de longo prazo / humanização — em avaliação. Atualizar aqui quando definido.