mnemiq

mnemiq

Text-to-SQL que você pode ajustar ao seu banco de dados. /NEM-ik/ — o "m" é silencioso, como em mnemônico.

Um mecanismo de código aberto que responde a perguntas em linguagem natural sobre o seu banco de dados, construído para que cada etapa entre a pergunta e o SQL seja uma configuração que você pode ler, alterar e medir.

Duas respostas e uma recusa. A terceira pergunta pede receita que o banco de dados não possui, e o mecanismo diz isso — nomeando as colunas de que precisaria — em vez de retornar um número que parece correto. Essa distinção é todo o design.

Leia mais · Artigo de lançamento · Relatório técnico (PDF) · Artigo (PDF) · beacon — o avaliador e o rastreador de resultados

Por que o mnemiq existe

Todo produto de text-to-SQL tem um número de precisão. Quase nenhum deles foi medido em um banco de dados que se parece com o seu.

Um sistema pode ter um bom desempenho em um benchmark e depois ter dificuldades no seu warehouse porque o esquema é maior, a nomenclatura é diferente, as definições de negócios vivem na cabeça das pessoas, ou a configuração que serviu para o benchmark simplesmente não serve para os seus dados. Quando tem desempenho inferior, um sistema fechado não lhe dá nenhuma maneira de descobrir o porquê, e nada para mudar.

Portanto, a pergunta que vale a pena fazer não é quão preciso ele é. É:

Qual será o desempenho disso no meu banco de dados — e o que posso mudar se não funcionar?

O mnemiq é construído para tornar ambas as metades respondíveis. Ele é Apache-2.0, roda dentro do seu próprio ambiente em modelos que você escolhe, e expõe as principais partes do pipeline como configurações em vez de detalhes internos. Nenhum número de precisão se aplica ao seu banco de dados até que você o execute no seu banco de dados; o mnemiq é o mecanismo e a estrutura de avaliação para fazer isso.

Como funciona

O mnemiq separa escrever SQL de decidir executá-lo. Um modelo propõe uma consulta. Uma camada determinística então decide sobre ela antes que qualquer coisa toque o banco de dados. A consulta tem que ser somente leitura, pode apenas referenciar objetos que o chamador tem permissão de ver, tem que compilar no dialeto SQL do próprio source, e tem que sobreviver a um EXPLAIN. Falhe em qualquer um desses e você recebe uma recusa com um motivo declarado em vez de um número plausível.

Duas propriedades decorrem dessa ordenação. As permissões se aplicam antes da recuperação do esquema, então o modelo nunca vê uma tabela que o chamador não pode ver — nomeá-la é inútil em vez de recusado. E cada resposta carrega um rastro: o SQL que foi executado, as tabelas que tocou, a versão de enriquecimento por trás dele.

Leia o diagrama da esquerda para a direita, de cima para baixo. Os estágios em vermelho são os que podem parar uma resposta: o decisor recusa ou repara, a execução roda sob política, e a verificação pode adiar. O modelo aparece uma vez, no estágio 05, e tudo ao redor dele é determinístico.

O pipeline é configurações, não detalhes internos

As partes que as pessoas geralmente não conseguem alcançar são as partes que o mnemiq coloca em suas mãos:

• Qual modelo escreve o SQL — hospedado ou local, um candidato ou vários.
• Quanto contexto de esquema é recuperado, e como é classificado.
• Quanto enriquecimento semântico é construído, e se um humano o certifica.
• Quão agressivamente o sistema recusa — o verificador e seu limite.
• O que o decisor impõe, incluindo política de linhas e colunas aplicada à árvore de consulta em vez de solicitada ao modelo.

Cada um desses é um dial com um custo do outro lado, que é por que são dials e não padrões. Mais contexto não é gratuito. Mais computação não é automaticamente melhor. A configuração certa depende dos seus dados, e o objetivo da estrutura é que você possa descobrir em vez de adivinhar.

A camada semântica tem níveis

Antes que qualquer pergunta seja feita, o mnemiq pode inspecionar o banco de dados e construir contexto ao redor do esquema:

• Nível 0 — apenas tabelas e colunas.
• Nível 1 — adiciona informações estruturais: chaves primárias e estrangeiras, perfilamento, distribuições de valores.
• Nível 2 — adiciona significado que um LLM propõe: descrições de tabelas e colunas, granularidade, termos de glossário, significados de valores codificados.

O enriquecimento é um multiplicador de significado que já não está no esquema. Onde os nomes das colunas já dizem o que contêm, cartões mais ricos adicionam comprimento sem adicionar sinal. Onde três colunas são todas chamadas de receita por três equipes diferentes, o significado está em uma pessoa, não no esquema — e isso é exatamente o que uma definição certificada captura. Para uso em produção, as definições podem ser revisadas e certificadas por um proprietário nomeado, e o dicionário do operador substitui tudo que o modelo propôs.

Códigos são fundamentados ou deixados nus, nunca adivinhados. E11 ou NC-17 tiram seu significado dos dados em si, de um sistema de código padrão (TTL/SKOS/OWL), ou de um dicionário escrito à mão, com a fonte registrada. Sem evidência, sem significado. Veja docs/grounding.md.

Meça no seu próprio banco de dados

A estrutura de avaliação faz parte do mecanismo, não um projeto de pesquisa separado. Ela executa um conjunto de perguntas contra uma configuração, avalia resultados pelos dados retornados em vez de correspondência de strings do SQL, e relata certo, recusado e errado como três números separados — porque um sistema pode comprar precisão respondendo com menos frequência, e uma única figura esconde isso.

Uma primeira passagem útil, nos seus dados:

• Pegue uma fatia significativa do seu esquema, não o warehouse inteiro.
• Escreva 20–30 perguntas que as pessoas realmente fazem, e marque cada uma: respondível a partir de nomes de colunas, precisa de uma definição, deve ser recusada.
• Execute com enriquecimento ligado e desligado, um modelo local e um hospedado, o verificador em dois limites.
• Leia o resultado por marcação. As marcações são o diagnóstico: se as perguntas da faixa de definição falharem enquanto as da faixa de esquema passarem, você tem um problema de glossário e a documentação se pagará sozinha. Se ambas já passarem, você estava prestes a gastar um trimestre em algo que vale muito pouco.

A mesma estrutura executa os benchmarks públicos (BIRD mini-dev, Spider 1.0, Spider 2.0-lite) e os scripts de comparação de warehouse sob scripts/, então a configuração que você usa nos seus dados é a configuração de onde os números publicados vieram.

A avaliação em si vive em beacon, um repositório separado Apache-2.0: o avaliador que decide o que conta como correto, e o rastreador que guarda cada execução por trás das figuras publicadas. Mantê-lo fora do mecanismo é deliberado — um sistema não deve corrigir sua própria lição de casa, e o mesmo avaliador pontua mnemiq, Snowflake Cortex Analyst e Databricks Genie na comparação. Resultados por pergunta são publicados lá, então um número no artigo de lançamento pode ser rastreado até o SQL e as linhas que o produziram.

Início rápido

Roda em um clone limpo sem banco de dados próprio e sem Docker. A etapa de seed escreve um pequeno banco de dados SQLite mais seu manifesto de source e política de acesso sob demo/.

uv sync
uv run python scripts/seed_demo.py

export MNEMIQ_LLM_BASE_URL=...  MNEMIQ_LLM_API_KEY=...  MNEMIQ_LLM_MODEL=...
export MNEMIQ_SOURCES_PATH=demo/sources.json
export MNEMIQ_AUTHZ_PATH=demo/authz.json
export MNEMIQ_STORE_PATH=demo/store.duckdb

uv run mnemiq enrich      # profile + describe the schema  (~30 s on the demo's 4 tables)
uv run mnemiq build       # index it for retrieval          (~2 s)
uv run mnemiq ask "how many customers are there by country?" --roles analyst

uv sync puxa cerca de 230 MB de dependências em uma primeira execução — DuckDB, PyArrow e o cliente OpenAI são a maior parte — então dê um minuto em uma conexão normal. É quase instantâneo em qualquer checkout subsequente, já que o uv armazena wheels em cache globalmente.

mnemiq enrich é a única etapa lenta: ela perfila cada coluna e faz uma passagem de LLM sobre o esquema, então espere cerca de 30 segundos para as quatro tabelas da demo e mais em proporção às suas próprias. Ela não imprime nada até que cada tabela complete — está trabalhando, não travada. O resultado é armazenado em cache, então você paga uma vez por esquema em vez de por pergunta.

Mais duas que valem a pena tentar, porque mostram as partes que não são o modelo:

uv run mnemiq ask "how many enterprise customers are there?" --roles analyst
uv run mnemiq ask "what was our total revenue last quarter?"   --roles analyst

A primeira junta através de uma tabela de lookup para resolver uma coluna codificada — segment_cd contém A/B/C e nada no nome diz "enterprise". A segunda é recusada: o esquema da demo não tem coluna de preço ou receita, e o mecanismo diz isso em vez de retornar um número.

O acesso é fail-closed. --roles analyst é obrigatório — sem um papel o mecanismo não concede nada e adia, que é o comportamento correto e a primeira coisa que as pessoas confundem com um bug. Sem política, sem concessões, sem snapshot — sem dados.

Quais endpoints de LLM funcionam

Qualquer endpoint /v1 compatível com OpenAI. O mnemiq fala com MNEMIQ_LLM_BASE_URL através do cliente OpenAI padrão, então vLLM, Ollama, o servidor do llama.cpp, LM Studio, gateways de fornecedores e as APIs hospedadas funcionam — defina a URL base, uma chave (qualquer string não vazia para servidores locais que a ignoram) e um nome de modelo. Nada sobre o mecanismo assume um provedor hospedado, que é o que "roda dentro do seu perímetro" significa na prática: aponte para um servidor local e nenhum esquema, nenhuma pergunta e nenhuma linha jamais sai da sua rede. Embeddings seguem a mesma configuração, ou as suas próprias via MNEMIQ_EMBED_*.

Use de um navegador (workbench)

cd workbench && pnpm install && pnpm build
uv run mnemiq serve --http     # http://127.0.0.1:8080

Um processo serve tanto o workbench quanto a API HTTP — POST /v1/ask (JSON), POST /v1/chat (SSE, vocabulário de eventos AG-UI), GET /v1/schema. Cada resposta mostra o SQL que a produziu e as tabelas que leu; uma pergunta que os dados não podem suportar volta como um motivo declarado, não um palpite — essa é a interface retratada no topo deste arquivo. Veja workbench/README.md.

Use de um agente de IA (MCP)

uv run mnemiq serve expõe duas ferramentas somente leitura, com escopo de acesso, via stdio — db_read(question) (resposta + SQL + rastro) e get_schema(). Aponte qualquer cliente MCP para ele:

{ "mcpServers": { "mnemiq": { "command": "mnemiq", "args": ["serve"] } } }

Sources

Postgres, SQLite, DuckDB, Oracle, Snowflake e Databricks, com DuckDB como executor universal. O modelo semântico (mnemiq-contract) é aberto, e importação/exportação dbt-semantic-interfaces vem com ele.

Implantando contra Oracle

O plano de leitura do Oracle recusa escritas, mas essa recusa é em parte uma propriedade da sua implantação em vez do mecanismo: um SELECT pode alcançar uma função AUTONOMOUS_TRANSACTION através de uma view, e restringir o chamador não fecha isso, porque uma view resolve suas referências com os direitos do proprietário da view. Apontar o plano de leitura para um banco de dados que está aberto somente leitura fecha isso, medido, e o mnemiq relata na inicialização se você está nessa implantação ou apoiado apenas na porta do mecanismo. Veja docs/oracle-deployment.md antes de conectar um source de produção.

O que é comercial

O mecanismo é Apache-2.0 e sempre será — enriquecimento incluído. Nada aqui é um build com tempo limitado ou com recursos limitados, e nenhuma capacidade é removida pendente de uma chave de licença.

Especificamente aberto, porque essas são as partes que as pessoas assumem que são retidas: o pipeline de enriquecimento incluindo a passagem de LLM e a fundamentação de valores codificados (src/mnemiq/enrichment/), o verificador e seu juiz (src/mnemiq/verify/), as verificações de acesso (src/mnemiq/authz/, src/mnemiq/sql/), o avaliador de resultados (src/mnemiq/eval/grade.py), e a estrutura de benchmark que produziu os números publicados (scripts/).

Comerciais são duas coisas que ficam ao redor do mecanismo em vez de dentro dele: Verity, um serviço gerenciado de avaliação e deriva, e o plano de controle Agentic Fabriq — identidade, credenciais cofradas, concessões por grupo e auditoria em muitas fontes. Ambos falam com o mecanismo através do contrato aberto (mnemiq-contract), então uma implantação auto-hospedada não é uma degradada; é o mesmo caminho de leitura sem um serviço gerenciado na frente dele.

Leia o código em vez de confiar nisso — esse é o ponto de enviá-lo.

Fraquezas conhecidas

Registrados como issues em aberto em vez de deixados para serem descobertos, porque são legíveis no código-fonte de qualquer forma: o verificador falha aberto quando seu juiz está inacessível, a verificação está desativada por padrão apesar de ser a única alavanca medida para reduzir a taxa de erro, MNEMIQ_ROLES é ignorado pela CLI, e relatórios de linhagem unconfirmed-function-identity em consultas comuns. Contribuições e argumentos são bem-vindos em todos os quatro.

Status

v0.1: o caminho completo de leitura — enriquecimento, recuperação, o decisor, execução, rastreamento — avaliado em ACME, BIRD mini-dev, Spider 1.0 e Spider 2.0-lite, com um programa de modelo local junto. Modos em camadas (instant / thinking / deep), segurança em nível de linha e coluna, o caminho de escrita governado, federação entre fontes e implantação com múltiplas réplicas são construídos e conectados por trás das mesmas interfaces. Próximos: adaptadores de fonte adicionais, os loops de automanutenção e o endurecimento do plano de escrita contra uma fonte de produção.