PAIRS

Persona-Aware Intents for Real-world SQL

Uma abordagem para geração automática de pares de consultas em linguagem natural–SQL

Gera benchmarks para sistemas Text-to-SQL: cria consultas SQL por nível de dificuldade, define personas para simular perfis distintos de usuários e sintetiza perguntas em linguagem natural associadas a essas consultas. Toda SQL gerada é validada no banco-alvo, e uma etapa de curadoria humana (Human-in-the-Loop) permite revisar, editar e descartar pares antes da exportação.

Estrutura

backend/    API FastAPI + domínio (pacote pairs, prompts, testes)
PAIRS/      Interface React (Vite)
data/       DDL e documentação dos datasets
docs/       Esquema OpenAPI e datasets de exemplo
output/     benchmark.db (SQLite) — tudo que é gerado e curado

Configuração fica na raiz: .env, agents_config.yaml, logging_config.yaml e os arquivos do Docker Compose.

Rodando com Docker (recomendado)

Requer apenas Docker. Sobe Postgres, API e interface de uma vez:

cp .env.example .env      # preencha a chave do provedor de LLM
docker compose up --build

• Interface: http://localhost:5173
• API: http://localhost:8000 (documentação em /docs)

O Postgres do compose é populado com o schema em data/datasus/ddl.sql na primeira subida. Para apontar para outro banco, use os campos de conexão na etapa 1 da interface.

Produção:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Rodando localmente

Requer Python >=3.12,<3.14, Poetry, Node 20+ e um PostgreSQL acessível.

# API
cd backend && poetry install && poetry run api

# interface, em outro terminal
cd PAIRS && npm install && npm run dev

A interface espera a API em VITE_API_BASE_URL (padrão http://localhost:8000).

Configuração

.env na raiz — veja .env.example para a lista completa:

Variável	Para quê
LLM_PROVIDER	openai, groq ou ollama
OPENAI_API_KEY / GROQ_API_KEY	Chave do provedor escolhido (Ollama não precisa)
DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD	Banco-alvo do benchmark
BENCHMARK_OUTPUT_DIR	Onde fica o benchmark.db (padrão: output/)

Quais modelos cada etapa usa fica em agents_config.yaml, editável também pela tela de configuração de agentes na interface.

Fluxo da interface (5 etapas)

1. Carregamento e conexão — dataset ID, upload do DDL e da documentação, dados de conexão com o PostgreSQL.
2. Geração de SQLs — quantidade por dificuldade (simples, moderada, difícil); cada consulta é executada no banco e quem falha fica marcada com o motivo.
3. Revisão das SQLs — inspecionar, editar, pré-visualizar o resultado, aprovar ou descartar. Toda edição é revalidada no banco.
4. Personas e perguntas — cadastro das personas e geração das perguntas a partir das SQLs aprovadas.
5. Paráfrases e curadoria final — geração das paráfrases e revisão dos pares antes da exportação.

As etapas 2, 4 e 5 rodam como jobs em segundo plano, com progresso na barra superior. A sessão é retomável: a URL carrega o run_id, e reconectar pede apenas a senha do banco.

Saída

Tudo é persistido em output/benchmark.db. O benchmark final é baixado pela interface na última etapa, ou pela API:

curl "http://localhost:8000/runs/<run_id>/export" -o benchmark.json

Cada entrada traz id, parent_id, db_id, question, difficulty, sql e persona.

Comandos

Comando	O que faz
poetry run api	Sobe a API FastAPI (dentro de backend/)
poetry run web	Interface Streamlit legada; exige a API no ar
poetry run openapi	Regenera docs/openapi.json
poetry run pytest	Testes do backend
npm run dev / npm run build	Interface React (dentro de PAIRS/)

Datasets de exemplo

docs/ traz um exemplo completo (schema, seed e documentação de negócio) para experimentar o fluxo sem um banco próprio — veja docs/README.md. O esquema da API fica em docs/openapi.json.