README

Vanna 2.0: Turn Questions into Data Insights

Natural language → SQL → Answers. Now with enterprise security and user-aware permissions.





https://github.com/user-attachments/assets/476cd421-d0b0-46af-8b29-0f40c73d6d83


!Vanna2 Demo

---

 What's New in 2.0

🔐 User-Aware at Every Layer — Queries automatically filtered per user permissions

🎨 Modern Web Interface — Beautiful pre-built  component

⚡ Streaming Responses — Real-time tables, charts, and progress updates

🔒 Enterprise Security — Row-level security, audit logs, rate limiting

🔄 Production-Ready — FastAPI integration, observability, lifecycle hooks

 Upgrading from 0.x? See the Migration Guide | What changed?

---

 Get Started

 Try it with Sample Data

Quickstart

 Configure

Configure

 Web Component

html






Uses your existing cookies/JWTs. Works with React, Vue, or plain HTML.

---

 What You Get

Ask a question in natural language and get back:

1. Streaming Progress Updates

2. SQL Code Block (By default only shown to "admin" users)

3. Interactive Data Table

4. Charts (Plotly visualizations)

5. Natural Language Summary

All streamed in real-time to your web component.

---

 Why Vanna 2.0?

 ✅ Get Started Instantly
 Production chat interface
 Custom agent with your database
 Embed in any webpage

 ✅ Enterprise-Ready Security
User-aware at every layer — Identity flows through system prompts, tool execution, and SQL filtering
Row-level security — Queries automatically filtered per user permissions
Audit logs — Every query tracked per user for compliance
Rate limiting — Per-user quotas via lifecycle hooks

 ✅ Beautiful Web UI Included
Pre-built  component — No need to build your own chat interface
Streaming tables & charts — Rich components, not just text
Responsive & customizable — Works on mobile, desktop, light/dark themes
Framework-agnostic — React, Vue, plain HTML

 ✅ Works With Your Stack
Any LLM: OpenAI, Anthropic, Ollama, Azure, Google Gemini, AWS Bedrock, Mistral, Others
Any Database: PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQLite, Oracle, SQL Server, DuckDB, ClickHouse, Others
Your Auth System: Bring your own — cookies, JWTs, OAuth tokens
Your Framework: FastAPI, Flask

 ✅ Extensible But Opinionated
Custom tools — Extend the Tool base class
Lifecycle hooks — Quota checking, logging, content filtering
LLM middlewares — Caching, prompt engineering
Observability — Built-in tracing and metrics

---

 Architecture

!Vanna2 Diagram

---

 How It Works

mermaid
sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 
    participant S as 🐍 Your Server
    participant A as 🤖 Agent
    participant T as 🧰 Tools

    U-W: "Show Q4 sales"
    W-S: POST /api/vanna/v2/chat_sse (with auth)
    S-A: User(id=alice, groups=[read_sales])
    A-T: Execute SQL tool (user-aware)
    T-T: Apply row-level security
    T-A: Filtered results
    A-W: Stream: Table → Chart → Summary
    W-U: Display beautiful UI


Key Concepts:

1. User Resolver — You define how to extr