# 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`](./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.

```bash
# 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

```bash
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

```bash
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:
```bash
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>`):
```bash
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`](./docs/embed-react.md) e [`docs/deploy.md`](./docs/deploy.md). O bootstrap único (`static/vanna-embed-bootstrap.js`) carrega bundle + tema + i18n.