vanna README

The project's README from github.com/vanna-ai/vanna. As one markdown file: README.md.

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

✅ 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:

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:

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

vanna (vanna-ai/vanna)

Searching Database…

23.8K ·GitHub
Vanna
archived
Что это такое?Vanna — это open-source фреймворк на Python для общения с вашей SQL-базой: пользователь задаёт вопрос обычным языком и получает SQL, таблицы, графики и ответ на естественном языке, причём разграничение прав для каждого пользователя встроено изначально.
Это Python-библиотека, готовое приложение или и то и другое?И то и другое: бэкенд на Python, который вы встраиваете в FastAPI или Flask, плюс готовый фронтенд-компонент для веба, который вставляется на любую страницу (React, Vue или обычный HTML) и отображает чат, таблицы и графики.
Как его запустить?Начните с Quickstart, чтобы попробовать на тестовых данных, затем выполните Configure для своей базы данных и LLM. Для продакшена есть подробный пример встраивания Vanna в уже существующее приложение на FastAPI со своей авторизацией.
Какие LLM и базы данных можно подключить?Проект не привязан к конкретным провайдерам: для LLM — OpenAI, Anthropic, Ollama, Azure, Gemini, AWS Bedrock, Mistral и другие; для баз данных — PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQLite, Oracle, SQL Server, DuckDB, ClickHouse и не только.
Проект до сих пор активно развивается?Стоит знать до того, как браться: репозиторий на GitHub заархивирован, то есть доступен только для чтения и изменения больше не принимаются. В README по-прежнему предлагается корпоративная поддержка через [email protected], но сначала проверьте актуальный статус.
Можно ли запустить его на своей инфраструктуре с локальной моделью?Да — он работает внутри вашего приложения на FastAPI или Flask, а если хотите, чтобы LLM была полностью локальной, поддерживается Ollama. Про политику хранения данных в README ничего не сказано.
Что на самом деле видит пользователь, когда задаёт вопрос?Пять вещей в режиме реального времени: обновления о ходе выполнения, блок с SQL-кодом (по умолчанию скрыт от пользователей без прав администратора), интерактивная таблица с данными, графики Plotly и итоговый ответ на естественном языке.
Для кого сделан Vanna?Для команд, которые строят аналитические приложения с интерфейсом на естественном языке, для multi-tenant SaaS-продуктов, где нужны права для каждого пользователя, и для компаний с требованиями аудита — то есть для всех, кому нужен готовый чат-интерфейс с бэкендом, а не свой с нуля.
Как устроена фильтрация по пользователю внутри?Ваш User Resolver берёт данные о пользователе из запроса (куки, JWT, OAuth-токены); они проходят через системные промпты, выполнение инструментов и фильтрацию SQL, а каждый запрос фиксируется в журналах аудита с привязкой к пользователю.
What are similar projects?DB-GPT, pandas-ai, superset, dataease, data-formulator, apowerb, redash, DocsGPT
Which topics is it in?text-to-sql, flask, charts, fastapi, analytics, enterprise, data-visualization, sql, rag, vue, anthropic, database
Creator
vanna-ai
Size
8.4 MB
Stars
23.8K
Updated
CommitFeb 02Releasev2.0.2Feb 02
Age
3y
Commits · 90 Days