nlqueries-core

CI PyPI Python License: BSL 1.1 Visitors

NLQueries Core turns plain-English questions into validated SQL, builds a self-updating YAML knowledge base from your schema and query history, and exposes everything as an MCP server your AI assistant can call directly. It also answers questions from your documents (PDF, Word, Excel, Notion, Confluence) and can blend both in a single hybrid answer.

Website & docs: nlqueries.com

---

Features

Capability	Description
Database connectors	PostgreSQL, MySQL, Snowflake, BigQuery, Redshift, SQL Server / Azure SQL, DuckDB
Document connectors	PDF, Word, Excel, Notion, Confluence — ask questions over ingested documents with citations
Query pipeline	Filter, cluster, and parameterize query history into reusable QueryCapsule templates
Knowledge base	Auto-generated YAML schema + capsule file, with coverage reporting via kb-stats
Multi-agent orchestration	Routes each question to a SQL agent, document agent, or both in parallel (hybrid)
Semantic cache	Returns previously-answered similar questions in under 50 ms, no LLM or DB round-trip
Embedding daemon	Keeps the embedding model resident in memory — ~10 ms per call instead of ~9 s
LLM client	Anthropic, OpenAI, or any LiteLLM-supported provider
MCP server	Query execution and schema/knowledge lookup exposed as MCP tools for Claude, Cursor, etc.
CLI	nlqueries (or the shorter nlq alias) — connect, build, query, and inspect from your terminal

See docs/architecture.md for how these pieces fit together.

---

Quickstart

Prerequisite: Python 3.11+.

Option A — Docker (recommended)

Pulls the published nlqueries/core image from Docker Hub — no clone required, just the compose file:

curl -O https://raw.githubusercontent.com/nlqueries/nlqueries/main/docker-compose.yml

Create a .env file next to it with at least one LLM key:

ANTHROPIC_API_KEY=sk-ant-...
# or OPENAI_API_KEY=sk-...

Then start the stack:

docker compose up

This pulls nlqueries/core:latest and starts it alongside Qdrant (:6333), with the MCP server on :8080. Run CLI commands against the running stack from a second terminal:

docker exec -it nlqueries-core nlqueries health

Option B — pip install

pip install nlqueries-core
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
nlqueries health

Optional extras for specific connectors:

pip install "nlqueries-core[mysql]"     # MySQL
pip install "nlqueries-core[redshift]"  # Amazon Redshift
pip install "nlqueries-core[mssql]"     # SQL Server / Azure SQL
pip install "nlqueries-core[duckdb]"    # DuckDB
pip install "nlqueries-core[docs]"      # PDF / Word / Excel ingestion
pip install "nlqueries-core[wiki]"      # Notion / Confluence sync

Option C — Clone and install from source

No Docker required — for contributing, or to run against unreleased changes:

git clone https://github.com/nlqueries/nlqueries.git
cd nlqueries
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
export ANTHROPIC_API_KEY=sk-ant-...   # or OPENAI_API_KEY
nlqueries health

See CONTRIBUTING.md for linting and test commands.

First query

nlqueries connect postgres --host localhost --database mydb --user alice --password secret --alias dev
nlqueries process-history dev --days 30 --annotate
nlqueries export-kb dev
nlqueries query dev "How many orders shipped last month?"

Full walkthrough: docs/getting-started.md.

---

Documentation

Doc	Covers
docs/getting-started.md	Step-by-step setup and your first query
docs/cli-reference.md	Every command and flag
docs/connectors.md	Database and document connector setup, per-connector notes and caveats
docs/configuration.md	Environment variables
docs/troubleshooting.md	Common warnings and errors explained
docs/qdrant-setup.md	Setting up Qdrant (required for embeddings, semantic cache, document search)
docs/architecture.md	Module layout and request flow

---

Contributing

See CONTRIBUTING.md. All contributors must sign the CLA before a PR can be merged — see CONTRIBUTOR_LICENSE_AGREEMENT.md.

---

License

Business Source License 1.1 — each release converts to Apache 2.0 four years after its release date.