# V2 da IA do Privia — Plano de Trabalho > Versão: 1.0 · Status: Proposta · Autor: Equipe Privia > Escopo: Redesenho do agente de IA contextual (módulo `agent`) para corrigir as falhas de arquitetura da V1. --- ## 1. Contexto e justificativa A V1 do agente (`modules/agent`) foi construída com boas intenções de segurança e conhecimento, mas acumulou falhas estruturais que tornaram o produto frágil, caro de manter e visualmente inconsistente com o sistema. Este documento propõe a **V2**: uma reescrita guiada por princípios claros, com plano de trabalho faseado e critérios de aceite verificáveis. ### 1.1 Problemas observados na V1 | # | Problema | Evidência / Sintoma | Arquivo-chave | |---|---|---|---| | P1 | Prompt gigante e amarrado (centenas de regras "OBRIGATÓRIAS e VINCULANTES") injetado em modelo pequeno | IA fica presa em regrinhas (ex.: `coleta_id`), ignora o conjunto, contradiz-se | `components/Agent.php::systemPrompt` | | P2 | Heurísticas de "correção" por regex frágil (`pedeArquivo`, `negaArquivo`, `desistiu`, `pedeTodos`) | Palavra acentuada "gráfico" não era detectada (falta `/u`) → gráfico nunca era gerado; tabela "vazava" | `components/Agent.php` | | P3 | Conhecimento fragmentado e semântica fraca: `agent_knowledge` mina trivia por regex do código | IA responde como se o sistema fosse "uma tabela"; conhecimento é ruído estruturado | `components/CodeIndexer.php`, `models/AgentKnowledge.php` | | P4 | Acesso a dados depende de "ids validados na sessão" frágil | Não-admin recebe "acesso negado" a coletas que consegue abrir no navegador | `components/TenantGuard.php`, `components/AgentContext.php` | | P5 | Geração de gráficos em engines duplicadas e inconsistentes (GD, export externo bloqueado, Highcharts inline) | PNG visualmente distante do Highcharts da tela; export externo 403 (Cloudflare) | `components/ArquivosService.php`, `components/tools/*` | | P6 | Sem testes automatizados de ponta a ponta | Bugs de uma linha escaparam por horas (regex `/u`, `series:` faltando, compat `Highcharts.chart` vs `new Highcharts.Chart`) | todo o módulo | | P7 | Sem observabilidade do raciocínio do modelo | Debug manual e lento; não se sabe o que o modelo viu/pensou a cada turno | `components/Agent.php::run` | --- ## 2. Princípios da V2 1. **O modelo é o centro, não as regras.** Regras imperativas e regex são último recurso, não primeiro. O prompt deve ser curto, claro e permitir raciocínio, não micro-gerir. 2. **Fonte única de verdade.** Uma única engine de gráficos; um único lugar que descreve o domínio; um único caminho de acesso a dados. 3. **Provar com teste automatizado.** Todo comportamento (heurística, tool-calling, renderização) tem teste automatizado que roda em CI. "Funcionou no navegador" deixa de ser o único critério. 4. **Observabilidade primeiro.** Cada turno gera um "trace" (mensagens, tool calls, resultados, razão) consultável. 5. **Conhecimento semântico, não mineração por regex.** O domínio é descrito de forma estruturada (entidades, relações, regras curadas), não extraído por heurística de código. 6. **Incremental e seguro.** Cada fase é independente, testável e reversível. Nada de "reescrita big-bang". --- ## 3. Arquitetura alvo da V2 ``` ┌─────────────────────────────────────────────────────────────┐ │ UI (widget / chat) │ │ • Renderização de gráfico: Highcharts INLINE (única) │ │ • Download de arquivos (XLSX/PDF/DOCX) separado de gráfico │ └──────────────────────────────┬──────────────────────────────┘ │ HTTP JSON (send / historico / feedback) ┌──────────────────────────────▼──────────────────────────────┐ │ ChatController (gate, rate-limit) │ └──────────────────────────────┬──────────────────────────────┘ ┌──────────────────────────────▼──────────────────────────────┐ │ Agent (orquestrador) │ │ • systemPrompt CURTO (identidade + acesso + 1-3 regras) │ │ • loop de tool-calling com limite e síntese │ │ • TRACE por turno (persistido, consultável) │ └──────┬──────────────┬──────────────┬──────────────┬──────────┘ │ │ │ │ ┌─────▼────┐ ┌──────▼─────┐ ┌─────▼─────┐ ┌─────▼──────────┐ │ Tools │ │ Conhecimento│ │ Acesso │ │ Gráficos │ │ (reduzir)│ │ Semântico │ │ (escopo │ │ (Highcharts │ │ │ │ (entidades/ │ │ por │ │ inline, │ │ │ │ relações/ │ │ massa de │ │ config única) │ │ │ │ regras) │ │ dados) │ │ │ └──────────┘ └─────────────┘ └───────────┘ └────────────────┘ ``` ### 3.1 Prompt enxuto - **Antes:** centenas de linhas, 20+ regras numeradas, glossário, esquema, "OBRIGATÓRIAS E VINCULANTES". - **Depois:** identidade (1 parágrafo), acesso do usuário (1 bloco), 3–5 regras de alto nível (não inventar, usar ferramentas, responder pt-BR), e o resto delegado a **ferramentas bem descritas**. O modelo deve raciocinar, não decorar. ### 3.2 Ferramentas consolidadas - **Antes:** 11 ferramentas (db_schema, db_select, code_search, code_read, knowledge_search, perfil_desempenho, coleta_cadeia_nota, coleta_faixas, gerar_arquivo, gerar_relatorio_template, context_get). - **Depois:** poucas, com responsabilidade clara: - `context_get` (acesso/usuário) - `db_select` (consulta segura — mantém o guard) - `perfil_desempenho` (retorna dados + config Highcharts pronta) - `coleta_cadeia_nota` + `coleta_faixas` (nota/faixas — manter, são específicas) - `gerar_arquivo` (só XLSX/PDF/DOCX/TXT — **sem PNG**) - `gerar_relatorio_template` (mantém) - **Remover do loop:** `code_search`, `code_read`, `db_schema`, `knowledge_search` **como ferramentas do turno**. Viram **pipeline offline** (ver 3.3). ### 3.3 Conhecimento semântico (substitui CodeIndexer) - **Antes:** `CodeIndexer` extrai trivia por regex a cada build e injeta como "conhecimento". - **Depois:** um **modelo semântico curado** de entidades do Privia: - Entidades (contexto, coleta, projeto, cliente, vertical, scope, inventario…) - Relações (contexto→cliente, coleta→contexto, coleta→estrutura→indicador…) - Regras de negócio curadas (fórmula da nota, faixas, soft-delete, auditoria em `log`) - Descrições por tela (glossário da tela já existente, mantido) - **Persistência:** uma tabela `agent_dominio` (ou JSON versionado) mantida por especialista, **não** gerada por regex. O `CodeIndexer` é aposentado ou reduzido a auditoria. ### 3.4 Acesso a dados (escopo por massa de dados) - **Antes:** só ids validados pela "pista da tela"; não-admin ficava cego fora da tela. - **Depois:** o `AgentContext` resolve a **massa de dados real** do usuário: - Clientes (já resolvido: `profile.cliente_id` + `user_has_resource`) - Contextos dos clientes (derivação já adicionada: `contexto WHERE cliente_id IN (...)` ) - Projetos/coletas derivados quando necessário - **Guard:** mantém o isolamento de tenant (não relaxar segurança), mas a IA passa a **poder consultar a massa do usuário**, não só a tela atual. ### 3.5 Gráficos — fonte única (Highcharts inline) - **Antes:** GD + export externo (403) + Highcharts inline (v4), três visuais. - **Depois:** - **Única engine de gráfico no chat: Highcharts inline** (compatível com v4 do sistema — `new Highcharts.Chart({renderTo})`). - A ferramenta `perfil_desempenho` devolve **config Highcharts pronta** (categorias, séries, plotBands/faixas) — o widget só renderiza. - **PNG deixa de existir para gráficos.** "Gerar gráfico" = render inline. Download (XLSX/PDF/DOCX) é para dados/listas, não para gráfico. - Fallback visual: se Highcharts indisponível, mostrar **tabela dos dados** (já existente) em vez de PNG feio. ### 3.6 Observabilidade (traces) - Cada turno persiste um **trace**: pergunta, system prompt resumido, todas as tool calls (nome + args + resultado), resposta final, tempo, modelo, erros. - Tabela `agent_trace` (ou JSON em `agent_conversa`). Endpoint `/agent/chat/trace?id=` para inspecionar. - **Critério de aceite:** qualquer resposta ruim deve ser debuggável em < 1 min pelo trace. ### 3.7 Testes automatizados - Suíte PHPUnit no módulo agent: - **Heurísticas:** `pedeArquivo`/`negaArquivo`/`desistiu`/`pedeTodos` com casos acentuados e de borda. - **Ferramentas:** `perfil_desempenho` (dados reais de fixture), `coleta_cadeia_nota`, `db_select` (escopo/tenant). - **Loop:** mock de LLM que responde tool calls determinísticos; garantir limite de iterações, síntese, enforcement. - **Renderização:** teste de integração com Highcharts real (jsdom ou headless) — série/faixas presentes no DOM. - CI: rodar suíte a cada PR. "Passou no navegador" não é critério único. --- ## 4. Plano de trabalho detalhado > Cada fase: **Objetivo**, **Tarefas**, **Entregável**, **Critério de aceite**, **Teste obrigatório**. > Ordem sugerida: Fase 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7. ### Fase 0 — Baseline e infraestrutura de teste (1–2 semanas) **Objetivo:** parar de sangrar; ter rede de proteção antes de mudar comportamento. - [ ] Tarefa 0.1 — Criar estrutura de testes do módulo `agent` (PHPUnit + fixtures de banco). - [ ] Tarefa 0.2 — Escrever testes das **heurísticas atuais** (`pedeArquivo`, `negaArquivo`, `desistiu`, `pedeTodos`) cobrindo: "gráfico", "faça um gráfico", "não quero arquivo", "no chat", acentos, maiúsculas. - [ ] Tarefa 0.3 — Escrever teste de **integração de renderização** (Highcharts real em jsdom/headless): config → DOM com séries e plotBands. - [ ] Tarefa 0.4 — Adicionar `agent_trace` (persistência básica do turno) sem mudar o loop. - [ ] Tarefa 0.5 — Configurar CI (comando único `php tests` do módulo). **Entregável:** suíte rodando, trace básico gravado. **Aceite:** `phpunit` verde com ≥ 20 casos cobrindo as heurísticas; trace gravado a cada turno. **Teste:** rodar suíte em CI. ### Fase 1 — Prompt enxuto (1 semana) **Objetivo:** reduzir o systemPrompt para o essencial, sem perder comportamento. - [ ] Tarefa 1.1 — Reescrita do `systemPrompt()`: identidade + acesso do usuário + 3–5 regras de alto nível. - [ ] Tarefa 1.2 — Remover regras numeradas redundantes; mover detalhes para **descrição de ferramentas** e para o **modelo semântico**. - [ ] Tarefa 1.3 — Manter o gancho de `agent_treinamento` (conduta), mas validar que não conflita. - [ ] Tarefa 1.4 — Rodar **avaliação comparativa** (mesmas 20 perguntas na V1 vs V2) para medir regressão/ganho. **Entregável:** prompt reduzido (meta < 40% do tamanho atual). **Aceite:** respostas às perguntas de referência não pioram; erros de "regrinha solta" reduzem. **Teste:** suíte de avaliação manual/automatizada das 20 perguntas. ### Fase 2 — Consolidação de ferramentas (1–2 semanas) **Objetivo:** menos ferramentas, cada uma bem definida; remover do turno as de investigação de código. - [ ] Tarefa 2.1 — Remover `code_search`, `code_read`, `db_schema`, `knowledge_search` do registro de tools do turno. - [ ] Tarefa 2.2 — `perfil_desempenho` devolve config Highcharts pronta (categorias, séries, plotBands). - [ ] Tarefa 2.3 — `gerar_arquivo`: remover suporte a `png`; manter XLSX/PDF/DOCX/TXT para dados. - [ ] Tarefa 2.4 — Atualizar descrições das ferramentas (o modelo passa a confiar nelas). - [ ] Tarefa 2.5 — Testar loop com mock de LLM (sequência de tool calls determinística). **Entregável:** ferramentas consolidadas; gráfico só via inline. **Aceite:** o modelo usa `perfil_desempenho` → devolve config → widget renderiza inline (sem PNG). **Teste:** teste de integração do loop + renderização Highcharts. ### Fase 3 — Conhecimento semântico (2–3 semanas) **Objetivo:** substituir a mineração por regex por um modelo curado do domínio. - [ ] Tarefa 3.1 — Criar `agent_dominio` (entidades, relações, regras) com conteúdo curado (extraído manualmente/especialista, não por regex). - [ ] Tarefa 3.2 — Aposentar `CodeIndexer` (ou reduzir a auditoria) — parar de injetar trivia. - [ ] Tarefa 3.3 — Ferramenta interna (não exposta ao modelo) que resolve o domínio para o prompt/ferramentas. - [ ] Tarefa 3.4 — Validar perguntas de domínio ("o que é dimensão", "onde fica a regra X") com o novo modelo. - [ ] Tarefa 3.5 — Migrar/limpar `agent_knowledge` (opcional; pode virar tabela de auditoria). **Entregável:** conhecimento em `agent_dominio`; `CodeIndexer` desligado. **Aceite:** perguntas conceituais respondidas a partir do modelo curado; respostas de "regrinha solta" eliminadas. **Teste:** avaliação das perguntas conceituais. ### Fase 4 — Acesso por massa de dados (1 semana) **Objetivo:** IA consulta a massa real do usuário (não-admin), não só a tela. - [ ] Tarefa 4.1 — Consolidar a derivação já existente (clientes → contextos → projetos/coletas) no `AgentContext`. - [ ] Tarefa 4.2 — Testar não-admin: "quais minhas coletas?", "quais meus contextos?" sem abrir tela. - [ ] Tarefa 4.3 — Confirmar que o `TenantGuard` mantém isolamento (nenhum vazamento entre clientes). - [ ] Tarefa 4.4 — Testes de escopo (usuário com 1 cliente não vê dados de outro). **Entregável:** não-admin consulta a massa liberada; isolamento intacto. **Aceite:** perguntas amplas funcionam para não-admin; testes de vazamento passam. **Teste:** suíte de escopo/tenant. ### Fase 5 — Gráficos: fonte única inline (1 semana) **Objetivo:** eliminar o PNG feio; gráfico = Highcharts inline. - [ ] Tarefa 5.1 — Remover `gerarGrafico` GD e o branch de export externo. - [ ] Tarefa 5.2 — Garantir que o widget renderiza Highcharts (v4 compat: `new Highcharts.Chart({renderTo})`) com faixas. - [ ] Tarefa 5.3 — Fallback visual (tabela) se Highcharts indisponível. - [ ] Tarefa 5.4 — Teste de renderização real (headless) confirmando séries + plotBands no DOM. - [ ] Tarefa 5.5 — Remover referências a PNG do `GerarArquivoTool`/prompt. **Entregável:** gráfico sempre inline Highcharts; nenhum PNG de gráfico. **Aceite:** pedir "gráfico do perfil" → inline com faixas, idêntico ao estilo da tela. **Teste:** teste headless de renderização. ### Fase 6 — Observabilidade completa (1 semana) **Objetivo:** todo turno debuggável em < 1 min. - [ ] Tarefa 6.1 — Enriquecer `agent_trace`: mensagens, tool calls (args+resultado), síntese, modelo, tempo, erros. - [ ] Tarefa 6.2 — Endpoint `/agent/chat/trace?id=` (autenticado, dev). - [ ] Tarefa 6.3 — Log de negações de escopo (motivo exato) para auditar "por que não vi". **Entregável:** trace completo por turno + endpoint. **Aceite:** reproduzir resposta ruim → trace explica a causa em < 1 min. **Teste:** teste funcional do endpoint. ### Fase 7 — Avaliação contínua (contínua) **Objetivo:** qualidade mensurável, não subjetiva. - [ ] Tarefa 7.1 — Conjunto de avaliação curado (perguntas com resposta esperada) — base de `agent_feedback`. - [ ] Tarefa 7.2 — Rodar avaliação a cada mudança de prompt/modelo; métrica de acerto. - [ ] Tarefa 7.3 — Feedback (👍/👎) alimenta o conjunto de avaliação automaticamente. - [ ] Tarefa 7.4 — Revisar modelo (trocar `deepseek-v4-flash` por um mais capaz) se a avaliação estagnar. **Entregável:** métrica de qualidade do agente. **Aceite:** mudanças de prompt só entram se não piorarem a avaliação. **Teste:** avaliação automatizada. --- ## 5. Matriz de decisões (ADRs a escrever) | Decisão | V1 | V2 | Status | |---|---|---|---| | Engine de gráfico | GD + export + inline | **Inline Highcharts (única)** | proposta | | Conhecimento | CodeIndexer (regex) | **Modelo semântico curado** | proposta | | Prompt | Gigante, regras imperativas | **Enxuto, ferramentas bem descritas** | proposta | | Acesso | Só "ids da tela" | **Massa de dados do usuário + guard** | parcial (derivação já existe) | | Ferramentas | 11 (incl. investigação de código) | **Menos, especializadas** | proposta | | PNG de gráfico | Sim (GD) | **Não (inline)** | proposta | | Testes | Manual no navegador | **Automático (PHPUnit + headless)** | proposta | --- ## 6. Métricas de sucesso da V2 - **Tempo de diagnóstico de resposta ruim:** de "horas/dias" para < 1 minuto (via trace). - **Taxa de acerto na avaliação curada:** medir baseline na Fase 0, melhorar ou manter. - **Falsos "acesso negado":** reduzir a zero para dados do escopo do usuário. - **Gráfico:** sempre inline, sem PNG; visual consistente com o sistema. - **Bugs de regressão:** pegos pela suíte, não no navegador. --- ## 7. Riscos e mitigação | Risco | Impacto | Mitigação | |---|---|---| | Reduzir ferramentas degrada respostas de investigação | Alto | Manter acesso offline ao domínio; avaliar 20 perguntas antes/depois | | Modelo pequeno não acompanha prompt enxuto | Médio | Revisar modelo (Fase 7.4); avaliação contínua | | Remover PNG quebra fluxo existente | Médio | Fallback visual = tabela; migração por fase | | Derivação de massa de dados vaza tenant | Alto | Testes de isolamento obrigatórios (Fase 4.4) | | Reescrever sem testar repete erros da V1 | Alto | Fase 0 primeiro; toda fase com teste obrigatório | --- ## 8. Próximos passos imediatos (sugestão) 1. **Validar este documento** com a equipe (aprovar princípios e ordem das fases). 2. **Iniciar Fase 0** (baseline + testes) — é o alicerce e não depende de decisões de design. 3. **Decidir ADR de gráficos** (Fase 5) — maior impacto visual percebido pelo usuário. 4. **Definir "pronto" para cada fase** (critério de aceite acima) antes de começar.