Vanna 2.0: Turn Questions into Data Insights

Natural language โ†’ SQL โ†’ Answers. Now with enterprise security and user-aware permissions.

Python License Code style: black

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 <vanna-chat> 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

<!-- Drop into any existing webpage -->
<script src="https://img.vanna.ai/vanna-components.js"></script>
<vanna-chat
  sse-endpoint="https://your-api.com/chat"
  theme="dark">
</vanna-chat>

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 <vanna-chat> 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

sequenceDiagram
    participant U as ๐Ÿ‘ค User
    participant W as ๐ŸŒ <vanna-chat>
    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 extract user identity from requests (cookies, JWTs, etc.)
  2. User-Aware Tools โ€” Tools automatically check permissions based on user's group memberships
  3. Streaming Components โ€” Backend streams structured UI components (tables, charts) to frontend
  4. Built-in Web UI โ€” Pre-built <vanna-chat> component renders everything beautifully

Production Setup with Your Auth

Here's a complete example integrating Vanna with your existing FastAPI app and authentication:

from fastapi import FastAPI
from vanna import Agent
from vanna.servers.fastapi.routes import register_chat_routes
from vanna.servers.base import ChatHandler
from vanna.core.user import UserResolver, User, RequestContext
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.core.registry import ToolRegistry

# Your existing FastAPI app
app = FastAPI()

# 1. Define your user resolver (using YOUR auth system)
class MyUserResolver(UserResolver):
    async def resolve_user(self, request_context: RequestContext) -> User:
        # Extract from cookies, JWTs, or session
        token = request_context.get_header('Authorization')
        user_data = self.decode_jwt(token)  # Your existing logic

        return User(
            id=user_data['id'],
            email=user_data['email'],
            group_memberships=user_data['groups']  # Used for permissions
        )

# 2. Set up agent with tools
llm = AnthropicLlmService(model="claude-sonnet-4-5")
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=MyUserResolver()
)

# 3. Add Vanna routes to your app
chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

# Now you have:
# - POST /api/vanna/v2/chat_sse (streaming endpoint)
# - GET / (optional web UI)

Then in your frontend:

<vanna-chat sse-endpoint="/api/vanna/v2/chat_sse"></vanna-chat>

See Full Documentation for custom tools, lifecycle hooks, and advanced configuration

Custom Tools

Extend Vanna with custom tools for your specific use case:

from vanna.core.tool import Tool, ToolContext, ToolResult
from pydantic import BaseModel, Field
from typing import Type

class EmailArgs(BaseModel):
    recipient: str = Field(description="Email recipient")
    subject: str = Field(description="Email subject")

class EmailTool(Tool[EmailArgs]):
    @property
    def name(self) -> str:
        return "send_email"

    @property
    def access_groups(self) -> list[str]:
        return ["send_email"]  # Permission check

    def get_args_schema(self) -> Type[EmailArgs]:
        return EmailArgs

    async def execute(self, context: ToolContext, args: EmailArgs) -> ToolResult:
        user = context.user  # Automatically injected

        # Your business logic
        await self.email_service.send(
            from_email=user.email,
            to=args.recipient,
            subject=args.subject
        )

        return ToolResult(success=True, result_for_llm=f"Email sent to {args.recipient}")

# Register your tool
tools.register(EmailTool())

Advanced Features

Vanna 2.0 includes powerful enterprise features for production use:

Lifecycle Hooks โ€” Add quota checking, custom logging, content filtering at key points in the request lifecycle

LLM Middlewares โ€” Implement caching, prompt engineering, or cost tracking around LLM calls

Conversation Storage โ€” Persist and retrieve conversation history per user

Observability โ€” Built-in tracing and metrics integration

Context Enrichers โ€” Add RAG, memory, or documentation to enhance agent responses

Agent Configuration โ€” Control streaming, temperature, max iterations, and more

Use Cases

Vanna is ideal for:

  • ๐Ÿ“Š Data analytics applications with natural language interfaces
  • ๐Ÿ” Multi-tenant SaaS needing user-aware permissions
  • ๐ŸŽจ Teams wanting a pre-built web component + backend
  • ๐Ÿข Enterprise environments with security/audit requirements
  • ๐Ÿ“ˆ Applications needing rich streaming responses (tables, charts, SQL)
  • ๐Ÿ”„ Integrating with existing authentication systems

Community & Support

Migration Notes

Upgrading from Vanna 0.x?

Vanna 2.0 is a complete rewrite focused on user-aware agents and production deployments. Key changes:

  • New API: Agent-based instead of VannaBase class methods
  • User-aware: Every component now knows the user identity
  • Streaming: Rich UI components instead of text/dataframes
  • Web-first: Built-in <vanna-chat> component and server

Migration path:

  1. Quick wrap โ€” Use LegacyVannaAdapter to wrap your existing Vanna 0.x instance and get the new web UI immediately
  2. Gradual migration โ€” Incrementally move to the new Agent API and tools

See the complete Migration Guide for step-by-step instructions.

License

MIT License โ€” See LICENSE for details.

Built with โค๏ธ by the Vanna team | Website | Docs | Discussions

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for ashishsingal from gravatar.com ashishsingal Avatar for zain_hoda from gravatar.com zain_hoda

Credits

Author: Zain Hoda

License

MIT License

Requires

Python >=3.9

Provides Extra

all anthropic azureopenai azuresearch bedrock bigquery chromadb clickhouse dev duckdb faiss-cpu faiss-gpu fastapi flask gemini google hf hive marqo milvus mistralai mssql mysql ollama openai opensearch oracle pgvector pinecone postgres presto qdrant qianfan servers snowflake test vllm weaviate xinference-client zhipuai

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vanna-2.0.2.tar.gz (375.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

vanna-2.0.2-py3-none-any.whl (486.6 kB view details)

Uploaded Python 3

File details

Details for the file vanna-2.0.2.tar.gz.

File metadata

  • Download URL: vanna-2.0.2.tar.gz
  • Upload date:
  • Size: 375.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.25

File hashes

Hashes for vanna-2.0.2.tar.gz
Algorithm Hash digest
SHA256 39ca66d7c7033dfd864c4cd3477fee0b8962921410e999f8669f7d527bca942e
MD5 576ec7ca8c3f7ae2314e4b09a01d54f1
BLAKE2b-256 1ed9af5fa8cb19cfb7d05faefda8c85083dd089971bbaee938b7e973dfb60ca2

See more details on using hashes here.

File details

Details for the file vanna-2.0.2-py3-none-any.whl.

File metadata

  • Download URL: vanna-2.0.2-py3-none-any.whl
  • Upload date:
  • Size: 486.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.25

File hashes

Hashes for vanna-2.0.2-py3-none-any.whl
Algorithm Hash digest
SHA256 d54f039572b0bcc520859ba99b7a587bdf96eebafc0c77c28fe44c0962550553
MD5 c7017ae19a1f2715b96c603e76ede748
BLAKE2b-256 bf8029ac542e8efe1d93fc99b25c870794673b22aeeb404060fd190e92aaf359

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

2.0.2 This release

2 files

2.0.1

2 files

2.0.0

2 files

Pre-release

2.0.0rc1

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

0.1.0

2 files

0.0.38

2 files

0.0.37

2 files

0.0.36

2 files

0.0.35

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page