leonardosalazar-cp
1d152c0dce
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
83 lines
2.4 KiB
Markdown
83 lines
2.4 KiB
Markdown
# 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.
|