SQL Agent API

AI-powered database query service using natural language processing. Built with clean architecture principles and FastAPI.

Features

• 🤖 Natural language to SQL query conversion using AI models
• 🗃️ SQLite database support
• 🏗️ Clean architecture with clear separation of concerns
• 🚀 Fast and modern API built with FastAPI
• 📊 Automatic API documentation with Swagger/OpenAPI
• 🔧 Configurable AI models (Gemini, OpenAI, Groq)
• 📝 Comprehensive logging
• 🔍 Database schema exploration
• ⚡ Health check endpoints

Architecture

The project follows clean architecture principles with these layers:

sqlagent/
├── domain/          # Core business logic and entities
├── application/     # Use cases and application services
├── infrastructure/  # Database connections, external services
├── presentation/    # API controllers and DTOs
├── config.py        # Configuration management
└── main.py         # FastAPI application

Quick Start

Prerequisites

• Python 3.9+
• uv (recommended) or pip

Installation

1. Clone the repository:

git clone https://github.com/mehdiozdemir/sqlAgent.git
cd sqlAgent

2. Install uv (if not already installed):

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: using pip
pip install uv

3. Install dependencies:

# Using uv (recommended)
uv sync

# Alternative: using pip
pip install -e .

4. Set up environment variables:

# Create .env file with your API keys
cp .env.example .env
# Edit .env with your actual API keys

Running the Service

Option 1: Using the startup script (recommended)

uv run python run_server.py

Option 2: Using uvicorn directly

uv run uvicorn sqlagent.main:app --reload --host 0.0.0.0 --port 8000

Option 3: Traditional approach

# Activate virtual environment and run
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
python run_server.py

The API will be available at:

• API: http://localhost:8000
• Documentation: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

API Endpoints

Health Check

• GET /health/ - Service health check
• GET /health/database - Database connection health check

Database Operations

• GET /database/info - Get database information
• GET /database/tables - List all tables
• GET /database/tables/{table_name} - Get table schema

Query Processing

• POST /query/natural-language - Process natural language queries

Example Usage

Get Database Tables

curl -X GET "http://localhost:8000/database/tables"

Process Natural Language Query

curl -X POST "http://localhost:8000/query/natural-language" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How many albums are in the database?",
    "limit": 10
  }'

Get Table Schema

curl -X GET "http://localhost:8000/database/tables/Album"

Configuration

The service can be configured using environment variables or a .env file:

# Database Configuration
DATABASE_PATH=sqlagent/Chinook_Sqlite.sqlite  # Your-db-path

# AI Model Configuration
AI_MODEL_TYPE=gemini  # Options: gemini, openai, groq, for local models use openai and set api key "dummy"

# API Keys
GEMINI_API_KEY=your_gemini_api_key
GROQ_API_KEY=your_groq_api_key
OPENAI_API_KEY=your_openai_api_key

OPENAI_BASE_URL=LOCAL_MODEL_URL  # Use for local models (Ollama, LMstudio)

# Server Configuration
HOST=0.0.0.0
PORT=8000

# Logging
LOG_LEVEL=INFO

AI Models

The service supports multiple AI models:

• Gemini (default): Google's Gemini models
• OpenAI: OpenAI GPT models (including local models via compatible APIs)
• Groq: Groq's fast inference models

Configure the model type using the AI_MODEL_TYPE environment variable.

API Key Setup

1. Gemini: Get your API key from Google AI Studio
2. OpenAI: Get your API key from OpenAI Dashboard
3. Groq: Get your API key from Groq Console

Database Support

Currently supports SQLite databases. The service includes a sample Chinook database for testing.

Development

Project Structure

sqlagent/
├── domain/
│   ├── entities.py      # Data models and entities
│   └── interfaces.py    # Abstract interfaces
├── application/
│   └── use_cases.py     # Business logic use cases
├── infrastructure/
│   ├── database.py      # Database repository implementation
│   └── ai_agent.py      # AI agent service implementation
├── presentation/
│   ├── controllers.py   # FastAPI route handlers
│   └── dependencies.py  # Dependency injection
├── config.py           # Configuration management
└── main.py            # FastAPI application setup

Troubleshooting

Common Issues

1. API Key Not Found: Make sure your .env file contains the correct API key for your chosen model
2. Port Already in Use: Change the port in .env file or kill the process using port 8000
3. Database Connection: Ensure the SQLite database file exists and is readable

Logs

Check the log file for detailed error information:

tail -f logs/sql_agent.log

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Ensure code quality checks pass
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For questions and support, please open an issue on the GitHub repository.