aiqwal 1.0.0

AI Query Writer for Any Language - Universal SQL generator that works with ANY database

AIQWAL - AI Query Writer for Any Language

🌍 Universal AI-powered SQL generator that works with ANY database in the world!

🚀 What is AIQWAL?

AIQWAL (AI Query Writer for Any Language) is a revolutionary Python library that converts natural language questions into SQL queries using AI, then executes them on ANY database in the world.

✨ Key Features

• 🤖 AI-Powered: Uses advanced language models.
• 🌍 Universal Database Support: Works with 15+ database types
• 🔄 Auto-Adaptation: Automatically converts SQL syntax for each database
• 🛡️ Smart Validation: Prevents dangerous operations and validates queries
• 🎯 Zero Configuration: Just provide a connection string!
• ⚡ Production Ready: Comprehensive error handling and logging

🎯 Supported Databases

Database	Status	Connection Example
SQLite	✅	sqlite:///database.db
PostgreSQL	✅	postgresql://user:pass@host:5432/db
MySQL	✅	mysql://user:pass@host:3306/db
SQL Server	✅	mssql+pyodbc://user:pass@host/db
Oracle	✅	oracle+cx_oracle://user:pass@host:1521/db
Snowflake	✅	snowflake://user:pass@account/db
BigQuery	✅	bigquery://project/dataset
Redshift	✅	redshift+psycopg2://user:pass@host/db
MongoDB	✅	mongodb://host/db (via SQL interface)
Any SQLAlchemy DB	✅	Any valid SQLAlchemy connection string

🔧 Installation

# Basic installation
pip install aiqwal

# With all database drivers
pip install aiqwal[all]

# Development installation  
pip install aiqwal[dev]

Prerequisites

1. AI Model: Download a compatible model (e.g., SQLCoder):

# Download SQLCoder model (recommended)
python -c "
import requests
url = 'https://huggingface.co/defog/sqlcoder-7b-2/resolve/main/sqlcoder-7b-q4_k_m.gguf'
response = requests.get(url)
with open('sqlcoder-7b-q4_k_m.gguf', 'wb') as f:
    f.write(response.content)
"

2. Database Drivers: Install drivers for your databases:

# PostgreSQL
pip install psycopg2-binary

# MySQL  
pip install pymysql

# SQL Server
pip install pyodbc

# Oracle
pip install cx-oracle

# Snowflake
pip install snowflake-sqlalchemy

# BigQuery
pip install pybigquery

🚀 Quick Start

Basic Usage

from aiqwal import AIQWAL

# Connect to any database (SQLite example)
ai = AIQWAL('sqlite:///employees.db')

# Ask questions in natural language!
results = ai.query("Show me the top 10 highest paid employees")
print(results)
# [{'name': 'John Doe', 'salary': 95000}, ...]

# Works with complex queries too
results = ai.query("Find average salary by department for employees hired after 2020")
print(results)

Different Databases

# PostgreSQL
ai = AIQWAL('postgresql://user:password@localhost:5432/company')
results = ai.query("Show me monthly sales trends")

# MySQL
ai = AIQWAL('mysql://user:password@localhost:3306/ecommerce') 
results = ai.query("Find top selling products this quarter")

# SQL Server
ai = AIQWAL('mssql+pyodbc://user:password@server/database')
results = ai.query("Get customer retention rates by region")

# Snowflake
ai = AIQWAL('snowflake://user:password@account/database/schema')
results = ai.query("Analyze user engagement metrics")

# The same code works with ANY database!

Advanced Usage

from aiqwal import AIQWAL

# Initialize with custom model
ai = AIQWAL(
    connection_string='postgresql://user:pass@host/db',
    model_path='/path/to/your/model.gguf',
    auto_connect=True
)

# Generate SQL without executing (for review)
sql = ai.generate_sql_only("Find customers who haven't ordered in 30 days")
print(f"Generated SQL: {sql}")

# Execute raw SQL
results = ai.execute_sql("SELECT COUNT(*) FROM orders WHERE date > '2024-01-01'")

# Get database information
info = ai.get_database_info()
print(f"Connected to: {info['name']}")

# Get schema
schema = ai.get_schema()
print(f"Available tables: {list(schema.keys())}")

CLI Usage

# Interactive mode
aiqwal interactive --db "postgresql://user:pass@host/db"

# Single query
aiqwal query --db "sqlite:///mydb.db" --query "Show top 10 sales"

# Generate SQL only
aiqwal generate --db "mysql://user:pass@host/db" --query "Find active users"

🎯 Real-World Examples

E-commerce Analytics

ai = AIQWAL('postgresql://user:pass@host/ecommerce_db')

# Sales analysis
sales = ai.query("Show monthly revenue trends for the last 12 months")

# Customer insights  
customers = ai.query("Find top 20 customers by total purchase value")

# Product performance
products = ai.query("Which products have the highest return rates?")

HR Analytics

ai = AIQWAL('mysql://user:pass@host/hr_system')

# Employee metrics
employees = ai.query("Show average salary by department and experience level")

# Hiring analysis
hiring = ai.query("What's our hiring trend by month for the last 2 years?")

# Retention insights
retention = ai.query("Calculate employee turnover rate by department")

Financial Reporting

ai = AIQWAL('mssql+pyodbc://user:pass@server/financial_db')

# Revenue analysis
revenue = ai.query("Break down revenue by product line and quarter")

# Expense tracking
expenses = ai.query("Show top expense categories for this fiscal year")

# Profitability
profit = ai.query("Calculate profit margins by business unit")

🔧 Configuration

Model Configuration

# Use different AI models
ai = AIQWAL(
    connection_string='your-db-connection',
    model_path='/path/to/codellama-sql.gguf',  # CodeLlama
    # model_path='/path/to/wizardcoder-sql.gguf',  # WizardCoder
)

Database-Specific Options

# SQL Server with specific driver
ai = AIQWAL(
    'mssql+pyodbc://user:pass@server/db?driver=ODBC+Driver+17+for+SQL+Server',
    auto_connect=True
)

# PostgreSQL with SSL
ai = AIQWAL(
    'postgresql://user:pass@host:5432/db?sslmode=require',
    auto_connect=True  
)

🛡️ Security & Safety

AIQWAL includes built-in safety features:

• Query Validation: Prevents dangerous operations (DROP, DELETE, etc.)
• SQL Injection Protection: Uses parameterized queries
• Schema Validation: Ensures queries reference valid tables/columns
• Connection Security: Supports SSL/TLS for database connections

# These will be safely rejected:
ai.query("DROP TABLE users")  # ❌ Dangerous operation blocked
ai.query("DELETE FROM orders")  # ❌ Modification blocked  
ai.query("Show me customers")  # ✅ Safe SELECT query allowed

🧪 Testing

# Run all tests
pytest

# Test specific database
pytest tests/test_postgresql.py

# Test with coverage
pytest --cov=aiqwal tests/

# Integration tests
pytest tests/test_integration.py

📊 Performance

AIQWAL is designed for production use:

• Model Loading: 2-5 seconds (cached after first use)
• Query Generation: 1-10 seconds (depending on complexity)
• Query Execution: Database-dependent
• Memory Usage: ~500MB-2GB (model-dependent)

Benchmarks

Database	Connection Time	Query Generation	Simple Query	Complex Query
SQLite	<100ms	2-5s	<100ms	100-500ms
PostgreSQL	100-300ms	2-5s	50-200ms	200-1s
MySQL	100-300ms	2-5s	50-200ms	200-1s
SQL Server	200-500ms	2-5s	100-300ms	300-2s

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

# Clone repository
git clone https://github.com/yourusername/aiqwal.git
cd aiqwal

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

📚 Documentation

• Full Documentation
• API Reference
• Database Support
• Examples

🐛 Troubleshooting

Common Issues

Model Loading Error:

# Ensure model file exists and is compatible
import os
print(os.path.exists('path/to/model.gguf'))

Database Connection Error:

# Test connection string
ai = AIQWAL('your-connection-string')
print(ai.test_connection())

Query Generation Issues:

# Check database schema
schema = ai.get_schema()
print("Available tables:", list(schema.keys()))

Getting Help

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 📧 Email Support

📄 License

AIQWAL is licensed under the MIT License. See LICENSE for details.

🙏 Acknowledgments

• SQLCoder for the excellent SQL generation model
• llama.cpp for efficient model inference
• SQLAlchemy for universal database connectivity
• The open-source community for continuous inspiration

⭐ Star History

If you find AIQWAL useful, please consider starring the repository!

---

Made with ❤️ by the AIQWAL team

Transform natural language into SQL queries for ANY database in the world!