nl2sql-api 0.1.2__tar.gz → 0.2.1__tar.gz

nl2sql_api-0.2.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: nl2sql-api
+Version: 0.2.1
+Summary: FastAPI REST service for the nl2sql engine: ask a database questions in English over HTTP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nadeem4/nl2sql
+Project-URL: Documentation, https://nadeem4.github.io/nl2sql/
+Project-URL: Source, https://github.com/nadeem4/nl2sql
+Project-URL: Issues, https://github.com/nadeem4/nl2sql/issues
+Project-URL: Demo, https://nadeem4nk-nl2sql-demo.hf.space
+Keywords: nl2sql,text-to-sql,natural language,sql,llm,fastapi,rest api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: nl2sql-engine~=0.1
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: python-dotenv>=1.0.0
+
+# NL2SQL API
+
+FastAPI REST service for the NL2SQL engine (`nl2sql-engine`). It builds one
+`NL2SQL` engine at startup, from the same env file and configs as the CLI, and
+serves it under `/api/v1`.
+
+## Running the API
+
+```bash
+pip install nl2sql-api
+ENV=demo NL2SQL_API_ROLE=admin nl2sql-api --host 127.0.0.1 --port 8000 [--reload]
+# or: python -m nl2sql_api.server ..., or: uvicorn nl2sql_api.main:app
+```
+
+Start it from the folder holding the env file and configs (the demo's use
+relative paths). Interactive docs: Swagger UI at `/docs`, ReDoc at `/redoc`,
+the schema at `/openapi.json`.
+
+The API does not authenticate callers and never takes the RBAC role from the
+request body. Set one of: `NL2SQL_API_ROLE_HEADER` (a header a trusted proxy
+sets), `NL2SQL_API_ROLE` (one static role) or, for local testing only,
+`NL2SQL_API_TRUST_BODY_ROLE=true` (the body's `user_context`; logs a warning).
+With none, `/api/v1/query` answers HTTP 401.
+
+## Endpoints
+
+- `POST /api/v1/query` - Ask a question as the configured role
+- `GET /api/v1/health` - Liveness check
+- `GET /api/v1/ready` - Readiness check (does not yet check dependencies)
+- `POST /api/v1/datasource` - Register a datasource in the running process
+- `GET /api/v1/datasource` - List registered datasource ids
+- `GET /api/v1/datasource/{datasource_id}` - Check a datasource is registered
+- `DELETE /api/v1/datasource/{datasource_id}` - Not supported yet (answers `success: false`)
+- `POST /api/v1/llm` - Configure an LLM in the running process
+- `GET /api/v1/llm` - List configured LLMs
+- `GET /api/v1/llm/{llm_name}` - Get one configured LLM
+- `POST /api/v1/index/{datasource_id}` - Index one datasource's schema
+- `POST /api/v1/index-all` - Index every registered datasource
+- `DELETE /api/v1/index` - Clear the vector store
+- `GET /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>.

nl2sql_api-0.2.1/README.md

@@ -0,0 +1,42 @@
+# NL2SQL API
+
+FastAPI REST service for the NL2SQL engine (`nl2sql-engine`). It builds one
+`NL2SQL` engine at startup, from the same env file and configs as the CLI, and
+serves it under `/api/v1`.
+
+## Running the API
+
+```bash
+pip install nl2sql-api
+ENV=demo NL2SQL_API_ROLE=admin nl2sql-api --host 127.0.0.1 --port 8000 [--reload]
+# or: python -m nl2sql_api.server ..., or: uvicorn nl2sql_api.main:app
+```
+
+Start it from the folder holding the env file and configs (the demo's use
+relative paths). Interactive docs: Swagger UI at `/docs`, ReDoc at `/redoc`,
+the schema at `/openapi.json`.
+
+The API does not authenticate callers and never takes the RBAC role from the
+request body. Set one of: `NL2SQL_API_ROLE_HEADER` (a header a trusted proxy
+sets), `NL2SQL_API_ROLE` (one static role) or, for local testing only,
+`NL2SQL_API_TRUST_BODY_ROLE=true` (the body's `user_context`; logs a warning).
+With none, `/api/v1/query` answers HTTP 401.
+
+## Endpoints
+
+- `POST /api/v1/query` - Ask a question as the configured role
+- `GET /api/v1/health` - Liveness check
+- `GET /api/v1/ready` - Readiness check (does not yet check dependencies)
+- `POST /api/v1/datasource` - Register a datasource in the running process
+- `GET /api/v1/datasource` - List registered datasource ids
+- `GET /api/v1/datasource/{datasource_id}` - Check a datasource is registered
+- `DELETE /api/v1/datasource/{datasource_id}` - Not supported yet (answers `success: false`)
+- `POST /api/v1/llm` - Configure an LLM in the running process
+- `GET /api/v1/llm` - List configured LLMs
+- `GET /api/v1/llm/{llm_name}` - Get one configured LLM
+- `POST /api/v1/index/{datasource_id}` - Index one datasource's schema
+- `POST /api/v1/index-all` - Index every registered datasource
+- `DELETE /api/v1/index` - Clear the vector store
+- `GET /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>.

nl2sql_api-0.2.1/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nl2sql-api"
+version = "0.2.1" # x-release-please-version
+description = "FastAPI REST service for the nl2sql engine: ask a database questions in English over HTTP"
+readme = "README.md"
+license = "MIT"
+keywords = ["nl2sql", "text-to-sql", "natural language", "sql", "llm", "fastapi", "rest api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "nl2sql-engine~=0.1",
+    "fastapi>=0.100.0",
+    "uvicorn>=0.20.0",
+    "pydantic>=2.0",
+    "python-multipart>=0.0.6",
+    "python-dotenv>=1.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/nadeem4/nl2sql"
+Documentation = "https://nadeem4.github.io/nl2sql/"
+Source = "https://github.com/nadeem4/nl2sql"
+Issues = "https://github.com/nadeem4/nl2sql/issues"
+Demo = "https://nadeem4nk-nl2sql-demo.hf.space"
+
+[project.scripts]
+nl2sql-api = "nl2sql_api.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nl2sql_api*"]

nl2sql_api-0.2.1/src/nl2sql_api/auth.py

@@ -0,0 +1,92 @@
+"""Where the caller's RBAC role comes from.
+
+The engine enforces RBAC; this module only decides which role a request carries.
+It is a seam, not an auth provider: put a proxy that authenticates the caller in
+front of the API and have it set the role header, or pin one static role.
+
+Sources, first match wins:
+
+1. ``NL2SQL_API_ROLE_HEADER``: the name of a header a trusted proxy sets, for
+   example ``X-NL2SQL-Role``. Comma-separated values are several roles. Only
+   configure it when the proxy overwrites that header on every request, or any
+   client can pick its own role.
+2. ``NL2SQL_API_ROLE``: one static role for every request.
+3. ``user_context`` in the request body, only with the dev flag
+   ``NL2SQL_API_TRUST_BODY_ROLE=true``. For local testing: it lets any client
+   choose any role.
+
+No role is a 401. The settings are read on each request.
+"""
+
+import logging
+import os
+from typing import Any, List
+
+from fastapi import HTTPException, Request, status
+from pydantic import ValidationError
+
+from nl2sql import UserContext
+
+logger = logging.getLogger(__name__)
+
+ROLE_HEADER_ENV = "NL2SQL_API_ROLE_HEADER"
+STATIC_ROLE_ENV = "NL2SQL_API_ROLE"
+TRUST_BODY_ROLE_ENV = "NL2SQL_API_TRUST_BODY_ROLE"
+
+
+def _body_role_trusted() -> bool:
+    return os.getenv(TRUST_BODY_ROLE_ENV, "").strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _roles(value: str) -> List[str]:
+    return [role.strip() for role in value.split(",") if role.strip()]
+
+
+def warn_if_body_role_trusted() -> None:
+    """Log a warning when the dev flag lets clients choose their own role."""
+    if _body_role_trusted():
+        logger.warning(
+            "%s is on: the RBAC role is taken from the request body, so any client "
+            "can choose any role. Use it for local testing only.",
+            TRUST_BODY_ROLE_ENV,
+        )
+
+
+async def _body_user_context(request: Request) -> Any:
+    try:
+        body = await request.json()
+    except Exception:
+        return None
+    return body.get("user_context") if isinstance(body, dict) else None
+
+
+async def get_user_context(request: Request) -> UserContext:
+    """Return the caller's ``UserContext``, or raise 401 when no role is configured."""
+    header = os.getenv(ROLE_HEADER_ENV, "").strip()
+    if header:
+        roles = _roles(request.headers.get(header, ""))
+        if roles:
+            return UserContext(roles=roles)
+
+    static_role = os.getenv(STATIC_ROLE_ENV, "").strip()
+    if static_role:
+        return UserContext(roles=_roles(static_role))
+
+    if _body_role_trusted():
+        payload = await _body_user_context(request)
+        if isinstance(payload, dict):
+            try:
+                user_context = UserContext(**payload)
+            except ValidationError:
+                user_context = None
+            if user_context and user_context.roles:
+                return user_context
+
+    raise HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail=(
+            "No role for this request. Configure a trusted proxy header "
+            f"({ROLE_HEADER_ENV}) or a static role ({STATIC_ROLE_ENV}). The body's "
+            f"user_context is ignored unless {TRUST_BODY_ROLE_ENV}=true (local testing only)."
+        ),
+    )

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/main.py

@@ -6,20 +6,22 @@ from importlib.metadata import PackageNotFoundError, version
 
 from .routes import query, health, datasource, llm, indexing
 from fastapi.middleware.cors import CORSMiddleware
-from nl2sql import NL2SQL
-from nl2sql.common.logger import configure_logging
-from nl2sql.common.settings import settings
+from nl2sql import NL2SQL, configure_logging
+from .auth import warn_if_body_role_trusted
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     # The library no longer configures logging on import, so the application
-    # entry point owns it - before anything that logs is constructed.
-    configure_logging(
-        level="INFO",
-        json_format=(settings.observability_exporter == "otlp"),
-    )
-    app.state.engine = NL2SQL()
+    # entry point owns it - before anything that logs is constructed. The
+    # exporter is read through the facade once the engine has loaded settings;
+    # an OTLP deployment then switches to JSON logs.
+    configure_logging(level="INFO")
+    engine = NL2SQL()
+    if engine.get_setting("observability_exporter") == "otlp":
+        configure_logging(level="INFO", json_format=True)
+    warn_if_body_role_trusted()
+    app.state.engine = engine
     yield
 
 

nl2sql_api-0.2.1/src/nl2sql_api/models/query.py

@@ -0,0 +1,34 @@
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from nl2sql import QueryResult, SubQueryResult
+
+
+class QueryRequest(BaseModel):
+    natural_language: str
+    datasource_id: Optional[str] = None
+    execute: bool = True
+    user_context: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description=(
+            "Ignored unless NL2SQL_API_TRUST_BODY_ROLE=true (local testing only); "
+            "the role otherwise comes from the API's auth settings."
+        ),
+    )
+
+
+class SubQueryResponse(SubQueryResult):
+    """One decomposed sub-query: its plan, validation checks, SQL and row sample."""
+
+
+class QueryResponse(QueryResult):
+    """The engine's ``QueryResult``, served as is.
+
+    It derives from ``nl2sql.QueryResult``, so the HTTP response cannot drift
+    from what the engine returns. ``sub_queries[].rows`` carries a capped
+    sample only; the full result set lives in artifact storage, addressable
+    through ``artifact_refs``. ``trace_path`` is where the run's trace was
+    written on the server, or None.
+    """
+    sub_queries: List[SubQueryResponse] = Field(default_factory=list)

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/routes/datasource.py

@@ -5,37 +5,43 @@ from nl2sql_api.models.datasource import DatasourceRequest, DatasourceResponse
 from nl2sql_api.dependencies import get_datasource_service
 from nl2sql_api.services import DatasourceService
 
-router = APIRouter()
+router = APIRouter(tags=["datasources"])
 
 DatasourceSvc = Annotated[DatasourceService, Depends(get_datasource_service)]
 
 
-@router.post("/datasource", response_model=DatasourceResponse)
+@router.post("/datasource", response_model=DatasourceResponse, summary="Add a datasource")
 def add_datasource(
     payload: DatasourceRequest,
     service: DatasourceSvc,
 ):
+    """Register a datasource in this process from `config`, shaped like one entry of
+    `configs/datasources.yaml`. It is not written to the config file and not indexed:
+    call `POST /api/v1/index/{datasource_id}` next.
+    """
     try:
         return service.add_datasource(payload)
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.get("/datasource", response_model=Dict[str, Any])
+@router.get("/datasource", response_model=Dict[str, Any], summary="List datasources")
 def list_datasources(
     service: DatasourceSvc,
 ):
+    """The ids of the registered datasources, as `{"datasources": [...]}`."""
     try:
         return {"datasources": service.list_datasources()}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.get("/datasource/{datasource_id}", response_model=Dict[str, Any])
+@router.get("/datasource/{datasource_id}", response_model=Dict[str, Any], summary="Check a datasource exists")
 def get_datasource(
     datasource_id: str,
     service: DatasourceSvc,
 ):
+    """`{"datasource_id": ..., "exists": true}`, or 404 when it is not registered. No other details yet."""
     try:
         return service.get_datasource(datasource_id)
     except ValueError as e:
@@ -44,11 +50,12 @@ def get_datasource(
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.delete("/datasource/{datasource_id}", response_model=Dict[str, Any])
+@router.delete("/datasource/{datasource_id}", response_model=Dict[str, Any], summary="Remove a datasource (not supported)")
 def remove_datasource(
     datasource_id: str,
     service: DatasourceSvc,
 ):
+    """Not supported by the engine yet: answers `success: false` (404 for an unknown id)."""
     try:
         return service.remove_datasource(datasource_id)
     except ValueError as e:

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/routes/health.py

@@ -4,19 +4,21 @@ from nl2sql_api.models.response import SuccessResponse
 from nl2sql_api.dependencies import get_health_service
 from nl2sql_api.services import HealthService
 
-router = APIRouter()
+router = APIRouter(tags=["health"])
 
 HealthSvc = Annotated[HealthService, Depends(get_health_service)]
 
-@router.get("/health", response_model=SuccessResponse)
+@router.get("/health", response_model=SuccessResponse, summary="Liveness check")
 async def health_check(
     service: HealthSvc
 ):
+    """Returns `success: true` while the process is serving. Checks nothing else."""
     return service.health_check()
 
 
-@router.get("/ready", response_model=SuccessResponse)
+@router.get("/ready", response_model=SuccessResponse, summary="Readiness check")
 async def readiness_check(
     service: HealthSvc,
 ):
+    """Returns `success: true`. It does not yet check datasources, the LLM or the index."""
     return service.readiness_check()

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/routes/indexing.py

@@ -3,15 +3,16 @@ from typing import Dict, Any, Annotated
 
 from nl2sql_api.dependencies import get_indexing_service
 from nl2sql_api.services import IndexingService
-router = APIRouter()
+router = APIRouter(tags=["indexing"])
 
 IndexingSvc = Annotated[IndexingService, Depends(get_indexing_service)]
 
-@router.post("/index/{datasource_id}", response_model=Dict[str, Any])
+@router.post("/index/{datasource_id}", response_model=Dict[str, Any], summary="Index one datasource")
 def index_datasource(
     datasource_id: str,
     service: IndexingSvc
 ):
+    """Index one datasource's schema into the vector store; returns the indexing stats."""
     try:
         result = service.index_datasource(datasource_id)
 
@@ -28,10 +29,11 @@ def index_datasource(
         )
 
 
-@router.post("/index-all", response_model=Dict[str, Any])
+@router.post("/index-all", response_model=Dict[str, Any], summary="Index every datasource")
 def index_all_datasources(
     service: IndexingSvc
 ):
+    """Index every registered datasource; returns the stats per datasource."""
     try:
         results = service.index_all_datasources()
 
@@ -47,10 +49,11 @@ def index_all_datasources(
         )
 
 
-@router.delete("/index", response_model=Dict[str, Any])
+@router.delete("/index", response_model=Dict[str, Any], summary="Clear the index")
 def clear_index(
     service: IndexingSvc
 ):
+    """Remove every entry from the vector store. Questions need a re-index before they can be answered."""
     try:
         return service.clear_index()
     except Exception as e:
@@ -60,10 +63,13 @@ def clear_index(
         )
 
 
-@router.get("/index/status", response_model=Dict[str, Any])
+@router.get("/index/status", response_model=Dict[str, Any], summary="Index status")
 def get_index_status(
     service: IndexingSvc
 ):
+    """The vector index's health: `status` (`ok`, `empty`, `stale` or `missing`), entry counts by
+    type, when it was built, the embedding model, one entry per registered datasource and any
+    problems found. Read from the live index; the same report the playground shows."""
     try:
         return service.get_index_status()
     except Exception as e:

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/routes/llm.py

@@ -5,36 +5,41 @@ from nl2sql_api.models.llm import LLMRequest, LLMResponse
 from nl2sql_api.dependencies import get_llm_service
 from nl2sql_api.services import LLMService
 
-router = APIRouter()
+router = APIRouter(tags=["llm"])
 
 LLMSvc = Annotated[LLMService, Depends(get_llm_service)]
 
-@router.post("/llm", response_model=LLMResponse)
+@router.post("/llm", response_model=LLMResponse, summary="Configure an LLM")
 def configure_llm(
     payload: LLMRequest,
     service: LLMSvc,
 ):
+    """Register an LLM in this process from `config` (`name` defaults to `default`).
+    It is not written to `configs/llm.yaml`.
+    """
     try:
         return service.configure_llm(payload)
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.get("/llm", response_model=Dict[str, Any])
+@router.get("/llm", response_model=Dict[str, Any], summary="List LLMs")
 def list_llms(
     service: LLMSvc,
 ):
+    """The configured LLMs, as `{"llms": ...}`."""
     try:
         return {"llms": service.list_llms()}
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.get("/llm/{llm_name}", response_model=Dict[str, Any])
+@router.get("/llm/{llm_name}", response_model=Dict[str, Any], summary="Get an LLM")
 def get_llm(
     llm_name: str,
     service: LLMSvc,
 ):
+    """One configured LLM by name."""
     try:
         return service.get_llm(llm_name)
     except Exception as e:

nl2sql_api-0.2.1/src/nl2sql_api/routes/query.py

@@ -0,0 +1,48 @@
+import logging
+
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Annotated
+from nl2sql import UserContext
+from nl2sql_api import auth
+from nl2sql_api.models.query import QueryRequest, QueryResponse
+from nl2sql_api.dependencies import get_query_service
+from nl2sql_api.services import QueryService
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["query"])
+
+QuerySvc = Annotated[QueryService, Depends(get_query_service)]
+Caller = Annotated[UserContext, Depends(auth.get_user_context)]
+
+
+# Synchronous on purpose: the pipeline performs blocking LLM and database calls,
+# so Starlette runs this handler in its threadpool instead of on the event loop.
+@router.post(
+    "/query",
+    response_model=QueryResponse,
+    summary="Ask a question",
+    responses={401: {"description": "No role for this request (see the auth settings)."}},
+)
+def execute_query(
+    payload: QueryRequest,
+    service: QuerySvc,
+    user_context: Caller,
+):
+    """Run a natural-language question through the pipeline.
+
+    Returns, per sub-query, the plan, the validation checks, the SQL and a capped row
+    sample, plus the written answer, errors, timings and token usage. A pipeline
+    failure (a refusal included) comes back with status 200 and `status: "error"`.
+    `execute: false` plans and validates without running SQL. The RBAC role comes
+    from a trusted proxy header (`NL2SQL_API_ROLE_HEADER`) or a static role
+    (`NL2SQL_API_ROLE`); the body's `user_context` counts only with the dev flag
+    `NL2SQL_API_TRUST_BODY_ROLE=true`. No role is a 401.
+    """
+    try:
+        return service.execute_query(payload, user_context)
+    except Exception:
+        # Pipeline failures are reported in QueryResponse.errors with a 200; reaching
+        # here means something genuinely unexpected broke.
+        logger.exception("Unexpected failure while executing query")
+        raise HTTPException(status_code=500, detail="Failed to execute query.")

{nl2sql_api-0.1.2 → nl2sql_api-0.2.1}/src/nl2sql_api/services/indexing.py

@@ -20,11 +20,5 @@ class IndexingService:
         return {"success": True, "message": "Index cleared successfully"}
 
     def get_index_status(self) -> Dict[str, Any]:
-        """Get the status of the index."""
-        # This would typically return information about the vector store
-        # For now, we'll return a placeholder
-        return {
-            "status": "operational",
-            "indexed_datasources": self.engine.list_datasources(),
-            "total_indexes": len(self.engine.list_datasources())  # Placeholder
-        }
+        """The vector index's health, as ``NL2SQL.index_health`` reports it."""
+        return self.engine.index_health()

nl2sql_api-0.2.1/src/nl2sql_api/services/query.py

@@ -0,0 +1,17 @@
+from nl2sql import NL2SQL, UserContext
+from nl2sql_api.models.query import QueryRequest, QueryResponse
+
+
+class QueryService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def execute_query(self, request: QueryRequest, user_context: UserContext) -> QueryResponse:
+        """Run the question as ``user_context``, which the auth dependency supplies."""
+        result = self.engine.run_query(
+            request.natural_language,
+            datasource_id=request.datasource_id,
+            execute=request.execute,
+            user_context=user_context,
+        )
+        return QueryResponse.model_validate(result.model_dump())

nl2sql_api-0.2.1/src/nl2sql_api.egg-info/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: nl2sql-api
+Version: 0.2.1
+Summary: FastAPI REST service for the nl2sql engine: ask a database questions in English over HTTP
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/nadeem4/nl2sql
+Project-URL: Documentation, https://nadeem4.github.io/nl2sql/
+Project-URL: Source, https://github.com/nadeem4/nl2sql
+Project-URL: Issues, https://github.com/nadeem4/nl2sql/issues
+Project-URL: Demo, https://nadeem4nk-nl2sql-demo.hf.space
+Keywords: nl2sql,text-to-sql,natural language,sql,llm,fastapi,rest api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: nl2sql-engine~=0.1
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: python-dotenv>=1.0.0
+
+# NL2SQL API
+
+FastAPI REST service for the NL2SQL engine (`nl2sql-engine`). It builds one
+`NL2SQL` engine at startup, from the same env file and configs as the CLI, and
+serves it under `/api/v1`.
+
+## Running the API
+
+```bash
+pip install nl2sql-api
+ENV=demo NL2SQL_API_ROLE=admin nl2sql-api --host 127.0.0.1 --port 8000 [--reload]
+# or: python -m nl2sql_api.server ..., or: uvicorn nl2sql_api.main:app
+```
+
+Start it from the folder holding the env file and configs (the demo's use
+relative paths). Interactive docs: Swagger UI at `/docs`, ReDoc at `/redoc`,
+the schema at `/openapi.json`.
+
+The API does not authenticate callers and never takes the RBAC role from the
+request body. Set one of: `NL2SQL_API_ROLE_HEADER` (a header a trusted proxy
+sets), `NL2SQL_API_ROLE` (one static role) or, for local testing only,
+`NL2SQL_API_TRUST_BODY_ROLE=true` (the body's `user_context`; logs a warning).
+With none, `/api/v1/query` answers HTTP 401.
+
+## Endpoints
+
+- `POST /api/v1/query` - Ask a question as the configured role
+- `GET /api/v1/health` - Liveness check
+- `GET /api/v1/ready` - Readiness check (does not yet check dependencies)
+- `POST /api/v1/datasource` - Register a datasource in the running process
+- `GET /api/v1/datasource` - List registered datasource ids
+- `GET /api/v1/datasource/{datasource_id}` - Check a datasource is registered
+- `DELETE /api/v1/datasource/{datasource_id}` - Not supported yet (answers `success: false`)
+- `POST /api/v1/llm` - Configure an LLM in the running process
+- `GET /api/v1/llm` - List configured LLMs
+- `GET /api/v1/llm/{llm_name}` - Get one configured LLM
+- `POST /api/v1/index/{datasource_id}` - Index one datasource's schema
+- `POST /api/v1/index-all` - Index every registered datasource
+- `DELETE /api/v1/index` - Clear the vector store
+- `GET /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>.