🇧🇷 Glancer — Converse com seu banco de dados Rails em linguagem natural

Uma engine Rails que permite consultar o banco de dados com linguagem natural, usando RAG e LLMs. Sem precisar escrever código.

Todo projeto Rails chega num ponto em que alguém do time (produto, suporte, gestão, etc.) precisa de um dado, mas ninguém tem tempo de parar para compreender a necessidade e escrever uma query. A mensagem no Slack, o card aberto, o pedido de CSV que some no backlog. Quem nunca.

Foi isso que me fez pensar no Glancer.

O que é

Glancer é uma engine Ruby on Rails que monta uma interface de chat em /glancer dentro da sua aplicação. Você digita uma pergunta em linguagem natural, ele busca o contexto relevante do sistema, gera um SELECT (ou uma expressão ActiveRecord), valida, executa com segurança e retorna o resultado.

"Quantos pedidos foram feitos nos últimos 30 dias, agrupados por status?"
→ SELECT executado, resultados exibidos, resposta escrita em português.

A inspiração direta foi o Blazer, uma gem que já usei bastante. A ideia aqui é dar um passo a mais: em vez de escrever o SQL, você só pergunta.

Como começar

Adicione no Gemfile:

gem "glancer"

Execute o gerador:

rails generate glancer:install
rails db:migrate
rails glancer:index:all

Acesse /glancer e comece a perguntar.

O gerador cria um initializer onde você configura o provider de LLM. Uma configuração mínima com Gemini:

Glancer.configure do |config|
  config.llm_provider   = :gemini
  config.llm_model      = "gemini-2.0-flash"
  config.gemini_api_key = ENV["GEMINI_API_KEY"]
  config.schema_permission = true
end

OpenAI e OpenRouter também são suportados. Ela roda em cima do RubyLLM então os modelos que ele suportar, o Glancer suportará. Dá para usar modelos diferentes por papel, por exemplo, um modelo mais capaz para gerar a query e um mais barato para escrever a resposta.

O que ele faz

Alguns pontos que vale conhecer:

Segurança por padrão: Toda query roda dentro de uma transaction que sempre faz rollback. Um blocklist de palavras rejeita DELETE, UPDATE, INSERT, DROP e afins antes mesmo de chegar no executor. Também é possível apontar para uma réplica de leitura.

Sem infraestrutura adicional: Os embeddings ficam no seu banco existente, numa coluna JSON. Sem Pinecone, sem Weaviate, sem nada extra para subir. Raramente será muita coisa, por isso essa abordagem.

Ensina o contexto do seu negócio. Você coloca um arquivo Markdown em config/glancer/llm_context.glancer.md e explica as regras do domínio: o que os valores de status significam, como a receita é calculada, quais colunas/tabelas/modelos ignorar, etc:

- `orders.status`: "pending" | "paid" | "shipped" | "refunded"
- Receita mensal = SUM(orders.total) WHERE status = "paid"
- Para perguntas sobre "churn", usar a coluna `churned_at` em `subscriptions`

Informações adicionais mais dinâmicas podem ser adicionadas em um campo texto nas configurações. Entretanto, não será gerado embedding disso pois será utilizado de contexto ao modelo base.

A interface tem uns detalhes legais. Os resultados aparecem em tabela com export CSV de um clique. Gráficos são gerados automaticamente quando fazem sentido. O processo de execução foi pensado para não travar a thread principal da aplicação. Dá para digitar @nome_da_tabela para fixar e ser mais assertivo sobre uma tabela específica na pergunta, editar o SQL gerado e reexecutar, e até ditar a pergunta pelo microfone. Tem também um visualizador de schema em /glancer/db-schema.

Integração com Blazer. Se você já usa o Blazer, o Glancer mostra um botão para abrir o SQL gerado direto lá.

A história por trás

Comecei isso como projeto de estudo. Estudei bastante sobre RAG e LLMs ao longo do ano passado e quando a ideia surgiu eu nunca tinha publicado uma gem antes e queria experimentar o processo completo, de engine a gemspec a CI. Com isso, juntei o útil ao agradável. Como mostrei para alguns colegas e eles acharam útil, então decidi abrir para a comunidade.

Atualmente está na versão 1.0.0.

Se você testar, adoraria saber o que achou, seja sobre o código ou sobre a ideia. Issues e pull requests são bem-vindos.

Se gostar do projeto, uma estrela no repositório ajuda bastante a divulgar para mais pessoas da comunidade.

GitHub: https://github.com/ErnaneJ/glancer
RubyGems: https://rubygems.org/gems/glancer