Vanna 2.0 is an open-source framework designed to transform natural language questions into data insights by generating SQL queries, executing them, and presenting results through a rich web interface. It emphasizes enterprise-grade security, user-aware permissions, real-time streaming, and production readiness.

The core methodology revolves around an agentic architecture that orchestrates interactions between a user, a web component, a backend server, an LLM-powered agent, and a set of tools. The workflow initiates when a user submits a natural language query to the $<vanna-chat>$ web component. This component dispatches an authenticated HTTP POST request (e.g., to /api/vanna/v2/chat_sse) to the user's backend server. The server, leveraging a UserResolver (a custom implementation of vanna.core.user.UserResolver), extracts the user's identity, including their ID, email, and group memberships, from the request's context (e.g., Authorization headers for JWTs).

This user-identified request is then forwarded to the Agent. The Agent, powered by an LLM (e.g., Anthropic, OpenAI), determines the appropriate Tool to invoke based on the user's query. A central tenet is the concept of "User-Aware Tools." Before execution, tools, such as the RunSqlTool, receive the User object and automatically enforce permissions, like row-level security, based on the user's group memberships. For example, a RunSqlTool would filter the generated SQL query or its results to ensure the user only accesses data they are authorized to see. The Tool executes its function (e.g., running the SQL query against a database), and returns a ToolResult to the Agent. The Agent then streams rich, structured UI components (e.g., interactive data tables, Plotly charts, and natural language summaries) in real-time back to the $<vanna-chat>$ component, which renders the output to the user.

Key technical components and features include:

• User Resolver: A configurable class (e.g., MyUserResolver) responsible for parsing user identity from RequestContext objects, crucial for subsequent permission enforcement. It returns a User object with id, email, and group_memberships.
• Agent: The orchestrator (vanna.Agent) that takes an LLMService (for language model interaction), a ToolRegistry (managing available tools), and a UserResolver.
• Tools: Extensible components that encapsulate specific functionalities (e.g., RunSqlTool for database interaction, custom tools for sending emails). Custom tools inherit from vanna.core.tool.Tool[ArgsType], define their name, access_groups (for permission checks), and get_args_schema (a Pydantic BaseModel defining the tool's input arguments). The execute method contains the business logic, receiving ToolContext (which includes the User object) and the parsed arguments.
• Streaming Components: The backend streams ToolResult data (e.g., table, chart, summary) to the frontend, enabling real-time updates and interactive display.
• Built-in Web UI: The $<vanna-chat>$ web component is a pre-built, framework-agnostic (React, Vue, plain HTML) UI that consumes the SSE stream from the backend and renders the data.
• Enterprise Security: Implemented via user-aware permissions, row-level security (applied by tools), audit logs (every query tracked per user), and rate limiting (via lifecycle hooks).
• Extensibility: Beyond custom tools, Vanna 2.0 supports Lifecycle Hooks (for custom logic at various stages like quota checking or content filtering), LLM Middlewares (for caching, prompt engineering, cost tracking), Conversation Storage, Observability (tracing, metrics), and Context Enrichers (RAG, memory).

Vanna 2.0 represents a significant rewrite from its 0.x predecessors, moving from a class-method based API to an agent-based architecture, incorporating user-awareness and streaming capabilities throughout. Migrating from 0.x can be done via a LegacyVannaAdapter or through a gradual transition to the new Agent API.