Vanna

Common errors

• ModuleNotFoundError: No module named 'vanna.openai'

  cause The optional `openai` dependency was not installed along with `vanna`.
  fix Install Vanna with the OpenAI extra: `pip install "vanna[openai]"`.

• AuthenticationError: Incorrect API key provided

  cause The OpenAI (or other LLM) API key is missing, incorrect, or expired.
  fix Set the `OPENAI_API_KEY` environment variable correctly, or pass a valid API key via the `config` dictionary during LLM initialization.

• AttributeError: 'Vanna' object has no attribute 'train_sql'

  cause Attempting to use pre-2.0 training methods like `train_sql` or `train_ddl` with Vanna 2.0.0+.
  fix In Vanna 2.0.0+, all training methods are consolidated under `vn.train()`. Use `vn.train(sql=...)`, `vn.train(ddl=...)`, `vn.train(question=...)`, etc.

• TypeError: __init__ missing 1 required positional argument: 'config'

  cause When creating a custom Vanna instance by inheriting from `VannaBase`, `LLM`, and `VectorStore` components, the `__init__` methods of the base classes (like `ChromaDB_VectorStore` or `OpenAI_Chat`) expect a `config` dictionary.
  fix Ensure that your custom Vanna class's `__init__` method correctly calls the `__init__` methods of its parent components with a `config` dictionary, even if empty. Example: `ChromaDB_VectorStore.__init__(self, config=config)`.

Warnings

• breaking Vanna 2.0.0 represents a complete architectural rewrite. Code written for pre-2.0 versions will likely break due to significant API changes, especially around `Vanna` class instantiation, training methods, and connector configuration.
  Fix: Refer to the Vanna 2.0 documentation and migration guides. Re-architect your Vanna instance creation using the new inheritance model (e.g., `class MyVanna(VectorStore, LLM, VannaBase)`) or use `VannaDefault` for quick setups. Update method calls like `train_sql` to `train`.
• gotcha Vanna requires additional packages for specific LLMs (e.g., OpenAI, Anthropic) and Vector Stores (e.g., ChromaDB, Pinecone, pgvector). The base `pip install vanna` does not include these.
  Fix: Install Vanna with the necessary extras, e.g., `pip install "vanna[openai]"` for OpenAI integration, `pip install "vanna[chromadb]"` for ChromaDB, or `pip install "vanna[duckdb]"` for local DuckDB use with `VannaDefault`.
• gotcha API keys for LLMs (like OpenAI) are critical for Vanna's functionality. Incorrect or missing keys will lead to authentication errors.
  Fix: Ensure your LLM API key is correctly configured. For OpenAI, set the `OPENAI_API_KEY` environment variable or pass it directly in the `config` dictionary when initializing your LLM component, e.g., `OpenAI_Chat(config={'api_key': 'YOUR_KEY'})`.

Install

• pip install vanna Basic Install

Imports

• VannaDefault
  wrong:

  from vanna import Vanna

  correct:

  from vanna.local import VannaDefault

  Vanna 2.0 introduces `VannaDefault` for simplified local setup, replacing direct instantiation of `Vanna` or a custom class based on `VannaBase`, `LLM`, and `VectorStore` components for quickstarts.
• VannaBase

  from vanna.base import VannaBase

  Used for building custom Vanna instances by inheriting from LLM and VectorStore components.
• OpenAI_Chat

  from vanna.openai import OpenAI_Chat

  Required for integrating with OpenAI LLM models.
• ChromaDB_VectorStore

  from vanna.chromadb import ChromaDB_VectorStore

  Required for integrating with ChromaDB as a vector store.

Quickstart

This quickstart demonstrates how to use `VannaDefault` for a local setup. It initializes Vanna with OpenAI and a local DuckDB, trains it with schema and example questions, and then generates and runs SQL for a natural language query. Ensure you have the `OPENAI_API_KEY` environment variable set or replace the placeholder.

import os
from vanna.local import VannaDefault
import pandas as pd

# For local testing, VannaDefault uses DuckDB and OpenAI as defaults.
# Ensure OPENAI_API_KEY is set in your environment.
# pip install "vanna[duckdb]" "vanna[openai]"

# Initialize VannaDefault with your OpenAI API key and preferred model
vn = VannaDefault(
    model='gpt-4o',
    api_key=os.environ.get('OPENAI_API_KEY', 'YOUR_OPENAI_API_KEY'), # Replace with actual key or set env var
    path='my_vanna_db' # Path for local ChromaDB and DuckDB storage
)

# Connect to a database (DuckDB is default for VannaDefault)
vn.run_sql_query("CREATE TABLE sales (id INT, product TEXT, amount INT)")
vn.run_sql_query("INSERT INTO sales (id, product, amount) VALUES (1, 'Apple', 100), (2, 'Banana', 150)")

# Train Vanna with DDL, documentation, and example questions/SQL
vn.train(ddl="CREATE TABLE employees (id INT, name TEXT, salary INT)")
vn.train(question="What are the total sales for each product?", sql="SELECT product, SUM(amount) FROM sales GROUP BY product")
vn.train(sql="SELECT * FROM sales", df=pd.DataFrame({'id': [1], 'product': ['Apple'], 'amount': [100]}))

# Ask a question
question = "Show me the sum of sales for each product"
sql = vn.generate_sql(question=question)
print(f"Generated SQL: {sql}")

# Run the generated SQL
if sql:
    results = vn.run_sql(sql=sql)
    print(f"Query Results:\n{results}")
else:
    print("Could not generate SQL for the question.")