Selo
- Motor: Usa LLM (Anthropic)
- Maturidade: Preview
- Medição: NOT_MEASURED (qualidade/latência de IA real em produção)
1. O que faz
Você descreve em português o que quer ver ("faturamento por mês do último ano") e a IA propõe uma consulta SQL somente-leitura para o seu datalake, com uma explicação em português e uma estimativa de custo/bytes.
2. Determinístico ou LLM?
LLM. O modelo é resolvido assim:
- O provedor de modelo é configurado por nós no ambiente; nenhuma credencial de IA é pedida a você.
- Quando não há credencial direta, o acesso ao modelo passa por um gateway gerenciado
(
anthropic/claude-sonnet-5). - Sem nenhum provider, em dev/preview cai num gerador mock determinístico (heurística simples que casa termos da pergunta com o schema). Em produção, sem provider, a rota responde 503 em vez de fingir um resultado (guarda de produção).
3. Dados enviados e egress
Vai para o LLM, dentro de um fence de dado não confiável (<dados id="...">):
- O schema do seu catálogo — nomes de tabelas e colunas das camadas silver e gold do seu workspace. Colunas marcadas como PII são excluídas antes de montar o prompt — a IA nem sabe que existem.
- A sua pergunta, fenceada como
<dados id="pergunta">. - No caminho semântico (quando há um modelo semântico publicado), vai o modelo (ids de tabelas/relações/medidas) em vez das colunas cruas.
Não vão linhas de dados. O text-to-SQL envia apenas estrutura (schema/modelo), nunca o conteúdo das tabelas. Uma guarda de workspace descarta qualquer tabela cujo nome não comece com o prefixo do seu workspace, mesmo que o catálogo estivesse corrompido.
4. Privacidade e retenção
- PII do catálogo não sai (exclusão na origem, antes de montar o prompt).
- Todo texto do cliente (pergunta, nomes de tabela) entra fenceado e com os tokens de fence neutralizados — é a defesa contra prompt injection (coberta por suíte adversarial).
- O uso (modelo, tokens, custo em R$, resumo de egress: nº de tabelas do schema, 0
linhas) é registrado no registro de auditoria com ação
ai.usage, escopado por workspace.
5. Tokens, custo e orçamento
- Antes da chamada, o produto reserva o orçamento estimado (
ai.reserva) e só então verifica o teto (padrão reserve-then-verify — concorrência não fura o teto). Depois da chamada, liquida com o custo real (ai.usage+ai.reserva_liquidada). - Teto mensal por workspace (padrão R$ 50/mês; sem teto quando zerado =
sem teto). Estourou → a chamada é recusada com mensagem clara e registrada em
ai.blocked. - Guarda de custo da própria consulta: estimativa de bytes/custo por dry-run real no datalake, e a consulta é validada antes de rodar.
- Detalhes em Privacidade, envio externo, orçamento e desligamento.
6. Como ligar, quem pode usar e como desligar
A rota POST /api/ai/sql só chama o provider depois de passar, nesta ordem:
- Rate limit 20 req/60 s por IP, fail-closed (cache gerenciado fora → nega).
- Workspace obrigatório (401 sem workspace).
- Entitlement
aiNarrative— disponível a partir do plano Pro (403 abaixo disso). - Verificação de acesso a verificação de workspace ativo — inadimplência/suspensão barra (402/403).
- Verificação de capacidade consulta em linguagem natural — chave de desligamento ortogonal ao dinheiro.
Desligamento geral: o envio a provedores de modelo pode ser desligado no ambiente; nesse estado nenhuma chamada a LLM acontece, mesmo com credencial configurada configurada — o text-to-SQL cai no mock determinístico e nada sai do produto.
7. Recusas
A IA não inventa:
- Ambiguidade (caminho semântico): se um termo da pergunta casa com ≥2 medidas/colunas, ela recusa antes de gastar token, listando as opções ("qual você quis dizer?").
- Ids inválidos (caminho semântico): se a resposta cita um identificador que não existe no modelo publicado, a consulta é descartada (SQL sem fundamento não sai) — o custo do token já gasto é liquidado com honestidade.
- Teto atingido → 429 com mensagem, sem gastar.
8. Limitações e ausência de causalidade
- Gera apenas
SELECT(sem DML/DDL). Mesmo assim, revise antes de confiar: a IA pode errar nome de coluna/tabela — por isso há auto-correção (um retry com o erro real do datalake), mas ela não é garantia. - A explicação descreve o que a consulta faz, não afirma relações de causa e efeito nos seus dados.
- No modo demo (sem provider), o SQL vem de heurística simples — serve para experimentar, não para produção.
9. Como validar
- Desligamento: com o envio a provedores desligado, confirme que a resposta vem do resultado determinístico (explicação diz "modo de demonstração") e que nenhuma chamada externa ocorre.
- PII fora do prompt: marque uma coluna como PII no catálogo e confira que ela não aparece no schema enviado à IA.
- Anti-injeção: escreva na pergunta um texto que tente "fechar" o fence e dar ordens à IA, e confirme que ela o trata como dado, não como instrução.
- Recusa por ambiguidade/ids: com um modelo semântico publicado, faça uma pergunta ambígua e confira a recusa (sem SQL).
- Orçamento: verifique no registro de auditoria do workspace os pares
ai.reserva/ai.reserva_liquidadae oai.usagecom custo.