Text-to-SQL de nível de produção sobre o Snowflake: um agente que responde perguntas em português consultando dados via Cortex Analyst, com o modelo semântico versionado como código, roles de least privilege, guarda-corpo de custo e a geração de SQL separada da execução.
É a versão com dado público do que construo em produção: agentes servindo consultas executivas a Board e C-Level em linguagem natural.
flowchart LR
U[Pergunta em português] --> S[Streamlit<br/>local ou in-Snowflake]
S -->|REST| A[Cortex Analyst]
M[semantic_model/indicadores.yaml<br/>dimensões, medidas, sinônimos,<br/>verified queries] --> A
A -->|SQL + explicação| S
S -->|revisão explícita| E[Execução<br/>role somente leitura]
N[Cortex Search<br/>notas metodológicas] -.->|perguntas conceituais| S
E --> R[(indicadores_economicos<br/>dados públicos BCB)]
| Peça | Arquivo | Por quê |
|---|---|---|
| Modelo semântico | semantic_model/indicadores.yaml |
O contrato pergunta → SQL: sinônimos em português e verified queries para as perguntas de negócio |
| Setup como código | sql/01..04 |
Database, warehouse XSMALL com resource monitor, roles read-only, Cortex Search |
| Cliente REST | src/agente/cliente.py |
Montagem, validação de contrato e extração; 100% coberto por testes com mock |
| Interface | app/streamlit_app.py |
Mostra o SQL antes de executar, de propósito |
| Seed | docs/seed_indicadores.csv |
Reprodução em qualquer conta trial em minutos |
Geração separada de execução. O Analyst devolve o SQL; executar é outra etapa, com role somente leitura. Agente que executa o que quiser com role administrativa é incidente esperando data.
Verified queries para o que é crítico. IPCA acumulado é multiplicativo, não soma de percentuais: a verified query congela o cálculo correto em vez de torcer para o modelo acertar.
Custo com teto. Warehouse XSMALL, auto-suspend de 60s e resource monitor com quota: o agente não tem como gerar surpresa na fatura.
pip install -r requirements-dev.txt && pytest # cliente testado sem Snowflake
# na conta Snowflake (worksheet ou snowflake-cli):
# sql/01_setup_base.sql → 02 → 03 → 04
# PUT do seed e do YAML no stage, COPY INTO
export SNOWFLAKE_ACCOUNT_URL=https://<conta>.snowflakecomputing.com
export SNOWFLAKE_TOKEN=<pat>
streamlit run app/streamlit_app.py