🚀 LocalSQLAgent - 100% Local Text-to-SQL AI System

🎯 86% execution accuracy on Spider benchmark with zero API costs and 100% data privacy

🌐 Bilingual support - Works perfectly with English and Chinese queries

English | 中文文档

🔥 Why LocalSQLAgent?

The Problem with Cloud Solutions

• 💸 Ongoing Costs: Continuous API fees that scale with usage
• 🔓 Privacy Risk: Your sensitive data leaves your infrastructure
• 🌐 Network Dependency: Requires internet, adds latency
• 🚫 Compliance Issues: Many industries can't send data to cloud

Our Solution: 100% Local AI

• ✅ Zero Cost: No API fees, ever
• 🔒 100% Private: Data never leaves your machine
• ⚡ Fast: 5-6 seconds average response time
• 📊 Proven: 86% execution accuracy on Spider benchmark

🏗️ Architecture

┌──────────────────────────────────────────────────────────────────┐
│                     🏠 Your Local Environment                      │
│                                                                   │
│  ┌────────────┐     ┌─────────────────┐     ┌─────────────────┐ │
│  │   User     │────▶│  LocalSQLAgent  │────▶│  Ollama + LLM   │ │
│  │   Query    │     │  (Intelligent   │     │ qwen2.5-coder:7b│ │
│  └────────────┘     │    Agent)       │     └─────────────────┘ │
│                     └────────┬─────────┘                         │
│                              ▼                                   │
│                     ┌──────────────────────────────┐            │
│                     │    Your Databases           │            │
│                     │ PostgreSQL│MySQL│MongoDB│... │            │
│                     └──────────────────────────────┘            │
│                                                                   │
│  💰 $0 Cost    🔒 100% Private    ⚡ 5.4s Avg    📊 86% EA      │
└──────────────────────────────────────────────────────────────────┘

🚀 Quick Start

1. Install Ollama

# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh

# Pull the recommended model (4.7GB)
ollama pull qwen2.5-coder:7b

2. Install LocalSQLAgent

git clone https://github.com/tokligence/LocalSQLAgent.git
cd LocalSQLAgent
pip install -e .

3. Run Your First Query

from localsql import IntelligentSQLAgent

# Connect to your database
agent = IntelligentSQLAgent("postgresql://localhost/mydb")

# Ask questions in natural language
result = agent.query("Show me top 10 customers by revenue last month")
print(result)

📊 Performance & Model Selection

Recommended Model

✅ qwen2.5-coder:7b - Best balance of accuracy, speed, and resource usage

• 86% execution accuracy on Spider benchmark*
• 5.4s average response time
• 4.7GB disk space
• ~6GB RAM required

*Tested on MacBook Pro (M-series, 48GB RAM) with Spider dev dataset (50 samples)

Alternative Models Tested

Model	EA (%)	Speed	Verdict
qwen2.5-coder:7b	86%	5.4s	✅ Best Choice
deepseek-coder-v2:16b	68%	4.0s	✅ Good alternative
codestral:22b	82%	30.6s	⚠️ Too slow
qwen2.5:14b	82%	10.0s	❌ General model, not optimized

Key Finding: Smaller domain-specific models outperform larger general models for SQL tasks

View detailed model analysis →

💡 Key Features

🧠 Intelligent Error Learning

• Automatically learns from SQL execution errors
• Self-corrects common mistakes (ambiguous columns, missing GROUP BY, etc.)
• Improves accuracy from 82% to 86% through error recovery

🌐 True Bilingual Support

# English
result = agent.query("Show me sales trends")

# 中文同样完美支持
result = agent.query("显示上个月销售前10的产品")

🔌 Multi-Database Support

• PostgreSQL, MySQL, SQLite
• MongoDB (via SQL interface)
• ClickHouse, DuckDB
• Any SQL-compatible database

🚀 Production Ready

• REST API with FastAPI
• Docker support
• Concurrent request handling (10+ QPS)
• Comprehensive test suite

📈 Benchmarks

Spider Dataset Results (50 samples)

• Execution Accuracy (EA): 86%
• Average Latency: 5.41s
• Average Attempts: 2.5
• Success Rate: 100% (with retries)

Multi-Attempt Strategy

Attempts	EA (%)	Latency	Finding
1	84%	2.4s	Fast but may fail
5	85%	4.0s	+1% EA improvement
7	85%	4.8s	No further gain

Recommendation: Use 1-3 attempts for best speed/accuracy balance

🛠️ Advanced Usage

API Server

# Start the API server
python api_server.py

# Query via HTTP
curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Show me all users who joined this month"}'

Docker Deployment

docker build -t localsqlagent .
docker run -p 8000:8000 localsqlagent

Custom Model Configuration

agent = IntelligentSQLAgent(
    db_url="postgresql://localhost/mydb",
    model_name="deepseek-coder-v2:16b",  # Use alternative model
    max_attempts=3,
    temperature=0.1
)

💰 Solution Comparison

Solution	Cost Model	Data Privacy	Setup Time
LocalSQLAgent	Free Forever	✅ 100% Local	5 minutes
Cloud APIs	Usage-based billing	⚠️ Data leaves premises	30 minutes
Self-hosted GPU	Infrastructure costs	✅ Local	Days-Weeks

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

📄 License

Apache 2.0 - Free for commercial use

🙏 Acknowledgments

• Powered by Ollama
• Spider dataset from Yale University
• Built with love by Tokligence

---

Ready to eliminate API costs? Star ⭐ this repo and get started in 5 minutes!