Metadata-Version: 2.4
Name: nexussql
Version: 1.0.2
Summary: NexusSQL — Agentic SQL Agent. Natural language to SQL with ReAct reasoning, semantic cache, and a bundled React UI.
Author-email: Pradip Tivhale <pradiptivhale@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/thepradip/NexusSQL
Project-URL: Documentation, https://github.com/thepradip/NexusSQL#readme
Project-URL: Repository, https://github.com/thepradip/NexusSQL
Keywords: sql,agent,llm,text-to-sql,natural-language,fastapi,react,agentic,mlflow,semantic-cache,schema-retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Framework :: FastAPI
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: uvicorn[standard]>=0.34.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: openai>=1.61.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: sqlglot>=25.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: mlflow>=3.1.0
Requires-Dist: greenlet>=3.1.0
Requires-Dist: sqlas>=2.8.0
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == "mysql"
Provides-Extra: vector
Requires-Dist: chromadb>=1.0.0; extra == "vector"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.49.0; extra == "anthropic"
Provides-Extra: all
Requires-Dist: asyncpg>=0.29.0; extra == "all"
Requires-Dist: aiomysql>=0.2.0; extra == "all"
Requires-Dist: chromadb>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.49.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/sqlas_logo.png" alt="NexusSQL Logo" width="200"/>
</p>

<h1 align="center">NexusSQL</h1>

<p align="center">
  <strong>Agentic SQL Agent — Natural Language to SQL with Multi-step Reasoning</strong>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white"/>
  <img src="https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi&logoColor=white"/>
  <img src="https://img.shields.io/badge/React-Frontend-61DAFB?style=for-the-badge&logo=react&logoColor=black"/>
  <img src="https://img.shields.io/badge/SQLAS-v2.0-orange?style=for-the-badge"/>
  <img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge"/>
</p>

<p align="center">
  <a href="https://github.com/thepradip/NexusSQL">GitHub</a> ·
  <a href="https://github.com/thepradip/SQLAS">SQLAS Eval Framework</a> ·
  <a href="https://zenodo.org/records/20180541">📄 Paper</a>
</p>

<p align="center">
  <a href="https://zenodo.org/records/20180541">
    <img src="https://zenodo.org/badge/DOI/10.5281/zenodo.20180541.svg" alt="DOI"/>
  </a>
</p>

## 📄 Paper

**NexusSQL: Production SQL Agent for 100+ Table Databases with SQLAS Evaluation**
**Author:** [thepradip](https://github.com/thepradip)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20180541.svg)](https://zenodo.org/records/20180541)
> Published May 14, 2026 · [View Paper](https://zenodo.org/records/20180541) · [View PDF](nexussql-package/paper/NexusSQL_SQLAS_Draft_V3.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](https://github.com/thepradip)



---

## Quick Start

```bash
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

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | DB status, table count, MLflow experiment |
| GET | `/schema` | Full auto-discovered schema context |
| POST | `/query` | NL → SQL → Execute → Narrate |
| POST | `/feedback` | Thumbs up/down — teaches the few-shot cache |
| POST | `/feedback/detailed` | Multi-dimension rating |
| POST | `/export/csv` | Download results as CSV |
| GET | `/cache/stats` | Hit rates, tokens saved, cost savings |
| DELETE | `/cache/results` | Flush result cache after data updates |
| POST | `/evaluate` | Run SQLAS evaluation suite |
| DELETE | `/conversations/{id}` | Clear conversation history |

---

## Evaluation — SQLAS v2.0

```bash
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:

| Dimension | Weight |
|-----------|--------|
| Execution Accuracy | 25% |
| Semantic Correctness | 10% |
| **Agentic Quality** (planning, grounding, steps) | **10%** |
| Context Quality (RAGAS-mapped) | 8% |
| Cost Efficiency (VES, scan, SQL quality) | 10% |
| Task Success (faithfulness, relevance) | 8% |
| Result + Visualization | 7% |
| Guardrails (read-only, injection, PII) | 15% |
| Execution Quality | 7% |

---

## Tech Stack

| Layer | Technology |
|-------|-----------|
| Agent | Custom ReAct loop — tool calling, MLflow tracing |
| Schema retrieval | BM25 + dense embeddings + Reciprocal Rank Fusion |
| Semantic cache | SQLite-backed L1/L2/L4, verified few-shot learning |
| Evaluation | [SQLAS v2.0](https://pypi.org/project/sqlas/) — 45 metrics, 9 categories |
| LLM | Azure OpenAI · OpenAI · Anthropic · Ollama · any compatible |
| Backend | FastAPI + SQLAlchemy async |
| Frontend | React 18 + Vite + Tailwind CSS |
| Observability | MLflow — traces, spans, feedback |
| Database | SQLite · PostgreSQL · MySQL (any SQLAlchemy async URL) |

---

## License

MIT — [Pradip Tivhale](https://github.com/thepradip)
