WrenAI é uma plataforma de código aberto projetada para transformar a forma como organizações interagem com dados empresariais. Em vez de exigir conhecimento especializado em SQL ou ferramentas de BI tradicionais, ela permite que usuários finais formulem perguntas em linguagem natural — e recebam respostas estruturadas, executáveis e governadas diretamente de múltiplas fontes de dados.

Arquitetura em Camadas: Separação Estratégica de Responsabilidades

O projeto adota um modelo arquitetônico de três camadas, cada uma com responsabilidades bem definidas:

• Camada de Aplicação: Interface com agentes de IA (ex.: LLMs integrados via API), dashboards personalizados e clientes web/mobile.
• Camada de Contexto Aberto: Núcleo inteligente que gerencia modelos semânticos, memória vetorial, políticas de acesso e geração de SQL contextualizada.
• Camada de Conectividade de Dados: Suporte nativo para mais de vinte sistemas — incluindo PostgreSQL, Snowflake, BigQuery, DuckDB, Redshift, Trino e bancos de dados baseados em arquivos (CSV/Parquet).

Essa separação permite atualizações independentes: por exemplo, substituir um modelo de embedding sem alterar o conector de banco de dados, ou aplicar novas regras de governança sem impactar os serviços de inferência.

Componentes-Chave e Implementação Prática

Sistema de Modelagem Semântica (MDL)

A linguagem de modelagem declarativa — chamada WrenMDL — é definida em YAML e armazenada no diretório schemas/. Ela descreve entidades, relações, métricas calculadas e hierarquias de agregação. Exemplo simplificado:

models:
  - name: sales_summary
    description: "Resumo diário de vendas por categoria"
    base_table: sales
    columns:
      - name: date
        type: DATE
        expression: "sale_date::DATE"
      - name: category
        type: STRING
        expression: "product_category"
      - name: revenue
        type: DECIMAL
        expression: "SUM(sale_amount)"
    group_by: [date, category]
    filters:
      - condition: "status = 'completed'"

O motor de análise interpreta esse modelo para gerar consultas SQL otimizadas, com tratamento automático de junções, filtros e agregações — eliminando erros comuns de escopo de agregação.

Mecanismo de Memória Vetorial

Em vez de depender exclusivamente de prompts estáticos, o sistema usa um índice vetorial persistente (baseado em LanceDB) para recuperar fragmentos relevantes de esquema, histórico de consultas e definições de negócio. A configuração padrão inclui:

• Modelo de embedding: text-embedding-3-small
• Limiar mínimo de similaridade: 0.68
• Número máximo de resultados retornados: 8
• Reclassificação pós-recuperação ativada por padrão

Isso permite que o sistema "lembre" não apenas o que foi perguntado enteriormente, mas também o contexto implícito — como preferências de granularidade ou convenções de nomenclatura usadas por determinada equipe.

Controle de Acesso Baseado em Políticas

O módulo de governança aplica restrições em tempo de execução, com suporte a:

• Visibilidade de colunas por perfil de usuário (ex.: analistas veem customer_email, mas não customer_ssn)
• Filtros dinâmicos automáticos (ex.: todos os usuários da região "Brasil" têm WHERE country = 'BR' injetado implicitamente)
• Logs detalhados de todas as consultas executadas, com identificação de usuário, fonte de dados, tempo de resposta e SQL gerado

As políticas são escritas em Python dentro de policies/ e carregadas como módulos plugáveis — facilitando testes unitários e versionamento independente.

Implantação em Ambientes Reais

Execução Local com Docker Compose

Para validação rápida, o repositório fornece um ambiente pré-configurado:

# Clonar e inicializar
git clone https://github.com/Canner/WrenAI
cd WrenAI

# Iniciar serviços (PostgreSQL + LanceDB + API)
docker compose up -d --build

# Carregar modelo semântico de exemplo
curl -X POST http://localhost:3000/v1/models \
  -H "Content-Type: application/yaml" \
  -d @examples/sample_mdl.yaml

Implantação em Produção com Kubernetes

Um manifesto básico de Deployment inclui tolerância a falhas, limites de recursos e integração com segredos externos:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: wrenai-api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: wrenai-api
  template:
    metadata:
      labels:
        app: wrenai-api
    spec:
      containers:
      - name: api-server
        image: ghcr.io/canner/wrenai:0.7.2
        ports:
        - containerPort: 3000
        envFrom:
        - secretRef:
            name: wrenai-prod-secrets
        resources:
          requests:
            memory: "512Mi"
            cpu: "250m"
          limits:
            memory: "2Gi"
            cpu: "1000m"

Otimizações de Desempenho Avançadas

Cache Estratificado

O sistema emprega dois níveis de cache:

• Cache de consultas SQL: armazena resultados brutos com TTL configurável (padrão: 1 hora), ideal para relatórios recorrentes.
• Cache de embeddings: evita recomputação de representações vetoriais de esquemas estáticos (TTL padrão: 24 horas).

Configuração em config.yaml:

cache:
  sql_results:
    enabled: true
    ttl_seconds: 3600
    max_entries: 5000
  embeddings:
    enabled: true
    ttl_seconds: 86400
    max_entries: 2000

Monitoramento com Métricas OpenMetrics

Todas as instâncias expõem endpoints Prometheus em /metrics. Principais métricas disponíveis:

• wrenai_query_duration_seconds_bucket — latência de execução por percentil
• wrenai_sql_generation_success_total — taxa de sucesso na geração de SQL
• wrenai_vector_search_hits_total — número de correspondências válidas em buscas semânticas
• wrenai_cache_hit_ratio — proporção de requisições atendidas pelo cache

Casos de Uso Setoriais

E-commerce: Análise de Conversão em Tempo Real

Uma equipe de marketing pode executar consultas como:

"Quais categorias tiveram maior crescimento de conversão nas últimas duas semanas comparadas ao mesmo período do mês passado?"

O sistema interpreta automaticamente "conversão" como orders / sessions, aplica comparação temporal correta e gera uma consulta SQL com CTEs e janelas de tempo — tudo sem intervenção manual.

Saúde: Análise de Dados Clínicos com Governança Estrita

Modelos MDL podem incorporar ontologias médicas (ex.: SNOMED CT), permitindo consultas como:

"Liste pacientes com diagnóstico de diabetes tipo 2 que receberam prescrição de metformina nos últimos 90 dias."

O mecanismo de política garante que campos sensíveis como patient_name ou birth_date sejam automaticamente anonimizados ou omitidos conforme o perfil do usuário.

Solução de Problemas Comuns

Consulta Gerada com Junções Incorretas

Causa provável: relacionamentos mal definidos no modelo MDL. Correção recomendada:

# Em schemas/product_mdl.yaml
relationships:
  - from: sales
    to: products
    type: many_to_one
    join_on: "sales.product_id = products.id"

Tempo de Resposta Elevado em Consultas Complexas

Solução imediata: habilitar otimização de plano de execução no conector:

# Em connectors/postgres.py
def get_optimized_query(self, raw_sql: str) -> str:
    return f"EXPLAIN (ANALYZE, BUFFERS) {raw_sql}"

Além disso, validar índices nas colunas frequentemente usadas em JOIN, WHERE e ORDER BY.

Extensibilidade e Integração

O SDK oferece classes abstratas para expansão:

• DataConnector: implemente fetch_schema() e execute() para novas fontes
• PolicyEngine: sobrescreva apply_rules() para lógicas customizadas de filtragem
• EmbeddingProvider: troque modelos de linguagem para embeddings específicos de domínio

Exemplo de integração com Streamlit:

import streamlit as st
from wrenai.client import WrenAIClient

client = WrenAIClient(base_url="http://localhost:3000")

question = st.text_input("Faça sua pergunta em linguagem natural:")
if question:
    response = client.query(question, data_source="analytics_db")
    st.dataframe(response.results)