Arquitetura — Copilot e LLM

A IA do DATTA não é uma tela à parte: ela está embutida onde o trabalho acontece — sugerindo a fórmula enquanto você edita um gráfico, respondendo perguntas sobre o dashboard aberto, escrevendo a narrativa do relatório, apontando o que merece atenção antes de você perguntar e processando colunas inteiras dentro dos pipelines. Esta página descreve como essas quatro superfícies são montadas, o que cada uma envia ao modelo, onde está o cache e quais limites protegem a plataforma.

1. As peças

Quando cada superfície entra

2. Copilot em tempo de edição (barra DATTAX.AI)

O analista edita um gráfico, digita na barra "adiciona percentual vs ano anterior" e a plataforma:

1. Monta o prompt com o DATTAX atual do gráfico, o schema do dataset e a intenção descrita.
2. Encaminha ao roteamento de modelos, que resolve para o vLLM local.
3. Recebe o DATTAX sugerido.
4. Exibe a diferença lado a lado — quem aceita ou rejeita é o usuário.

O prompt de sistema é direto: "Você é um assistente DATTAX. Retorne SOMENTE DATTAX válido. Não inclua markdown.", seguido do contexto de schema.

O desenho prevê que a saída seja validada antes de chegar à tela, falhando com mensagem em português quando o modelo devolve algo inválido. Esse validador ainda não está implementado — é intenção de design registrada para a fase F10. Hoje a proteção efetiva é o próprio diff: nada entra no gráfico sem o aceite explícito do usuário.

3. Copilot do dashboard ("Perguntar ao dashboard")

O fluxo

1. O usuário abre um dashboard publicado e o copilot aparece na barra superior.
2. Ele digita a pergunta — "Qual região cresceu mais em Q1?".
3. Antes de qualquer coisa, a plataforma valida o acesso: guarda contra IDOR que nega a pergunta se o usuário não for dono do dashboard, não tiver compartilhamento nem apresentar token público válido.
4. O limite de uso é consumido: 20 perguntas por minuto e 200 por hora, por usuário.
5. O contexto é montado: para cada gráfico, a plataforma pega o último render em cache (datta:dattabi:chart:<id>:render) ou força um render novo, e concatena os metadados (título, tipo, DATTAX) com uma amostra de dados de até 1 KB por gráfico.
6. O prompt final tem a forma Pergunta: … seguida de Contexto: com o JSON montado, e a resposta é transmitida por streaming.
7. Se o modelo acionar a ferramenta dattax.execute, a consulta é executada no motor DATTAX e o resultado volta ao modelo para compor a resposta.

As ferramentas expostas ao modelo

Cada ferramenta tem schema JSON documentado; modelos com suporte a function-calling podem invocá-las.

Cache e limites

• Contexto do dashboard: datta:dattabi:copilot:ctx:<dashboardId>, TTL de 2 minutos.
• Limite de uso: datta:dattabi:copilot:rl:<user>:min e :hour.

4. Narrativa executiva

Quando roda: na exportação de PDF com a opção de narrativa marcada (includeNarrative=true).

Estilos disponíveis:

Cada estilo tem seu prompt de sistema no repositório de prompts. A narrativa é cacheada em datta:dattabi:dashboard:narrative:<dashId>:<style>:<hash>, onde o hash é o conteúdo dos renders — ou seja, atualizar os dados invalida a narrativa automaticamente.

Se a IA estiver indisponível, o PDF sai sem a narrativa, acompanhado de mensagem explicativa. O relatório nunca fica travado.

5. Sugestões proativas

Ao abrir o dashboard, a plataforma dispara uma análise assíncrona à procura de outliers, tendências e correlações. Quando o achado passa do limiar configurado, o modelo é chamado apenas para redigi-lo em português natural, no espírito "você sabia que…?", e a sugestão aparece na barra superior.

O resultado é cacheado em datta:dattabi:dashboard:suggestions:<dashId>:<hash> e o usuário pode dispensar a sugestão permanentemente para aquele dashboard.

6. Primitivas de IA no DATTAX

Executadas dentro do motor DATTAX, processam colunas inteiras no pipeline:

LLM EXTRACT FROM <col> INTO {schema}    -- extração dirigida por schema
LLM CLASSIFY FROM <col> LABELS [...]    -- classificação multi-rótulo
LLM EMBED FROM <col> MODEL "..."        -- geração de embeddings

Como o executor se comporta

• Processa em lotes de N linhas por requisição (padrão 20).
• Timeout de 30 segundos por lote.
• Retry exponencial em 429 e 5xx.
• Valida a resposta contra o schema antes de injetá-la no resultado.
• Reaproveita respostas já calculadas pelo cache datta:dattax:llm:<primitive>:<hash>, com chave por hash do texto mais o modelo — o mesmo texto não é pago duas vezes.

Cotas

O consumo de IA tem limite diário e mensal por usuário, verificado antes da execução. Os custos são acumulados no cache da plataforma e o painel administrativo de cotas mostra o detalhamento por usuário.

7. vLLM local e alternativa em nuvem

Stack local: os modelos padrão são Qwen3-30B-A3B-Instruct e DeepSeek-Coder-V2-Lite, mais o modelo ativo de embeddings. A implantação usa GPUs quando disponíveis, ou somente CPU para os modelos menores, e expõe um endpoint compatível com a API OpenAI em http://vllm:8000/v1.

Alternativa em nuvem: GEMINI_API_KEY ou OPENAI_API_KEY, guardadas como segredo da instalação — sempre opcionais. A camada de acesso aos modelos escolhe o destino por três critérios:

1. disponibilidade do modelo local;
2. preferência do administrador (por tenant);
3. falha — que aciona a alternativa.

Requisito de arquitetura (Diretrizes do Projeto §6): a plataforma tem de funcionar com as chaves de nuvem vazias.

8. RAG no chat

Para o Chat principal — não para o copilot do dashboard:

• A plataforma gera embeddings dos documentos e das consultas com o modelo ativo.
• A recuperação é por busca vetorial (KNN) no índice datta-rag-docs.
• Os top-K trechos recuperados são injetados no prompt.
• Uma ferramenta permite ao modelo buscar metadados do catálogo.

O copilot do dashboard não usa RAG externo: seu contexto é estritamente o do painel aberto. É uma decisão de escopo, não uma limitação temporária.

9. Observabilidade

Eventos de auditoria: COPILOT.ASK, COPILOT.NARRATIVE e LLM.QUOTA_EXCEEDED. O rastreamento distribuído cobre a cadeia inteira — há um span por requisição, do clique até a chamada ao modelo.

10. Segurança

• IDOR: a guarda de acesso ao dashboard roda em toda interação do copilot, sem exceção.
• Dados pessoais: o prompt instrui o modelo a recusar campos marcados com pii=true.
• Prompt injection: a entrada passa por sanitização antes de chegar ao modelo (remoção de marcações do tipo <|…|>).
• Limite de uso: por usuário, nas superfícies interativas e nas cotas de pipeline.
• Auditoria: cada interação é registrada.

Detalhes em segurança da plataforma.

11. Referências

• Guia do usuário do DATTA BI, seção de Copilot: DATTABI — Guia do Usuário.
• Endpoints de conversa, modelos e copilot: referência de API.