NL2SQL API
FastAPI REST service for the NL2SQL engine (nl2sql-engine). At startup it
loads the .env next to nl2sql.yaml (never overriding a variable already
set), builds one engine with NL2SQL.from_config() from the same config as the
CLI (NL2SQL_CONFIG, else ./nl2sql.yaml), calls engine.check(), and serves
it under /api/v1. A datasource marked required: true that cannot connect
stops it from starting; any other one that fails is left out.
Running the API
pip install nl2sql-api
nl2sql-api serve --config nl2sql-demo/nl2sql.yaml --port 8000 # 127.0.0.1, one worker
# or: python -m nl2sql_api serve ..., or: NL2SQL_CONFIG=... uvicorn nl2sql_api.main:app
nl2sql-api serve --demo # the demo project; add --hosted for the public demo (anonymous sessions, limits)
Interactive docs: Swagger UI at /docs, ReDoc at /redoc, the schema at
/openapi.json.
The API's own settings are the api section of nl2sql.yaml; the engine
ignores it:
api:
auth: static # api_keys | proxy | static | none (default none)
static_role: admin # auth: static only
cors_origins: [] # browser origins allowed to call the API
api.auth picks who is asking; the request body never carries the caller. With no
identity the routes answer HTTP 401. Under the default none only a request made
straight to localhost is answered, and serve refuses to bind another host.
Every error is one envelope, {"error": {"code", "message", "fix", "details", "request_id"}},
with the request id also in the X-Request-ID header.
The routes that change datasources, LLMs or the index need a role listed in
policies.admin_roles (default [admin]), else HTTP 403.
The Docker image (the Dockerfile at the repository root, which also builds the web app) reads /etc/nl2sql/nl2sql.yaml:
mount a config folder there, and a volume for storage.path.
Endpoints
POST /api/v1/query- Ask a question as the configured rolePOST /api/v1/query/stream- The same, as Server-Sent Events: each step as it runs, the result manifest, the answer as it is written, then the/queryresponseGET /api/v1/health- Liveness checkGET /api/v1/ready- Readiness from the engine's check, kept 10 seconds:200 readyor503 not_ready; an admin also getsproblems. The API starts even when a required datasource fails; this is where it says soGET /api/v1/meta- The mode, the identity source andrequest_llm(no caller needed)GET /api/v1/about- What the engine isGET /api/v1/datasource-types- The adapters the engine can name, each with its connection schema (admin only)POST /api/v1/datasources/test- Test a connection without registering it; returns the failed stage and the fix (admin only)POST /api/v1/datasources- Register a datasource in the running process (configis onedatasourcesentry);save: truealso writesdatasources/<id>.yaml(admin only)GET /api/v1/datasources,GET /api/v1/datasources/{datasource_id}- The datasources the caller reaches, with status, masked connection and sample questionsDELETE /api/v1/datasources/{datasource_id}- Take a datasource out of the running process (admin only)GET /api/v1/datasources/{datasource_id}/schema,GET /api/v1/datasources/{datasource_id}/diagram- The caller's view of the schema, as JSON or a MermaiderDiagramGET /api/v1/index- Index health (status, entries by type, embedding model, problems)DELETE /api/v1/index- Clear the vector store (admin only)GET /api/v1/index/check- Drift check against the live schemas (admin only)GET /api/v1/index/inspect,POST /api/v1/index/inspect- The retrieval inspectorPOST /api/v1/jobs/index,POST /api/v1/jobs/profile- Start the index or profile job (admin only,202)GET /api/v1/knowledge,GET /api/v1/knowledge/sources,POST /api/v1/knowledge/reload,POST /api/v1/knowledge/choices- What the engine knows; reload (admin) and file a clarification choiceGET /api/v1/proposals,GET /api/v1/proposals/{proposal_id},POST /api/v1/proposals/accept|reject|examples- Review proposed knowledge changes (admin only)PUT /api/v1/settings/llm- Replace the wholellmsection in the running process (admin only; 422 with the config error)PATCH /api/v1/settings/llm- Change only the provider and model of named agents (admin only; every otherllmsetting stays; in memory, this process only)GET /api/v1/llm- Each agent and the model it runs onGET /api/v1/llm/providers- The LLM providers: key present, verified models, the shape a key must haveGET /api/v1/api-keys,POST /api/v1/api-keys,DELETE /api/v1/api-keys/{key_id}- List, create (the token is returned once) and revoke API keys (admin only)GET /api/v1/evals/suites,GET /api/v1/evals/scorers- The configured eval suites and the scorer names (admin only)POST /api/v1/jobs/eval- Run the configured eval suites as a job (admin only,202;422when no suite is configured or named)POST /api/v1/jobs/demo- Add the sample databases and index them, as a job (admin only,202)GET /api/v1/events/catalog- Every event the engine publishes, with its data's JSON Schema
Reference: https://github.com/nadeem4/nl2sql/blob/main/docs/api/rest/index.md.
Metadata
Release files for nl2sql-api 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nl2sql_api-0.10.0.tar.gz | 6.3 MB | Without provenance | Details for nl2sql_api-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nl2sql_api-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for nl2sql_api-0.10.0-py3-none-any.whl |
Total release size: 12.6 MB
Release files / nl2sql_api-0.10.0.tar.gz
| Download URL | nl2sql_api-0.10.0.tar.gz |
|---|---|
| Size | 6.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
08646b57df642e227e48fa70e5339baf6a8470b94ea1f72693ac6239a50bfc71
|
|
BLAKE2b-256 checksum How to use checksums |
d385af57f4fd389ab4b33344ddfae39cf331a6e2065e1ebb922f2419a26032a7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / nl2sql_api-0.10.0-py3-none-any.whl
| Download URL | nl2sql_api-0.10.0-py3-none-any.whl |
|---|---|
| Size | 6.3 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8af1a8f8dd823025bc8f1e8fdafc0f65367d40c834790cc5d5edcf33ae77a63
|
|
BLAKE2b-256 checksum How to use checksums |
39f0f8ea7fb0395529eb91a2e1d7f759c9beb880535b3289fede7bed46c74780
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for nl2sql-api 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.