leonardosalazar-cp 1d152c0dce Initial commit: Vanna 2.0 deployment for ClubPetro

Wrapper application around upstream Vanna with:
- Tenant-aware ChromaDB memory (per program/store)
- ClickHouse RLS runner with introspection guards
- PT-BR system prompt and chat translations
- Custom Plotly chart generator (ranked bar, datetime coercion)
- Embed bootstrap (theme pierce + i18n + markdown) shared by demo and React app
- Event sink for chat turn observability

2026-04-29 17:22:05 -03:00

2.4 KiB

Raw Permalink Blame History

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.

2.4 KiB Raw Permalink Blame History