Vanna 2.0 deployment - agente NL2SQL pt-BR sobre ClickHouse com RLS por tenant

Go to file

Dalton Alvarenga 0a6852acbb All checks were successful CD / build (push) Successful in 5m47s Details Merge PR #8 : fix(ci): Cloud Build com --gcs-source-staging-dir + --async + poll loop		2026-05-07 16:27:47 +00:00
.gitea/workflows	fix(ci): troca --suppress-logs por --async + poll loop	2026-05-07 13:20:27 -03:00
docs	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
k8s	chore: bootstrap deploy no hml2 (Dockerfile + k8s + workflow CD)	2026-05-05 17:56:37 -03:00
static	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
.dockerignore	chore: bootstrap deploy no hml2 (Dockerfile + k8s + workflow CD)	2026-05-05 17:56:37 -03:00
.env.example	chore: bootstrap deploy no hml2 (Dockerfile + k8s + workflow CD)	2026-05-05 17:56:37 -03:00
.gitignore	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
agent.py	fix: troca header markdown por negrito na saudação inicial	2026-05-06 16:21:48 -03:00
AI-HISTORY.md	chore: bootstrap deploy no hml2 (Dockerfile + k8s + workflow CD)	2026-05-05 17:56:37 -03:00
ask.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
chat_filter.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
CLAUDE.md	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
csv_cleanup.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
Dockerfile	fix(ci): volta build pra Cloud Build + bump Node 20 no webcomponent	2026-05-07 10:21:18 -03:00
events_sink.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
README.md	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
requirements.txt	chore: bootstrap deploy no hml2 (Dockerfile + k8s + workflow CD)	2026-05-05 17:56:37 -03:00
rls_runner.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
server.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
system_prompt.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
tenant_memory.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
test_clickhouse.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
train.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00
viz_tool.py	Initial commit: Vanna 2.0 deployment for ClubPetro	2026-04-29 17:22:05 -03:00

README.md

vanna-clubpetro

Deploy do Vanna 2.0 da ClubPetro: agente NL2SQL em pt-BR sobre ClickHouse Cloud, com RLS por program_id/store_id, memória ChromaDB tenant-aware, eventos persistidos em events.vanna_ai, e Web Component embedável (chat flutuante com Plotly + tabelas).

A arquitetura completa está em CLAUDE.md.

Dependência: upstream Vanna

Este repo não vendora o upstream — vanna/ está em .gitignore. O Vanna 2.0 é instalado editable a partir de um clone separado do repositório oficial.

# 1. Clone este repo
git clone https://git.clubpetro.com/leonardo.salazar/vanna-clubpetro.git
cd vanna-clubpetro

# 2. Clone o upstream do Vanna dentro do projeto
git clone https://github.com/vanna-ai/vanna.git vanna

# 3. Crie o venv e instale
python3 -m venv venv
source venv/bin/activate
pip install -e ./vanna
pip install clickhouse-connect chromadb openai python-dotenv fastapi uvicorn

Pinning recomendado: o deploy atual roda com upstream em 365d061 (vanna-ai/vanna@365d0617c1a4567ffee1b19b40c27feb4206bfcf). Se um git pull upstream quebrar algo, faça git checkout 365d061 dentro de vanna/.

Build do Web Component

cd vanna/frontends/webcomponent
npm install
npm run build
# gera vanna/frontends/webcomponent/dist/vanna-components.js (~7.5 MB)

Configuração

Copie .env.example (não versionado — peça pro time) ou crie .env com:

CLICKHOUSE_HOST=...
CLICKHOUSE_PORT=8443
CLICKHOUSE_DATABASE=gold
CLICKHOUSE_USER=wren_ia
CLICKHOUSE_PASSWORD=...
CLICKHOUSE_SECURE=true

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-5
OPENAI_TEMPERATURE=1.0

RLS_PROGRAM_ID=...
RLS_STORE_ID=...
RLS_USER_ID=...

Treinar a memória de schema

python train.py

Lê system.columns filtrado por GRANT do usuário wren_ia e escreve memórias de texto no ChromaDB local (./chroma_db/). Re-rode após qualquer mudança em GRANT, em RLS_TABLES, ou em RLS_INTERNAL_COLS.

Rodar

CLI:

python ask.py "qual o ranking de produtos por valor de venda?"
python ask.py --program-id <id> --store-id <id> "..."

Servidor web (embed do <vanna-chat>):

uvicorn server:app --host 127.0.0.1 --port 8765
# smoke test em http://127.0.0.1:8765/embed-demo.html

Embed em outras páginas

Ver docs/embed-react.md e docs/deploy.md. O bootstrap único (static/vanna-embed-bootstrap.js) carrega bundle + tema + i18n.