Vanna AI

Understanding the fundamental shifts between the legacy 0.x version and the current 2.0+ framework:

To build a system that converts natural language questions into SQL, follow this five-step architectural pattern:

1. Question: Define the business question in plain English.
2. Prompt: Construct a prompt that includes the question and instructions for the LLM.
3. Generate SQL: Send the prompt to an LLM via an API to receive the generated SQL.
4. Run SQL: Execute the generated SQL against your database.
5. Validate results: Verify that the returned data matches the expected business outcome.

This process highlights that the LLM's ability to generate correct SQL is heavily dependent on the context provided during the prompt stage.

# 1. Question
question = "how many clients are there in germany"

# 2. Prompt
prompt = f"""
Write a SQL statement for the following question:
{question}
"""

# 3. Generate SQL
sql = llm.api(api_key=api_key, prompt=prompt, parameters=parameters)

# 4. Run SQL
df = db.conn.execute(sql)

# 5. Validate results
# (Manual or automated evaluation of df)

If you have an existing Vanna 0.x codebase and want to adopt the Vanna 2.0+ agent framework with minimal changes, use the LegacyVannaAdapter. This strategy allows you to keep your existing VannaBase instance (including database connections and training data) while gaining access to new features like the Web UI and streaming responses.

Key steps:

1. Install Vanna 2.0+ with necessary extras: pip install 'vanna[flask,anthropic]' (adjust extras based on your provider).
2. Implement a UserResolver (required in 2.0+).
3. Wrap your existing vn object with LegacyVannaAdapter(vn).
4. Initialize an Agent using an llm_service and the adapter as the tool_registry.
5. Run the VannaFastAPIServer.

What the adapter provides:

• Wraps vn.run_sql() as the run_sql tool.
• Exposes training data via search_saved_correct_tool_uses.
• Allows admins to save new training data via save_question_tool_args.

from vanna import Agent, AgentConfig
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.core.user import UserResolver, User, RequestContext
from vanna.legacy.adapter import LegacyVannaAdapter
from vanna.integrations.anthropic import AnthropicLlmService

# 1. Your existing 0.x object
# vn = MyVanna(config={'model': 'gpt-4', 'api_key': 'your-key'})
# vn.connect_to_postgres(...)

# 2. Define required UserResolver
class SimpleUserResolver(UserResolver):
    async def resolve_user(self, request_context: RequestContext) -> User:
        user_email = request_context.get_cookie('vanna_email')
        if not user_email:
            raise ValueError("Missing 'vanna_email' cookie")
        return User(id=user_email, email=user_email, group_memberships=['user'])

# 3. Wrap existing vn with adapter
tools = LegacyVannaAdapter(vn)

# 4. Setup LLM and Agent
llm = AnthropicLlmService(model="claude-haiku-4-5", api_key="YOUR_KEY")
agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=SimpleUserResolver(),
    config=AgentConfig()
)

# 5. Run server
server = VannaFastAPIServer(agent)
if __name__ == "__main__":
    server.run(host='0.0.0.0', port=8000)

To deploy Vanna in production with your own authentication system, you need to implement a UserResolver to extract user identity (from cookies, JWTs, etc.) and register Vanna's chat routes with your FastAPI application. This ensures that every query is user-aware and can be filtered by permissions.

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)