Skip to content

Latest commit

 

History

History
222 lines (171 loc) · 8.05 KB

README.md

File metadata and controls

222 lines (171 loc) · 8.05 KB

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

100% Local Zero API Cost Execution Accuracy Model Size By Tokligence

🎯 88% 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: 3.7-5.4 seconds average response time
  • 📊 Proven: 88% execution accuracy on Spider benchmark (NEW: qwen3-coder:30b)

🏗️ Architecture

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

🚀 Quick Start

1. Install Ollama

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

# Pull the best model (18GB, requires 25GB RAM)
ollama pull qwen3-coder:30b

# Or for limited resources (4.7GB, requires 6GB RAM)
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 Models

Best Performance: qwen3-coder:30b (NEW!)

  • 88% execution accuracy on Spider benchmark* - Highest accuracy achieved!
  • 3.69s average response time - 32% faster than qwen2.5-coder
  • 18GB disk space (MoE: 30B total, 3.3B active)
  • ~25GB RAM required
  • Key advantage: Mixture-of-Experts architecture delivers superior performance

Best for Limited Resources: qwen2.5-coder:7b

  • 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)

All Models Tested

Model EA (%) Speed Size Verdict
qwen3-coder:30b 🆕 88% 3.69s 18GB ✅ Best overall
qwen2.5-coder:7b 86% 5.41s 4.7GB ✅ Best for limited RAM
codestral:22b 82% 30.6s 12GB ⚠️ Too slow
qwen2.5:14b 82% 10.0s 9.0GB ❌ General model
deepseek-coder:6.7b 72% 6.64s 3.8GB ⚠️ Lower accuracy
deepseek-coder-v2:16b 68% 4.0s 8.9GB ⚠️ Lower accuracy

Key Finding: MoE architecture (qwen3-coder:30b) achieves best results - 88% EA with only 3.3B active params!

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.)
  • Achieves up to 88% accuracy through error recovery (qwen3-coder:30b)

🌐 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)

qwen3-coder:30b (Best Model)

  • Execution Accuracy (EA): 88% 🏆
  • Average Latency: 3.69s ⚡
  • Average Attempts: 2.5
  • Success Rate: 100% (with retries)

qwen2.5-coder:7b (Resource-Efficient)

  • 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="qwen3-coder:30b",  # Use best model for highest accuracy
    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!