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_CONFIG=nl2sql-demo/nl2sql.yaml nl2sql-api --host 127.0.0.1 --port 8000 [--reload]
# or: python -m nl2sql_api.server ..., or: uvicorn nl2sql_api.main:app
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:
role_header: X-NL2SQL-Role # a header a trusted proxy sets on every request
role: null # or one static role for every request
trust_body_role: false # local testing only: the body's user_context
cors_origins: [] # browser origins allowed to call the API
The API does not authenticate callers and never takes the RBAC role from the
request body unless api.trust_body_role is on (it logs a warning). With no
role source, /api/v1/query and /api/v1/query/stream answer HTTP 401.
The routes that change datasources, LLMs or the index need a role listed in
policies.admin_roles (default [admin]), else HTTP 403. With no role setting
at all they answer loopback clients only.
The Docker image (packages/api/Dockerfile) 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 check (does not yet check dependencies)GET /api/v1/datasource-types- The adapters the engine can name, each with its connection schema (admin only)POST /api/v1/datasource/test- Test a connection without registering it; returns the failed stage and the fix (admin only)POST /api/v1/datasource- Register a datasource in the running process (configis onedatasourcesentry:id,type,connection, ...);save: truealso writesdatasources/<id>.yamlwith secrets as references; a body that does not validate is a 422 listing each problem by pathGET /api/v1/datasource- List the datasources, with their status and masked connectionsGET /api/v1/datasource/{datasource_id}- One datasourceDELETE /api/v1/datasource/{datasource_id}- Take a datasource out of the running processPUT /api/v1/settings/llm- Replace the wholellmsection in the running process (admin only; 422 with the config error)GET /api/v1/llm- Each agent and the model it runs onGET /api/v1/llm/{agent}- One agent's modelPOST /api/v1/index/{datasource_id}- Index one datasource's schemaPOST /api/v1/index-all- Index every configured datasourceDELETE /api/v1/index- Clear the vector storeGET /api/v1/index/status- Index health (status, entries by type, embedding model, problems)
Reference: https://github.com/nadeem4/nl2sql/blob/main/docs/api/rest/index.md.
Metadata
Release files for nl2sql-api 0.9.1
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.9.1.tar.gz | 37.8 kB | Without provenance | Details for nl2sql_api-0.9.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nl2sql_api-0.9.1-py3-none-any.whl | Python 3 | none | any | Details for nl2sql_api-0.9.1-py3-none-any.whl |
Total release size: 62.4 kB
Release files / nl2sql_api-0.9.1.tar.gz
| Download URL | nl2sql_api-0.9.1.tar.gz |
|---|---|
| Size | 37.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1778aba05140325283a7a27f4b0c99bc34a7eb12fce854ad2f741c0ddbd70d6b
|
|
BLAKE2b-256 checksum How to use checksums |
af949084d5292d0f578a1b9284dcaa777e4498e6bb396d66aeab879c7508cabc
|
| 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.9.1-py3-none-any.whl
| Download URL | nl2sql_api-0.9.1-py3-none-any.whl |
|---|---|
| Size | 24.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2086ee7022e915a916689b9a8eb116cd6ff71efb20d544f16b45581035c08338
|
|
BLAKE2b-256 checksum How to use checksums |
dc7e4f5778f508bdcaefbd1ae316febeb13cb0a4924cb541dd2c0b2e3518d3b2
|
| 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.9.1
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.