Voice AI Agent

A Flask-based API service that provides natural language querying capabilities for databases with streaming responses.

Prerequisites

• Python 3.12 or higher
• pip (Python package installer)
• virtualenv

Setup Instructions

1. Clone the repository:

git clone <repository-url>
cd voice-ai-agent

2. Create and activate a virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

4. Create a .env file in the project root with the following variables:

API_KEY=your_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
DATABASE_URL=your_database_url_here
MCP_SERVER_URL=your_mcp_server_url_here

Running the Application

1. Make sure your virtual environment is activated:

source venv/bin/activate  # On Windows use: venv\Scripts\activate

2. Start the Flask server:

flask run --host=0.0.0.0 --port=5000

The API will be available at http://localhost:5000

API Documentation

Database Chat Endpoint

• URL: /api/v1/dbchat/query
• Method: POST
• Headers:
  • X-API-Key: Your API key
  • Content-Type: application/json
  • Accept: text/event-stream
• Request Body:

{
    "query": "Your natural language query here"
}

Testing with Postman

1. Create a new request:

   • Method: POST
   • URL: http://localhost:5000/api/v1/dbchat/query
   • Headers:

     X-API-Key: your_api_key_here
     Content-Type: application/json
     Accept: text/event-stream
     

   • Body (raw JSON):

     {
         "query": "Show me all the tables in the database"
     }
     

2. Configure Postman Settings:

   • Click Settings (⚙️)
   • Go to Settings > General
   • Enable:
     • "Enable automatic response streaming"
     • "Disable response size limit"

Troubleshooting

1. ModuleNotFoundError: If you see errors about missing modules, ensure you've:

   • Activated the virtual environment
   • Installed all requirements: pip install -r requirements.txt

2. Environment Variables: Make sure all required environment variables are set in your .env file

3. Connection Issues: Verify that:

   • Database URL is correct and accessible
   • MCP server is running and accessible
   • OpenAI API key is valid

Development

The project structure follows a modular approach:

voice-ai-agent/
├── app/
│   ├── api/
│   │   └── v1/
│   │       └── routes/
│   ├── core/
│   ├── models/
│   └── services/
├── tests/
├── .env
├── requirements.txt
└── README.md

Genearate uptodate models

bashsqlacodegen --outfile=app/models/generated_models.py "postgresql:/ /neondb_owner:npg_d6FZRvUtX9ym@ep-crimson-frost-a881hwah-pooler.eastus2.azure.neon.tech/neondb?sslmode=require"

License

MIT License

Database Migrations

We use a simple SQL-based migration system to manage database schema changes. All migrations are stored in the migrations/sql/ directory as SQL files.

Migration Files

Migration files follow this naming convention:

NNN_description_of_change.sql

Where NNN is a 3-digit number (e.g., 001, 002) that determines the order in which migrations are run.

Current migrations:

• 001_create_queries_table.sql: Creates the queries table for tracking natural language to SQL conversions
• 002_create_chat_tables.sql: Sets up chat session and message storage

Running Migrations

The migrations are managed by migrations/run_migration.py. You have two options to run migrations:

1. Run a specific migration:

python migrations/run_migration.py <migration_file.sql>

2. Run all pending migrations:

python migrations/run_migration.py --all

When running all migrations, the script will:

1. Show you the list of migrations to be run
2. Ask for confirmation before proceeding
3. Execute migrations in order based on their numeric prefix
4. Roll back automatically if any migration fails

Adding New Migrations

To add a new migration:

1. Create a new SQL file in migrations/sql/
2. Name it with the next number in sequence (e.g., if last is 002, use 003)
3. Write your SQL statements
4. Run the migration using one of the methods above