Turn natural language into SQL, execute it, and visualise results.
N2S is an open-source Natural Language to SQL to Insights agent. Built on the Vanna 2.0 agent framework, it extends the original with stronger tool-calling, multi-turn reasoning, a data ingestion pipeline, and a built-in Text2SQL benchmark.
N2S is a derivative project. It retains Vanna's MIT license and all original copyright notices. See NOTICE for attribution.
- Agent + Tool Calling — The agent reasons over schema, generates SQL, executes it, and visualises results through an explicit tool loop.
- Self-Correction — Failed SQL is captured and fed back to the LLM for automatic retry.
- Schema Introspection — The agent inspects database schema before writing queries, reducing hallucination.
- Data Ingestion Pipeline — Scan directories, read CSV/Excel/JSON/Parquet files, infer schema automatically, and load into the target database. Optional LLM-assisted schema enhancement with graceful degradation.
- Multi-Database Support — SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, Oracle, BigQuery, Snowflake, MSSQL, Hive, Presto, and more via SQLAlchemy.
- Multi-LLM Providers — Mock (no API key), OpenAI, Anthropic, Gemini, Ollama, and OpenAI-compatible endpoints (Agnes, Mimo).
- Built-in Benchmark —
python -m n2s.evalruns a reproducible Text2SQL evaluation and compares multiple LLM providers. - One-Command Demo —
python n2s_app.pystarts a FastAPI server with a web UI.
git clone https://github.com/YOUR_USERNAME/n2s.git
cd n2s
pip install -e ".[fastapi]"python n2s_app.py
# Open http://localhost:8000Supported providers: mock (default), agnes, openai, anthropic, ollama, mimo.
# OpenAI
export N2S_LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...
python n2s_app.py
# Anthropic
export N2S_LLM_PROVIDER=anthropic
export ANTHROPIC_API_KEY=sk-ant-...
python n2s_app.py
# Ollama (local)
export N2S_LLM_PROVIDER=ollama
export OLLAMA_MODEL=llama3.1
python n2s_app.pydocker-compose up --build
# Open http://localhost:8000 N2S Architecture
┌──────────────────────────────────────────────────────────────────┐
│ User Interface │
│ (Web Chat / CLI / FastAPI / Flask) │
└────────────────────────────┬─────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ N2S Agent Core │
│ ┌──────────┐ ┌───────────────┐ ┌───────────────────────────┐ │
│ │ Agent │ │ Tool Registry │ │ Workflow Handler │ │
│ │ Loop │──│ (tool-call) │ │ (/help, /status, /mem) │ │
│ └────┬─────┘ └───────┬───────┘ └───────────────────────────┘ │
│ │ │ │
│ │ ┌───────────┼───────────┐ │
│ │ ▼ ▼ ▼ │
│ │ Schema RunSQL Visualize │
│ │ Tool Tool Data Tool │
│ └─────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ LLM Providers │ │ Databases │ │ Vector Memory │
│ (OpenAI, │ │ (SQLite, │ │ (ChromaDB, │
│ Anthropic, │ │ Postgres, │ │ FAISS, │
│ Gemini, │ │ MySQL, │ │ Qdrant, │
│ Ollama...) │ │ DuckDB...) │ │ Pinecone...) │
└──────────────────┘ └──────────────┘ └──────────────────┘
User Question
│
▼
┌─────────────────┐
│ Parse Input │ ← Workflow handler checks for /help, /status, etc.
└────────┬────────┘
│ (not a command)
▼
┌─────────────────┐
│ Build Context │ ← Load conversation history + agent memory
└────────┬────────┘
│
▼
┌─────────────────┐ ┌─────────────────────────┐
│ Call LLM │────▶│ LLM returns tool call? │
└────────┬────────┘ └───────────┬─────────────┘
│ │
│ ┌───────────┴───────────┐
│ │ │
│ Yes ▼ No ▼
│ ┌──────────────┐ ┌──────────────┐
│ │ Execute Tool │ │ Return Final │
│ │ (SQL/Schema/ │ │ Response │
│ │ Visualize) │ └──────────────┘
│ └──────┬───────┘
│ │
│ ▼
│ ┌──────────────┐
│ │ SQL Failed? │
│ └──────┬───────┘
│ │
│ ┌──────┴───────┐
│ │ │
│ Yes▼ No ▼
│ Feed error Append result
│ back to LLM to context
│ │ │
└──────┴──────────────┘
(loop back to Call LLM,
up to max_tool_calls)
Directory / File
│
▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Scanner │────▶│ Reader │────▶│ Inferrer │
│ (classify │ │ (CSV/Excel/ │ │ (auto-detect │
│ file types) │ │ JSON/Parquet)│ │ schema+type)│
└──────────────┘ └──────────────┘ └──────┬───────┘
│
┌─────────────┴─────────────┐
│ │
LLM available? Not available
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ LLM Enhancer│ │ Fallback: │
│ (enrich table│ │ use inferred │
│ & column │ │ schema only │
│ descriptions)│ └──────┬───────┘
└──────┬───────┘ │
└──────────┬──────────────┘
▼
┌──────────────┐
│ Loader │
│ (to_sql into │
│ target DB) │
└──────────────┘
Evaluate N2S on a Text2SQL dataset:
python -m n2s.eval \
--dataset src/n2s/eval/datasets/n2s_sql.yaml \
--providers mock openai anthropicThe report includes:
| Metric | Description |
|---|---|
| Trajectory | Did the agent call the expected tools? |
| Output | Does the final answer contain expected keywords? |
| SQL Similarity | Does the generated SQL match the reference? |
| SQL Execution | Does the SQL execute and return the expected result? |
# Run all unit tests (excludes integration tests requiring API keys)
pytest tests/ -m "not integration and not anthropic and not openai and not azureopenai and not gemini and not ollama and not postgres and not mysql and not slow"n2s/
├── src/n2s/
│ ├── core/ # Agent framework (agent, llm, tools, workflow, components)
│ ├── capabilities/ # Capability interfaces (sql_runner, agent_memory, file_system)
│ ├── components/ # UI components (rich + simple)
│ ├── integrations/ # DB/LLM/vector store integrations
│ │ ├── anthropic/ # Anthropic Claude
│ │ ├── openai/ # OpenAI GPT
│ │ ├── google/ # Google Gemini
│ │ ├── ollama/ # Local Ollama
│ │ ├── sqlite/ # SQLite runner
│ │ ├── postgres/ # PostgreSQL runner
│ │ ├── chromadb/ # ChromaDB vector memory
│ │ └── ... # 20+ more integrations
│ ├── ingest/ # Data ingestion pipeline
│ ├── demo/ # Demo server, agent, database manager
│ ├── eval/ # Text2SQL benchmark evaluation
│ ├── examples/ # Example scripts
│ ├── servers/ # FastAPI / Flask / CLI servers
│ └── tools/ # Built-in tools (run_sql, visualize_data, file_system)
├── frontends/webcomponent/# TypeScript web components (Vite + Storybook)
├── tests/ # Pytest test suite
├── n2s_app.py # Demo entry point
├── pyproject.toml # Project metadata + dependencies
├── docker-compose.yml # Docker deployment
└── .env.example # Environment variable template
| Provider | Type | Requires API Key | Description |
|---|---|---|---|
mock |
Built-in | No | Deterministic mock response, for testing |
openai |
Cloud | Yes | OpenAI GPT models |
anthropic |
Cloud | Yes | Anthropic Claude models |
gemini |
Cloud | Yes | Google Gemini models |
ollama |
Local | No | Local Ollama server |
SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, Oracle, BigQuery, Snowflake, MS SQL Server, Hive, Presto (via SQLAlchemy).
N2S is built on Vanna by Vanna.AI and contributors, used under the MIT License.