Vanna 2.0

https://vanna.ai/docs
Admin
Vanna 2.0 is a user-aware AI agent framework that connects large language models to databases,...
Tokens:72,052
Snippets:687
Trust Score:8.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Deploying Vanna with Flask

Source: https://vanna.ai/docs/placeholder/deployment/flask

A basic example demonstrating how to set up and run a Vanna Flask server.

```APIDOC
## Quick Start: Deploying Vanna with Flask

This example shows the minimal setup required to run Vanna AI as a Flask server.

### Code Example
```python
from vanna import Agent, ToolRegistry
from vanna.servers.flask import VannaFlaskServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.postgres import PostgresRunner
from vanna.tools import RunSqlTool

# Create components
llm_service = AnthropicLlmService(api_key="...")
sql_runner = PostgresRunner(connection_string="...")

# Create tool registry and register tools
registry = ToolRegistry()
registry.register_local_tool(RunSqlTool(sql_runner), access_groups=[])

# Create your agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=MyUserResolver(),
    agent_memory=MyAgentMemory()  # Required parameter
)

# Create Flask server
server = VannaFlaskServer(agent)

# Run the server
server.run(host="0.0.0.0", port=5000)
```
```

--------------------------------

### Example Starter UI Components

Source: https://vanna.ai/docs/placeholder/workflow-handlers

Illustrates `StatusCardComponent` usage for different setup states: complete SQL connection, missing SQL tool, and missing memory tools.

```python
# Complete setup - shows success message
StatusCardComponent(
    title="SQL Connection", 
    status="success",
    description="Database connection configured and ready"
)

# Missing SQL - shows error
StatusCardComponent(
    title="SQL Connection",
    status="error", 
    description="No SQL tool detected - this is required"
)

# Missing memory - shows warning  
StatusCardComponent(
    title="Memory System",
    status="warning",
    description="Memory tools not configured - I won't remember patterns"
)
```

--------------------------------

### Web Server Initialization Example

Source: https://vanna.ai/docs/tutorials/quickstart-5min

Shows how to initialize and run a FastAPI server with a built-in web UI for interacting with a Vanna agent. This setup provides a user-friendly interface for querying the database.

```python
server = VannaFastAPIServer(agent)
server.run()
```

--------------------------------

### Complete configuration example

Source: https://vanna.ai/docs/configure

A consolidated example containing all necessary imports and configuration steps.

```python
# All imports at the top
from vanna import Agent
from vanna.core.registry import ToolRegistry
from vanna.core.user import UserResolver, User, RequestContext
from vanna.tools import RunSqlTool, VisualizeDataTool
from vanna.tools.agent_memory import SaveQuestionToolArgsTool, SearchSavedCorrectToolUsesTool, SaveTextMemoryTool
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.sqlite import SqliteRunner
from vanna.integrations.local.agent_memory import DemoAgentMemory

# Configure your LLM
llm = AnthropicLlmService(
    model="claude-sonnet-4-5",
    api_key="sk-ant-..."  # Or use os.getenv("ANTHROPIC_API_KEY")
)

# Configure your database
db_tool = RunSqlTool(
    sql_runner=SqliteRunner(database_path="./your_database.db")
)

# Configure your agent memory
agent_memory = DemoAgentMemory(max_items=1000)
```

--------------------------------

### Installation

Source: https://vanna.ai/docs/placeholder/python

Install the Vanna Python SDK and its optional dependencies for various integrations.

```APIDOC
## Installation

Install the Vanna Python SDK:
```
pip install vanna
```

### Optional Dependencies

Install optional dependencies for database integrations:
```
# Database integrations
pip install vanna[postgres]
pip install vanna[mysql]
pip install vanna[snowflake]
pip install vanna[bigquery]
pip install vanna[duckdb]
```

Install optional dependencies for LLM providers:
```
# LLM providers
pip install vanna[anthropic]
pip install vanna[openai]
```

Install all integrations:
```
# All integrations
pip install vanna[all]
```
```

--------------------------------

### Provide Example Interactions in System Prompt

Source: https://vanna.ai/docs/placeholder/system-prompts

This snippet demonstrates how to include example user-assistant interactions within a system prompt to guide the AI's conversational flow and tool usage.

```text
prompt += """
## Example Interactions

User: \"Show me top customers\"
Assistant: I'll query the customers table and order by total_purchases.
[calls run_sql with appropriate query]

User: \"Visualize that\"
Assistant: [calls visualize_data on the results file]"""
```

--------------------------------

### Install Vanna SDK

Source: https://vanna.ai/docs/placeholder/python

Install the base Vanna package via pip.

```bash
pip install vanna
```

--------------------------------

### Install Optional Dependencies

Source: https://vanna.ai/docs/placeholder/python

Install specific database integrations, LLM providers, or all available dependencies.

```bash
# Database integrations
pip install vanna[postgres]
pip install vanna[mysql]
pip install vanna[snowflake]
pip install vanna[bigquery]
pip install vanna[duckdb]

# LLM providers
pip install vanna[anthropic]
pip install vanna[openai]

# All integrations
pip install vanna[all]
```

--------------------------------

### Tool Registration Example

Source: https://vanna.ai/docs/tutorials/quickstart-5min

Example of registering a local tool, specifically a RunSqlTool for SQLite, and assigning access permissions to the 'users' group. This demonstrates how to make tools available to specific user roles.

```python
tools.register_local_tool(
    RunSqlTool(...),
    access_groups=['users']  # Who can use this tool
)
```

--------------------------------

### Agent Configuration Example

Source: https://vanna.ai/docs/tutorials/quickstart-5min

Illustrates the configuration of a Vanna agent, specifying the LLM service (e.g., Anthropic), tool registry, user resolver, agent memory, and general configuration settings. This setup allows the agent to process natural language queries and interact with tools.

```python
agent = Agent(
    llm_service=AnthropicLlmService(...),     # The AI brain
    tool_registry=tools,                       # Available capabilities
    user_resolver=CookieEmailUserResolver(),  # How to identify users
    agent_memory=DemoAgentMemory(),            # Tool usage learning
    config=AgentConfig()                       # Settings
)
```

--------------------------------

### DemoAgentMemory (In-Memory) Setup

Source: https://vanna.ai/docs/placeholder/memory-backends

Uses an ephemeral in-memory storage for demos and rapid prototyping. Data is lost upon restart, and no setup is required.

```python
from vanna.integrations.local.agent_memory import DemoAgentMemory

memory = DemoAgentMemory()

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=resolver,
    agent_memory=memory
)
```

--------------------------------

### Full Page Example with Styling

Source: https://vanna.ai/docs/placeholder/web-ui

A complete example demonstrating Tailwind CSS integration and custom styling for the chat component.

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Vanna Chat</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module" src="https://img.vanna.ai/vanna-components.js"></script>
    
    <style>
        body {
            background: linear-gradient(to bottom, #e7e1cf, #ffffff);
            min-height: 100vh;
        }
        vanna-chat {
            width: 100%;
            height: 100%;
            display: block;
        }
    </style>
</head>
<body>
    <div class="max-w-6xl mx-auto p-5">
        <h1 class="text-4xl font-bold text-center mb-8">My Data Agent</h1>
        
        <div class="bg-white rounded-xl shadow-lg h-[600px] overflow-hidden">
            <vanna-chat
                api-base=""
                sse-endpoint="/api/vanna/v2/chat_sse"
                ws-endpoint="/api/vanna/v2/chat_websocket"
                poll-endpoint="/api/vanna/v2/chat_poll">
            </vanna-chat>
        </div>
    </div>
    
    <script>
        // The component automatically includes authentication cookies
        // in all API requests
    </script>
</body>
</html>
```

--------------------------------

### Initialize ChartComponent

Source: https://vanna.ai/docs/placeholder/charts

Basic setup for creating a chart component with either Plotly or Vega-Lite.

```python
from vanna.components.rich import ChartComponent

chart = ChartComponent(
    type="plotly",  # or "vega-lite"
    spec={...},  # Chart specification
    title="Sales Trends",
    description="Monthly revenue breakdown"
)
```

--------------------------------

### File System Tools Setup

Source: https://vanna.ai/docs/placeholder/python

Initialize local file system tools for reading, writing, editing, listing, and searching files. Ensure LocalFileSystem is correctly instantiated.

```python
from vanna.tools.file_system import (
    ReadFileTool,
    WriteFileTool,
    EditFileTool,
    ListFilesTool,
    SearchFilesTool
)
from vanna.integrations.local import LocalFileSystem

fs = LocalFileSystem()

read_tool = ReadFileTool(file_system=fs)
write_tool = WriteFileTool(file_system=fs)
edit_tool = EditFileTool(file_system=fs)
list_tool = ListFilesTool(file_system=fs)
search_tool = SearchFilesTool(file_system=fs)
```

--------------------------------

### Install and Run Vanna with Uvicorn

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

Install Uvicorn with standard extras and run your FastAPI application. This is a common method for serving Python web applications.

```bash
pip install uvicorn[standard]
uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4
```

--------------------------------

### Install Vanna dependencies

Source: https://vanna.ai/docs/configure

Install the Vanna package with Anthropic and FastAPI support.

```bash
# Install Vanna with your selected dependencies 
pip install 'vanna[anthropic,fastapi]'
```

--------------------------------

### Install Vanna with Flask and Anthropic

Source: https://vanna.ai/docs/tutorials/quickstart-5min

Install Vanna along with Flask for the web server and Anthropic for the LLM service. Ensure Python 3.8 or higher is used.

```bash
pip install 'vanna[flask,anthropic]'
```

--------------------------------

### Common Use Case Configurations

Source: https://vanna.ai/docs/placeholder/ui-features

Example configurations for progressive disclosure, debug modes, and role-based UI layouts.

```python
feature_group_access={
    'sql_editor': ['developer', 'data_analyst'],
    'raw_json_view': ['developer'],
    'query_explain': ['developer', 'data_analyst'],
    'export_csv': [],  # Everyone
    'export_excel': ['premium_user']
}
```

```python
feature_group_access={
    'tool_names': ['developer'],
    'tool_arguments': ['developer'],
    'tool_error': ['developer'],
    'execution_time': ['developer'],
    'llm_tokens_used': ['developer']
}
```

```python
feature_group_access={
    # Analysts see SQL
    'sql_editor': ['analyst'],
    'query_history': ['analyst'],
    
    # Executives see insights
    'executive_summary': ['executive'],
    'trend_analysis': ['executive'],
    
    # Everyone sees charts
    'charts': [],
    'data_export': []
}
```

--------------------------------

### Quick Start: Deploying Vanna with FastAPI

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

This snippet shows the basic steps to create and run a Vanna FastAPI server with essential components like LLM service, SQL runner, and tool registry.

```APIDOC
## Quick Start: Deploying Vanna with FastAPI

This snippet shows the basic steps to create and run a Vanna FastAPI server with essential components like LLM service, SQL runner, and tool registry.

```python
from vanna import Agent, ToolRegistry
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.postgres import PostgresRunner
from vanna.tools import RunSqlTool

# Create components
llm_service = AnthropicLlmService(api_key="...")
sql_runner = PostgresRunner(connection_string="...")

# Create tool registry and register tools
registry = ToolRegistry()
registry.register_local_tool(RunSqlTool(sql_runner), access_groups=[])

# Create your agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=MyUserResolver(),  # See Authentication docs
    agent_memory=MyAgentMemory()  # Required parameter
)

# Create FastAPI server
server = VannaFastAPIServer(agent)

# Run the server
server.run(host="0.0.0.0", port=8000)
```
```

--------------------------------

### Initialize VisualizeDataTool

Source: https://vanna.ai/docs/placeholder/charts

Setup the tool for automated chart generation from CSV data.

```python
from vanna.tools import VisualizeDataTool

tool = VisualizeDataTool(file_system=file_system)

# The LLM can call this tool to create charts
# Args: filename, chart_type, x_column, y_column, title
```

--------------------------------

### Quick Start: Vanna FastAPI Server

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

Set up a Vanna agent and run it as a standalone FastAPI server. Ensure you have necessary components like LLM service and SQL runner configured.

```python
from vanna import Agent, ToolRegistry
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.postgres import PostgresRunner
from vanna.tools import RunSqlTool

# Create components
llm_service = AnthropicLlmService(api_key="...")
sql_runner = PostgresRunner(connection_string="...")

# Create tool registry and register tools
registry = ToolRegistry()
registry.register_local_tool(RunSqlTool(sql_runner), access_groups=[])

# Create your agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=MyUserResolver(),  # See Authentication docs
    agent_memory=MyAgentMemory()  # Required parameter
)

# Create FastAPI server
server = VannaFastAPIServer(agent)

# Run the server
server.run(host="0.0.0.0", port=8000)
```

--------------------------------

### Implement Custom Prometheus Integration

Source: https://vanna.ai/docs/placeholder/observability

Example of a custom provider implementation using the prometheus_client library.

```python
from prometheus_client import Counter, Histogram, Gauge, CollectorRegistry
from vanna.core.observability import ObservabilityProvider, Span

class PrometheusProvider(ObservabilityProvider):
    def __init__(self, registry: CollectorRegistry):
        self.registry = registry
        
        # Define metrics
        self.request_counter = Counter(
            'agent_requests_total',
            'Total agent requests',
            ['user_group', 'status'],
            registry=registry
        )
        
        self.tool_duration = Histogram(
            'agent_tool_duration_seconds',
            'Tool execution duration',
            ['tool_name', 'success'],
            registry=registry
        )
        
        self.active_conversations = Gauge(
            'agent_active_conversations',
            'Number of active conversations',
            registry=registry
        )
        
        self.llm_tokens = Counter(
            'agent_llm_tokens_total',
            'Total LLM tokens used',
            ['model', 'token_type'],
            registry=registry
        )
    
    async def record_metric(
        self,
        name: str,
        value: float,
        unit: str = "",
        tags: Optional[Dict[str, str]] = None
    ) -> None:
        tags = tags or {}
        
        if name == "agent.request":
            self.request_counter.labels(
                user_group=tags.get('user_group', 'unknown'),
                status=tags.get('status', 'success')
            ).inc()
        
        elif name == "agent.tool.duration":
            self.tool_duration.labels(
                tool_name=tags.get('tool_name'),
                success=tags.get('success', 'true')
            ).observe(value)
        
        elif name == "agent.llm.tokens":
            self.llm_tokens.labels(
                model=tags.get('model'),
                token_type=tags.get('type', 'total')
            ).inc(value)
    
    async def create_span(
        self,
        name: str,
        attributes: Optional[Dict[str, Any]] = None
    ) -> Span:
        return Span(name=name, attributes=attributes or {})
```

--------------------------------

### Register PipInstallTool with an Agent

Source: https://vanna.ai/docs/placeholder/built-in-tools

Installs Python packages dynamically. Restrict to trusted users only.

```python
from vanna.tools.python import PipInstallTool

tool = PipInstallTool()
agent.register_tool(tool)
```

--------------------------------

### ChromaDB (Local Development) Memory Backend

Source: https://vanna.ai/docs/placeholder/memory-backends

Example of how to configure and use ChromaDB for persistent local vector storage, suitable for development and testing.

```APIDOC
## ChromaDB (Local Development)

ChromaDB provides persistent local vector storage for local development and testing:

```python
from vanna.integrations.chromadb import ChromaAgentMemory

memory = ChromaAgentMemory(
    collection_name="vanna_tool_memory",
    persist_directory="./chroma_db"
)

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=resolver,
    agent_memory=memory
)
```

**Features:**
  * Persistent local storage
  * Fast vector search
  * No external dependencies
  * Ideal for development and testing
```

--------------------------------

### Create Vanna AI Agent with Tool Registry

Source: https://vanna.ai/docs/configure

Set up the Vanna AI agent by initializing a ToolRegistry and registering various local tools with specific access group permissions. This example includes tools for database access, saving questions, and data visualization.

```python
tools = ToolRegistry()
tools.register_local_tool(db_tool, access_groups=['admin', 'user'])
tools.register_local_tool(SaveQuestionToolArgsTool(), access_groups=['admin'])
tools.register_local_tool(SearchSavedCorrectToolUsesTool(), access_groups=['admin', 'user'])
tools.register_local_tool(SaveTextMemoryTool(), access_groups=['admin', 'user'])
tools.register_local_tool(VisualizeDataTool(), access_groups=['admin', 'user'])

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=user_resolver,
    agent_memory=agent_memory
)
```

--------------------------------

### Configure Filter Use Cases

Source: https://vanna.ai/docs/placeholder/conversation-filters

Example configurations for common scenarios like long conversations, privacy, and performance.

```python
conversation_filters=[
    SummarizationFilter(summarizer_llm, max_messages=50),
    ContextWindowFilter(max_tokens=8000)
]
```

```python
conversation_filters=[
    SensitiveDataFilter(),
    PIIRemovalFilter(),
    CredentialRedactionFilter()
]
```

```python
conversation_filters=[
    ToolResultCompressionFilter(),
    DeduplicationFilter(),
    ContextWindowFilter(max_tokens=4000)  # Use smaller context
]
```

--------------------------------

### Implement Caching in enhance_system_prompt

Source: https://vanna.ai/docs/placeholder/llm-context-enhancers

This example demonstrates how to implement caching within the `enhance_system_prompt` method to optimize performance by storing and retrieving previously fetched context. It checks the cache before fetching new context and stores it upon retrieval.

```python
class OptimizedEnhancer(LlmContextEnhancer):
    def __init__(self):
        self.cache = {}
        self.cache_ttl = 300  # 5 minutes

    async def enhance_system_prompt(
        self, 
        system_prompt: str,
        user_message: str,
        user: User
    ) -> str:
        # Check cache first
        cache_key = f"{user.id}:{user_message[:50]}"
        if cache_key in self.cache:
            cached, timestamp = self.cache[cache_key]
            if time.time() - timestamp < self.cache_ttl:
                return system_prompt + cached

        # Fetch and cache
        context = await self._fetch_context(user_message)
        self.cache[cache_key] = (context, time.time())

        return system_prompt + context
```

--------------------------------

### Example Chat Request (SSE)

Source: https://vanna.ai/docs/placeholder/deployment/flask

Demonstrates how to send a chat message to the SSE endpoint and process the streaming response.

```APIDOC
### Example Chat Request (SSE)

This example shows how to interact with the Server-Sent Events (SSE) chat endpoint.

### Request Example
```python
import requests
import json

response = requests.post(
    "http://localhost:5000/api/vanna/v2/chat_sse",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    },
    stream=True
)

# Process SSE stream
for line in response.iter_lines():
    if line:
        if line.startswith(b"data: "):
            data = line[6:].decode('utf-8')
            if data != "[DONE]":
                chunk = json.loads(data)
                print(chunk)
```
```

--------------------------------

### Define Specific Behavior for SQL Assistant

Source: https://vanna.ai/docs/placeholder/system-prompts

This example shows how to define specific, actionable guidelines for a SQL assistant within a system prompt. It emphasizes best practices like using table aliases and avoiding SELECT *.

```text
prompt = """You are a SQL query assistant.

IMPORTANT GUIDELINES:

- ALWAYS use table aliases in joins
- NEVER use SELECT *
- PREFER window functions over subqueries
- ALWAYS include LIMIT clauses for exploratory queries
- ASK for clarification if the request is ambiguous
"""
```

--------------------------------

### Implement Custom DataDog Integration

Source: https://vanna.ai/docs/placeholder/observability

Example of a custom provider implementation using the datadog and ddtrace libraries.

```python
from datadog import statsd
from vanna.core.observability import ObservabilityProvider

class DataDogProvider(ObservabilityProvider):
    def __init__(self, tags=None):
        self.default_tags = tags or []
    
    async def record_metric(
        self,
        name: str,
        value: float,
        unit: str = "",
        tags: Optional[Dict[str, str]] = None
    ) -> None:
        # Convert tags dict to list
        tag_list = self.default_tags + [
            f"{k}:{v}" for k, v in (tags or {}).items()
        ]
        
        # Send to DataDog
        if 'duration' in name:
            statsd.histogram(name, value, tags=tag_list)
        elif 'count' in name:
            statsd.increment(name, value, tags=tag_list)
        else:
            statsd.gauge(name, value, tags=tag_list)
    
    async def create_span(self, name, attributes=None):
        # DataDog tracing integration
        from ddtrace import tracer
        span = tracer.trace(name)
        if attributes:
            for k, v in attributes.items():
                span.set_tag(k, v)
        return span
```

--------------------------------

### Define Business Data Semantics in System Prompt

Source: https://vanna.ai/docs/placeholder/system-prompts

This example illustrates how to define key business terms and their meanings within a system prompt. This helps the AI understand and use domain-specific terminology accurately.

```text
prompt += """
## Business Definitions

- Customer: A user who has made at least one purchase
- Active Customer: Purchased within last 90 days
- Revenue: Sum of order_total excluding refunds
- MRR: Sum of subscription amounts for active subscriptions
"""
```

--------------------------------

### Cloud Agent Memory Setup

Source: https://vanna.ai/docs/placeholder/memory-backends

Connects to Vanna Cloud for managed, scalable vector storage suitable for production environments. Requires an API key and workspace ID.

```python
from vanna.integrations.premium.agent_memory import CloudAgentMemory

memory = CloudAgentMemory(
    api_key="your-vanna-api-key",
    workspace_id="your-workspace-id"
)

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=resolver,
    agent_memory=memory
)
```

--------------------------------

### Example Chat Request (SSE)

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

Demonstrates how to send a chat message to the `/api/vanna/v2/chat_sse` endpoint and process the Server-Sent Events response stream.

```APIDOC
### Example Chat Request (SSE)

Demonstrates how to send a chat message to the `/api/vanna/v2/chat_sse` endpoint and process the Server-Sent Events response stream.

```python
import requests
import json

response = requests.post(
    "http://localhost:8000/api/vanna/v2/chat_sse",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    },
    stream=True
)

# Process SSE stream
for line in response.iter_lines():
    if line:
        if line.startswith(b"data: "):
            data = line[6:].decode('utf-8')
            if data != "[DONE]":
                chunk = json.loads(data)
                print(chunk)
```
```

--------------------------------

### ChromaDB Agent Memory Setup

Source: https://vanna.ai/docs/placeholder/memory-backends

Integrates ChromaDB for persistent local vector storage, ideal for development and testing. Configure the collection name and persistence directory.

```python
from vanna.integrations.chromadb import ChromaAgentMemory

memory = ChromaAgentMemory(
    collection_name="vanna_tool_memory",
    persist_directory="./chroma_db"
)

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=resolver,
    agent_memory=memory
)
```

--------------------------------

### Customizing Default Workflow Handler

Source: https://vanna.ai/docs/placeholder/workflow-handlers

Demonstrates how to customize the default workflow handler, for example, by providing a custom welcome message.

```python
from vanna import DefaultWorkflowHandler

# Custom welcome message
handler = DefaultWorkflowHandler(
    welcome_message="# Welcome to AcmeCorp Data Assistant!\n\nI'm here to help with your analytics needs."
)
```

--------------------------------

### Run the Server and Set API Key

Source: https://vanna.ai/docs/tutorials/quickstart-5min

Set the ANTHROPIC_API_KEY environment variable and run the Python application to start the Vanna server. The server will be accessible at http://localhost:8000.

```bash
export ANTHROPIC_API_KEY=sk-ant-...
python app.py
```

--------------------------------

### AgentConfig Setup

Source: https://vanna.ai/docs/placeholder/python

Configure agent behavior with AgentConfig. Customize parameters like tool iterations, response streaming, conversation saving, temperature, and UI/audit features.

```python
from vanna.core.agent import AgentConfig, UiFeatures, AuditConfig

config = AgentConfig(
    max_tool_iterations=10,
    stream_responses=True,
    auto_save_conversations=True,
    temperature=0.7,
    max_tokens=None,
    ui_features=UiFeatures(
        feature_group_access={
            'tool_names': ['admin'],
            'tool_arguments': ['admin'],
            'tool_error': ['admin']
        }
    ),
    audit_config=AuditConfig(
        enabled=True,
        log_tool_invocations=True,
        log_tool_results=True
    )
)
```

--------------------------------

### Vanna 2.0 Database Query Tool Example

Source: https://vanna.ai/docs/vanna-explained-for-business-users

Demonstrates how Vanna 2.0 automatically incorporates user context for database queries. The `context.user` object provides identity and permissions, enabling secure data access without manual checks.

```python
class DatabaseQueryTool(Tool):
    async def execute(self, args, context):
        # context.user automatically has identity & permissions
        connection = get_user_connection(context.user.id)
        results = connection.execute(args.sql)
        return results
```

--------------------------------

### Example Chat Request using Server-Sent Events (SSE)

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

Demonstrates how to send a chat message to the Vanna FastAPI server using SSE and process the streamed response. Includes setting the Authorization header and handling JSON data chunks.

```python
import requests
import json

response = requests.post(
    "http://localhost:8000/api/vanna/v2/chat_sse",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    },
    stream=True
)

# Process SSE stream
for line in response.iter_lines():
    if line:
        if line.startswith(b"data: "):
            data = line[6:].decode('utf-8')
            if data != "[DONE]":
                chunk = json.loads(data)
                print(chunk)
```

--------------------------------

### Docker Compose Configuration for Vanna AI

Source: https://vanna.ai/docs/placeholder/deployment/fastapi

Define and run multi-container Docker applications using Docker Compose. This example sets up Vanna AI, a PostgreSQL database, and specifies environment variables.

```yaml
version: '3.8'

services:
  vanna:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
      - ANTHROPIC_API_KEY=sk-...
    depends_on:
      - db
  
  db:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb
```

--------------------------------

### User-Scoped Memory Example

Source: https://vanna.ai/docs/placeholder/memory-backends

Illustrates how user IDs scope memories, ensuring Alice's searches only retrieve Alice's past tool usage and Bob's retrieve Bob's.

```python
# Each user builds their own memory
user_alice = User(id="alice", ...)
user_bob = User(id="bob", ...)

# Alice's searches only find Alice's past tool usage
# Bob's searches only find Bob's past tool usage
```

--------------------------------

### Initialize Vanna Agent

Source: https://vanna.ai/docs/test-presentation

Demonstrates how to instantiate an agent with specific tools and an LLM provider, then execute a natural language query.

```python
<span class="token keyword">from</span> vanna <span class="token keyword">import</span> Agent
<span class="token keyword">from</span> vanna<span class="token punctuation">.</span>tools <span class="token keyword">import</span> QueryTool

<span class="token comment"># Create your agent</span>
agent <span class="token operator">=</span> Agent<span class="token punctuation">(</span>
    tools<span class="token punctuation">=</span><span class="token punctuation">[</span>QueryTool<span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">]</span><span class="token punctuation">,</span>
    llm<span class="token operator">=</span><span class="token string">"claude-sonnet-4"</span>
<span class="token punctuation">)</span>

<span class="token comment"># Run a query</span>
response <span class="token operator">=</span> agent<span class="token punctuation">.</span>run<span class="token punctuation">(</span><span class="token string">"Show me sales by region"</span><span class="token punctuation">)</span>
```

--------------------------------

### Create Vanna Agent and FastAPI Server

Source: https://vanna.ai/docs/tutorials/quickstart-5min

This Python script sets up a Vanna agent, configures it with an Anthropic LLM and a SQLite runner for the Chinook database, and starts a FastAPI server with a web UI. Replace 'sk-ant-...' with your actual Anthropic API key.

```python
from vanna import Agent, AgentConfig
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.core.registry import ToolRegistry
from vanna.core.user import CookieEmailUserResolver
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.integrations.local.agent_memory import DemoAgentMemory

# 1. Configure tools with permissions
tools = ToolRegistry()
tools.register_local_tool(
    RunSqlTool(sql_runner=SqliteRunner(database_path="./Chinook.sqlite")),
    access_groups=['users']
)

# 2. Create agent with memory
agent = Agent(
    llm_service=AnthropicLlmService(
        model="claude-sonnet-4",
        api_key="sk-ant-..."  # Replace with your API key
    ),
    tool_registry=tools,
    user_resolver=CookieEmailUserResolver(),
    agent_memory=DemoAgentMemory(max_items=1000),
    config=AgentConfig()
)

# 3. Run server with web UI
server = VannaFastAPIServer(agent)
server.run()
```

--------------------------------

### Flask Server Configuration and Run

Source: https://vanna.ai/docs/placeholder/python

Set up and launch a Vanna server using Flask. Create the application instance and specify the host and port for execution.

```python
from vanna.servers.flask import VannaFlaskServer

server = VannaFlaskServer(
    agent=agent,
    config={}
)

app = server.create_app()
server.run(host="0.0.0.0", port=5000)
```

--------------------------------

### Initialize a Basic Vanna Agent

Source: https://vanna.ai/docs/guides/when-to-build-agents

Sets up a minimal agent instance using a mock LLM service and memory storage.

```python
from vanna import Agent, AgentConfig, MockLlmService, ToolRegistry, MemoryConversationStore

agent = Agent(
    llm_service=MockLlmService("I'm ready to help."),
    tool_registry=ToolRegistry(),
    conversation_store=MemoryConversationStore(),
    config=AgentConfig(stream_responses=False),
)
```

--------------------------------

### ToolAccessCheckEvent Example

Source: https://vanna.ai/docs/placeholder/audit-logging

An example of a `ToolAccessCheckEvent` object, used for logging when a user attempts to access a tool. It includes details about the user, the tool, and the access decision.

```python
ToolAccessCheckEvent(
    timestamp=datetime.now(),
    user_id=user.id,
    user_email=user.email,
    tool_name=tool.name,
    access_granted=True,
    user_groups=user.group_memberships,
    required_groups=tool.access_groups
)
```

--------------------------------

### Registering Tools with Vanna Agent

Source: https://vanna.ai/docs/placeholder/custom-tools

Demonstrates how to instantiate the Vanna Agent and register custom tools with it. Ensure your LLM service and SQL runner are properly configured before agent instantiation.

```python
from vanna import Agent

agent = Agent(
    llm_service=llm,
    sql_runner=sql_runner
)

# Register your custom tools
agent.register_tool(WeatherTool(api_key="..."))
agent.register_tool(UserAnalyticsTool(db_connection))
agent.register_tool(CachedSearchTool())
```

--------------------------------

### Initialize Vanna Flask Server

Source: https://vanna.ai/docs/placeholder/deployment/flask

Sets up a standalone Vanna Flask server with Anthropic LLM and Postgres runner.

```python
from vanna import Agent, ToolRegistry
from vanna.servers.flask import VannaFlaskServer
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.integrations.postgres import PostgresRunner
from vanna.tools import RunSqlTool

# Create components
llm_service = AnthropicLlmService(api_key="...")
sql_runner = PostgresRunner(connection_string="...")

# Create tool registry and register tools
registry = ToolRegistry()
registry.register_local_tool(RunSqlTool(sql_runner), access_groups=[])

# Create your agent
agent = Agent(
    llm_service=llm_service,
    tool_registry=registry,
    user_resolver=MyUserResolver(),
    agent_memory=MyAgentMemory()  # Required parameter
)

# Create Flask server
server = VannaFlaskServer(agent)

# Run the server
server.run(host="0.0.0.0", port=5000)
```

--------------------------------

### Implement CustomSystemPromptBuilder

Source: https://vanna.ai/docs/placeholder/system-prompts

Create a specialized builder to inject company-specific domain knowledge and formatting into the system prompt.

```python
from vanna.core.system_prompt import SystemPromptBuilder
from vanna.core.user import User
from typing import List, Dict, Any

class CustomSystemPromptBuilder(SystemPromptBuilder):
    def __init__(self, company_name: str, domain: str):
        self.company_name = company_name
        self.domain = domain
    
    async def build_system_prompt(
        self,
        user: User,
        tool_schemas: List[Dict[str, Any]],
        context: Dict[str, Any]
    ) -> str:
        prompt = f"""You are a data analyst assistant for {self.company_name}.
        
Your role is to help users understand and analyze {self.domain} data.

## Guidelines

1. Always be helpful and professional
2. Explain your reasoning when writing SQL queries
3. Suggest visualizations when appropriate
4. If you're unsure, ask clarifying questions

## Available Tools

"""
        
        # Add tool documentation
        for tool in tool_schemas:
            prompt += f"\n### {tool['name']}\n"
            prompt += f"{tool['description']}\n"
            prompt += f"Parameters: {tool['parameters']}\n"
        
        # Add database-specific guidance
        if 'database_schema' in context:
            prompt += "\n## Database Schema\n"
            prompt += context['database_schema']
        
        # Add user-specific context
        prompt += f"\n## Current User\n"
        prompt += f"Name: {user.username}\n"
        prompt += f"Groups: {', '.join(user.group_memberships)}\n"
        
        return prompt

# Use your custom builder
agent = Agent(
    llm_service=llm,
    sql_runner=sql_runner,
    system_prompt_builder=CustomSystemPromptBuilder(
        company_name="Acme Corp",
        domain="e-commerce"
    )
)
```

--------------------------------

### Implement State-Based Onboarding Workflow

Source: https://vanna.ai/docs/placeholder/workflow-handlers

Uses a WorkflowHandler to track user onboarding progress via metadata and return specific UI components based on the current step.

```python
class OnboardingHandler(WorkflowHandler):
    async def try_handle(self, agent, user, conversation, message):
        # Check if user needs onboarding
        if user.metadata.get("needs_onboarding"):
            step = user.metadata.get("onboarding_step", 1)
            
            if step == 1:
                # Welcome step
                async def update_step(conv):
                    user.metadata["onboarding_step"] = 2
                
                return TriggerResult(
                    triggered=True,
                    components=[
                        RichTextComponent(
                            content="# Welcome to Vanna! 👋\n\nLet's get you set up in 3 quick steps.",
                            markdown=True
                        ),
                        ButtonComponent(
                            label="Get Started",
                            action="Continue onboarding",
                            variant="primary"
                        )
                    ],
                    conversation_mutation=update_step
                )
            
            elif step == 2:
                # Configuration step
                return TriggerResult(
                    triggered=True,
                    components=[
                        StatusCardComponent(
                            title="Step 2: Database Connection",
                            status="pending",
                            description="Let's connect to your database"
                        ),
                        # ... configuration UI
                    ]
                )
        
        return TriggerResult(triggered=False)
```

--------------------------------

### Simulate In-Chat Training Conversation

Source: https://vanna.ai/docs/placeholder/training

Example of the interaction flow where an agent learns from a corrected query.

```text
User: Show me total sales by country
Agent: [Runs incorrect SQL query]
Agent: [Corrects and runs proper query]
Agent: [Saves the correct query to AgentMemory]
```

--------------------------------

### Python Execution Tools

Source: https://vanna.ai/docs/placeholder/built-in-tools

Tools for executing Python code, including running scripts and installing packages.

```APIDOC
## RunPythonFileTool

### Description
Execute Python scripts in a sandboxed environment.

### Method
Not applicable (Tool)

### Endpoint
Not applicable (Tool)

### Parameters
#### Arguments
- **filename** (str) - Required - Path to Python file to execute

### Request Example
```python
from vanna.tools.python import RunPythonFileTool

tool = RunPythonFileTool(file_system=LocalFileSystem())
agent.register_tool(tool)
```

### Response
#### Success Response (200)
- **output** (str) - The standard output of the executed script

#### Response Example
```
"Script execution output..."
```

**Security Note:** Use with caution. Consider restricting to admin users only.
```

```APIDOC
## PipInstallTool

### Description
Install Python packages dynamically.

### Method
Not applicable (Tool)

### Endpoint
Not applicable (Tool)

### Parameters
#### Arguments
- **package_name** (str) - Required - Package to install

### Request Example
```python
from vanna.tools.python import PipInstallTool

tool = PipInstallTool()
agent.register_tool(tool)
```

### Response
#### Success Response (200)
- **status** (str) - Success message indicating package installation

#### Response Example
```
"Package installed successfully."
```

**Security Note:** Restrict to trusted users only.
```

--------------------------------

### Frontend Integration for Feature Access

Source: https://vanna.ai/docs/placeholder/ui-features

Example of checking feature access within a Svelte frontend component.

```javascript
// Svelte example
<script>
  import { page } from '$app/stores';
  
  $: user = $page.data.user;
  $: uiFeatures = $page.data.uiFeatures;
  
  $: canSeeToolArgs = uiFeatures.tool_arguments.includes(user.group);
</script>

{#if canSeeToolArgs}
  <div class="tool-arguments">
    {JSON.stringify(toolArgs)}
  </div>
{/if}
```

--------------------------------

### Example Chat Request (Polling)

Source: https://vanna.ai/docs/placeholder/deployment/flask

Demonstrates how to send a chat message to the polling endpoint and receive a JSON response.

```APIDOC
### Example Chat Request (Polling)

This example shows how to interact with the HTTP polling chat endpoint.

### Request Example
```python
import requests

response = requests.post(
    "http://localhost:5000/api/vanna/v2/chat_poll",
    json={
        "message": "Show me sales by region",
        "conversation_id": "conv_123",
        "metadata": {}
    },
    headers={
        "Authorization": "Bearer your-jwt-token"
    }
)

print(response.json())
```
```

--------------------------------

### Generate Role-Based Starter UI

Source: https://vanna.ai/docs/placeholder/workflow-handlers

Implement a workflow handler to provide role-based starter UI elements, dynamically fetching report tools for analysts or offering a welcome experience for new users.

```python
class StarterUIHandler(WorkflowHandler):
    async def get_starter_ui(self, agent, user, conversation):
        # Role-based starter UI
        if "analyst" in user.group_memberships:
            # Get available report tools dynamically
            tools = await agent.tool_registry.get_schemas(user)
            report_tools = [t for t in tools if t.name.startswith("report_")]
            
            buttons = [
                {
                    "label": f"📊 {tool.name.replace('report_', '').title()} Report",
                    "action": f"/{tool.name}",
                    "variant": "secondary"
                }
                for tool in report_tools[:3]  # Show top 3
            ]
            
            return [
                RichTextComponent(
                    content=f"# Welcome back, {user.username}! 👋\n\nReady to analyze some data?",
                    markdown=True
                ),
                ButtonGroupComponent(
                    buttons=buttons,
                    orientation="vertical"
                )
            ]
        
        elif user.metadata.get("is_new_user"):
            return [
                RichTextComponent(
                    content="# Welcome to Vanna! 🎉\n\nI'm your AI data assistant. Try one of these to get started:",
                    markdown=True
                ),
                ButtonGroupComponent(
                    buttons=[
                        {"label": "📖 Show Tutorial", "action": "/tutorial", "variant": "primary"},
                        {"label": "💡 Example Query", "action": "/example", "variant": "secondary"},
                        {"label": "🔧 Setup Guide", "action": "/setup", "variant": "secondary"}
                    ],
                    orientation="vertical"
                )
            ]
        
        return None  # No starter UI for other users
    
    async def try_handle(self, agent, user, conversation, message):
        # Handle starter UI actions
        if message == "/tutorial":
            return TriggerResult(
                triggered=True,
                components=[
                    # Tutorial content
                ]
            )
        
        return TriggerResult(triggered=False)
```

--------------------------------

### Implement Resilient Tool Execution

Source: https://vanna.ai/docs/placeholder/error-recovery

Example of a tool implementing its own retry logic with exponential backoff for connection errors.

```python
from vanna.core.tool import Tool, ToolResult

class ResilientApiTool(Tool):
    async def execute(self, context: ToolContext, args: MyArgs) -> ToolResult:
        max_retries = 3
        
        for attempt in range(max_retries):
            try:
                result = await self.call_api(args)
                return ToolResult(success=True, result_for_llm=result)
            
            except ConnectionError as e:
                if attempt < max_retries - 1:
                    await asyncio.sleep(2 ** attempt)
                    continue
                else:
                    return ToolResult(
                        success=False,
                        error=f"API call failed after {max_retries} attempts: {e}"
                    )
```

--------------------------------

### Get Tool Usage Statistics

Source: https://vanna.ai/docs/placeholder/memory-backends

Retrieve statistics about tool usage from the agent's memory. Requires a ToolContext.

```python
stats = await agent.agent_memory.get_tool_usage_stats(context)

print(f"Total memories: {stats['total_count']}")
print(f"Tools with memories: {stats['tools']}")
```

--------------------------------

### Run VannaFastAPIServer

Source: https://vanna.ai/docs/configure

Instantiate and run the VannaFastAPIServer with the configured agent. The server will be accessible at http://localhost:8000.

```python
server = VannaFastAPIServer(agent)
server.run()  # Access at http://localhost:8000
```

--------------------------------

### MySQL Integration

Source: https://vanna.ai/docs/placeholder/python

Initialize the MySQL runner.

```python
from vanna.integrations.mysql import MySQLRunner

sql_runner = MySQLRunner(
    host="localhost",
    database="mydb",
    user="user",
    password="pass",
    port=3306
)
```

--------------------------------

### React Integration

Source: https://vanna.ai/docs/placeholder/web-ui

Example of integrating the Vanna web component into a React application using a useEffect hook to load the script.

```javascript
import { useEffect, useRef } from 'react';

function VannaChat() {
    useEffect(() => {
        // Load the web component script
        const script = document.createElement('script');
        script.type = 'module';
        script.src = 'https://img.vanna.ai/vanna-components.js';
        document.head.appendChild(script);
    }, []);
    
    return (
        <vanna-chat
            api-base="http://localhost:8000"
            sse-endpoint="http://localhost:8000/api/vanna/v2/chat_sse"
            ws-endpoint="http://localhost:8000/api/vanna/v2/chat_websocket"
            poll-endpoint="http://localhost:8000/api/vanna/v2/chat_poll"
            style={{ width: '100%', height: '600px', display: 'block' }}
        />
    );
}
```

--------------------------------

### Production Deployment with uWSGI

Source: https://vanna.ai/docs/placeholder/deployment/flask

Instructions for deploying the Vanna Flask application using uWSGI.

```APIDOC
### Using uWSGI

Deploy your Vanna Flask application using uWSGI for production environments.

### Command Example
```bash
pip install uwsgi
uwsgi --http 0.0.0.0:5000 \
  --wsgi-file app.py \
  --callable app \
  --processes 4 \
  --threads 2
```
```
Tokens:
Raw