NexusSQL

Agentic SQL Agent — Natural Language to SQL with Multi-step Reasoning

GitHub · SQLAS Eval Framework · 📄 Paper

📄 Paper

NexusSQL: Production SQL Agent for 100+ Table Databases with SQLAS Evaluation Author: thepradip

Published May 14, 2026 · View Paper · View PDF

NexusSQL transforms natural language into SQL using a ReAct agentic loop — the agent inspects your schema, reasons step-by-step, and runs multiple queries before answering. Works with any SQL database, any LLM, and scales to 100+ tables with zero configuration.

Author: Pradip Tivhale

Quick Start

git clone https://github.com/thepradip/NexusSQL.git && cd NexusSQL
cd backend && pip install -r requirements.txt && cp .env.example .env
python ingest.py && uvicorn main:app --reload
# frontend: cd frontend && npm install && npm run dev

Agentic Reasoning

• ReAct loop — Reason → call tool → observe result → repeat until confident
• 4 tools: list_tables, describe_table, execute_sql, final_answer
• Auto-routing: complex queries use ReAct; simple queries use fast pipeline

Intelligent Schema Retrieval (100+ tables)

BM25 + dense embedding hybrid search with RRF. FK-graph-aware. Token budget control.

Semantic Query Cache

L1 exact → L2 semantic → L4 result TTL. Learning loop from user feedback.

Any LLM, Any Database

Azure OpenAI · OpenAI · Anthropic · Ollama · any compatible endpoint. SQLite · PostgreSQL · MySQL · any SQLAlchemy async URL.

Production Safety

AST-based read-only (sqlglot) · query timeout · fetchmany OOM protection · persistent conversations.

API Reference

Evaluation — SQLAS v2.0

python backend/eval_runner.py --quick                                    # 5 test cases
python backend/eval_runner.py                                            # 28 test cases
python backend/eval_runner.py --provider anthropic:claude-opus-4-7      # test a specific LLM
python backend/eval_runner.py --compare azure,anthropic:claude-opus-4-7,ollama:sqlcoder --quick

45 metrics across 9 dimensions — correctness, agentic quality, cache ROI, safety, faithfulness:

Tech Stack

License

MIT — Pradip Tivhale