NLQueries

nlqueries-core

CI PyPI Python License: BSL 1.1

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.

Project links

Data verified by PyPI on Jul 7, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nlqueries from gravatar.com nlqueries

GitHub Statistics

Data verified by PyPI on Jul 7, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Other/Proprietary License (Business Source License 1.1)

Requires

Python <3.14, >=3.11

Provides Extra

bigquery dev docs duckdb mssql mysql onnx openai redshift snowflake wiki

Tags

mcp natural-language nlp query sql

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nlqueries_core-0.2.0.tar.gz (1.3 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

nlqueries_core-0.2.0-py3-none-any.whl (179.7 kB view details)

Uploaded Python 3

File details

Details for the file nlqueries_core-0.2.0.tar.gz.

File metadata

  • Download URL: nlqueries_core-0.2.0.tar.gz
  • Upload date:
  • Size: 1.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for nlqueries_core-0.2.0.tar.gz
Algorithm Hash digest
SHA256 caf46de13ef81d6075ee528aa2dd6f2088a31fd9d419b9fad701ec41e9242e90
MD5 3b238bc667022e39a00096aa440cbcd8
BLAKE2b-256 b3178f23ca03038bc2579eac679b9863e89749866847bea7f41409876af88683

See more details on using hashes here.

Provenance

The following attestation bundles were made for nlqueries_core-0.2.0.tar.gz:

Publisher: release.yml on nlqueries/nlqueries

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file nlqueries_core-0.2.0-py3-none-any.whl.

File metadata

  • Download URL: nlqueries_core-0.2.0-py3-none-any.whl
  • Upload date:
  • Size: 179.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for nlqueries_core-0.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5eb31a1721e7fcfd9373c7174f7ca85e285c8d2ee17bb267e537fa3c823b8548
MD5 0747b17de67b6cd688f0c9862625823e
BLAKE2b-256 79159a9819e3f9e352681d2d4a2eebb8d68b7bf30070ce40dc59e44be6fad8f1

See more details on using hashes here.

Provenance

The following attestation bundles were made for nlqueries_core-0.2.0-py3-none-any.whl:

Publisher: release.yml on nlqueries/nlqueries

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 files

0.1.0

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page