Database Query Agent

An intelligent agent that processes natural language questions, converts them to SQL queries, and returns answers in natural language.

Features

• Processes questions in natural language
• Automatically generates SQL queries based on the question
• Executes the queries against a database
• Returns answers in natural language

Requirements

• Python 3.10 or higher
• Groq API key

Installation

1. Clone this repository:

   git clone https://github.com/yourusername/agent-textsql.git
   cd agent-textsql
   

2. Create a virtual environment and activate it:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install the dependencies:

   Basic installation (SQLite only):

   pip install -e .
   

   For PostgreSQL support:

   pip install -e .[postgresql]
   

   For MySQL support:

   pip install -e .[mysql]
   

   For SQL Server support:

   pip install -e .[sqlserver]
   

   For all database types:

   pip install -e .[all]
   

4. Set your Groq API key using one of these methods:

   Option A: Create a .env file in the project root (recommended):

   # Create a .env file with your API key
   echo "GROQ_API_KEY=your-api-key" > .env
   

   Option B: Set the environment variable directly:

   export GROQ_API_KEY='your-api-key'  # On Windows: set GROQ_API_KEY=your-api-key
   

Usage

To run the agent, you need to provide a database URL:

python main.py --db-url "your-database-url"

Where your-database-url is a SQLAlchemy connection string for your database.

Examples:

• SQLite: sqlite:///path/to/your/database.db
• PostgreSQL: postgresql://username:password@host:port/database
• MySQL: mysql://username:password@host:port/database
• SQL Server: mssql+pyodbc://username:password@host:port/database?driver=ODBC+Driver+17+for+SQL+Server

Example Questions

Here are some example types of questions you can ask (adapt to your database schema):

• "How many records are in the [table] table?"
• "What are the top 3 [items] by [attribute]?"
• "Show me the [attribute] with the most [related items]"
• "What is the total [numeric value] from all [items]?"
• "How many [items] are in the [category] category?"
• "What is the average [value] of [items]?"
• "Which [item] has the highest [attribute]?"

Database Schema Requirements

For the agent to work effectively with your database:

1. Make sure your database has proper foreign key relationships defined
2. Table and column names should be descriptive and follow standard naming conventions
3. If your database schema is complex, you may want to create views that simplify the structure

Customization

Using Different Database Types

The agent supports any database type that SQLAlchemy can connect to. You may need to install additional Python packages for specific database types:

• PostgreSQL: pip install psycopg2-binary
• MySQL: pip install pymysql
• SQL Server: pip install pyodbc

Additional Connection Options

You can add additional connection options to the database URL as needed:

python main.py --db-url "postgresql://user:pass@host:port/db?sslmode=require"

Project Structure

The code is organized in a modular structure:

• src/utils.py: Utility functions for text processing
• src/agent.py: The DatabaseAgent class that handles database queries
• src/main.py: Main application logic and CLI interface
• main.py: Entry point that imports and runs the main function

Extending the Agent

To extend the agent's capabilities:

1. Modify the DatabaseAgent class in src/agent.py to add new features
2. Add utility functions in src/utils.py for text processing or other helpers
3. Customize the prompts in src/agent.py to better match your specific database schema
4. Add additional validation or preprocessing for specific types of questions

License

MIT