Text2SQL AI Assistant with Visualization

A powerful AI agent that transforms natural language questions into SQL queries, executes them against a database, and generates interactive visualizations. Built with CrewAI, Streamlit, and Plotly.

Features

• Natural Language to SQL: Ask questions in plain English
• Multi-Agent System: Specialized agents for SQL generation, validation & analysis
• Interactive Visualizations: Auto-detected charts (bar, line, pie, scatter)
• Complex DB Handling: Supports Sakila DB with 23 interconnected tables
• Query Safety: Prevents SQL injection and harmful operations
• Data Export: Download results as CSV/JSON

Tech Stack

Installation

1. Clone Repository

git clone https://github.com/gitprajapati/crewai-sql-visual-agent.git
cd crewai-sql-visual-agent

2. Initialize Environment

uv init
uv venv

3. Activate Virtual Environment

# Linux/MacOS
source .venv/bin/activate

# Windows
.\.venv\Scripts\activate

4. Install Dependencies

uv sync

5. Set Up Sakila Database

1. Download Sakila database:
   • sakila-schema.sql
   • sakila-data.sql
2. Load into MySQL:

mysql> SOURCE sakila-schema.sql;
mysql> SOURCE sakila-data.sql;

6. Configure Environment Variables

Create .env file:

DB_HOST=localhost
DB_USER=root
DB_PASSWORD=adminpass
DB_NAME=sakila
DB_PORT=3306

# Choose one LLM provider
GROQ_API_KEY=your_groq_key
# OR
GEMINI_API_KEY=your_gemini_key
# OR
REPLICATE_API_TOKEN=your_replicate_token

Usage

uv streamlit run main.py

Configuration Options

Database Settings

# DatabaseConfig in sql_connection_tool.py
self.host = os.getenv("DB_HOST", "localhost")
self.username = os.getenv("DB_USER", "root")
self.password = os.getenv("DB_PASSWORD", "adminpass")
self.database = os.getenv("DB_NAME", "sakila")
self.port = int(os.getenv("DB_PORT", 3306))

LLM Selection

Modify Text2SQLAgent class to use your preferred LLM:

# In Text2SQLAgent.__init__
self.llm = LLM(
    model="gemini/gemini-2.5-flash-preview-04-17",  # Gemini
    # model="groq/llama-3.3-70b-versatile",         # Groq
    # model="replicate/meta/meta-llama-3-8b-instruct" # Replicate
    temperature=0.3
)

Features Overview

Here's the Mermaid diagram of your Text2SQL agent workflow based on the provided code:

graph TD
    A[User Question] --> B[Text2SQLAgent.process_question]
    B --> C[Generate SQL with LLM]
    C --> D[Extract SQL from Response]
    D --> E[Validate & Optimize Query]
    E --> F[Execute Query with Retry]
    F --> G{Success?}
    G -->|Yes| H[Analyze Results]
    G -->|No| I[Attempt Query Fix]
    I --> F
    H --> J[Prepare Visualization Data]
    J --> K[Return Results]

    subgraph SQL Generation
        C --> C1[SQLGenerator Agent]
        C1 --> C2[Create SQL Generation Task]
        C2 --> C3[Crew Execution]
    end

    subgraph Validation
        E --> E1[SQLValidator Agent]
        E1 --> E2[Create Validation Task]
        E2 --> E3[Crew Execution]
    end

    subgraph Analysis
        H --> H1[DataAnalyst Agent]
        H1 --> H2[Create Analysis Task]
        H2 --> H3[Crew Execution]
    end

    subgraph Execution
        F --> F1[SQLConnectionTool]
        F1 --> F2[Safety Check]
        F2 --> F3[Execute Query]
        F3 --> F4{Error?}
        F4 -->|No| G
        F4 -->|Yes| F5[Retry Mechanism]
    end

    subgraph Visualization
        J --> J1[Determine Chart Type]
        J1 --> J2[Generate Plotly Figure]
    end

    A --> C
    D --> E
    E --> F
    F --> G
    G -->|Yes| H
    H --> J
    J --> K[Display Results]
    G -->|No| I
    I --> C1

Loading

Natural Language Processing

graph LR
A[User Question] --> B[SQL Generator Agent]
B --> C[SQL Query]
C --> D[Validator Agent]
D --> E[Optimized Query]
E --> F[Execution]

Loading

Visualization Engine

graph TD
A[Query Results] --> B{Data Analysis}
B -->|Numeric Data| C[Bar/Line Charts]
B -->|Categorical| D[Pie Charts]
B -->|Time Series| E[Trend Lines]
B -->|Multi-Variable| F[Scatter Plots]

Loading

Sample Questions

1. "Show monthly revenue trends"
2. "Top 10 customers by rental count"
3. "Most popular film categories by store"
4. "Average rental duration by rating"
5. "Revenue comparison between stores"

Troubleshooting

MySQL Connection Issues:

• Verify Sakila DB is loaded: SHOW TABLES FROM sakila;
• Check user privileges: GRANT ALL PRIVILEGES ON sakila.* TO 'root'@'localhost';

API Key Errors:

• Ensure correct .env configuration
• Verify provider account status

Visualization Issues:

• Try different chart types from dropdown
• Check data types in results