nl2sql-api 0.1.0__tar.gz

nl2sql_api-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: nl2sql-api
+Version: 0.1.0
+Summary: API layer for NL2SQL engine
+Requires-Python: >=3.9
+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-0.1.0/README.md

@@ -0,0 +1,85 @@
+# NL2SQL API
+
+API layer for the NL2SQL engine that provides a REST interface to the core functionality.
+
+## Two-Tier API Architecture
+
+NL2SQL provides a two-tier API architecture:
+
+### 1. Core API (Python)
+- **Location**: Core package (`nl2sql`)
+- **Interface**: Direct Python class interface (`NL2SQL` class)
+- **Use Case**: Direct Python integration, embedded applications
+- **Access**: Import and use directly in Python code
+
+### 2. REST API (HTTP) - This Package
+- **Location**: API package (`nl2sql-api`) - This package
+- **Interface**: HTTP REST endpoints
+- **Use Case**: Remote clients, web applications, TypeScript CLI
+- **Access**: HTTP requests to API endpoints
+
+This REST API package serves as a bridge between external HTTP clients and the core NL2SQL engine, using the core's public API internally.
+
+## Overview
+
+This package provides a FastAPI-based REST API that uses the NL2SQL core's public API to interact with the NL2SQL engine over HTTP. It serves as a bridge between external clients (such as the TypeScript CLI) and the core engine functionality.
+
+## Architecture
+
+The API package leverages the NL2SQL core's public API layer (`NL2SQL` class), ensuring clean separation between the API service and the core engine implementation. The service layer uses the core's public methods like `run_query()`, `list_datasources()`, and schema access through `engine.context.schema_store`.
+
+## Features
+
+- RESTful API endpoints for natural language to SQL conversion
+- Datasource and LLM management endpoints
+- Health and readiness checks
+- Proper error handling and response formatting
+- Lazy initialization to avoid configuration issues during import
+- Integration with the core's public API layer
+
+## Endpoints
+
+### Query Endpoints
+- `POST /api/v1/query` - Execute a natural language query
+- `GET /api/v1/health` - Health check endpoint
+- `GET /api/v1/ready` - Readiness check endpoint
+
+### Datasource Management Endpoints
+- `POST /api/v1/datasource` - Add a new datasource programmatically
+- `GET /api/v1/datasource` - List all registered datasources
+- `GET /api/v1/datasource/{datasource_id}` - Get details of a specific datasource
+- `DELETE /api/v1/datasource/{datasource_id}` - Remove a datasource (not currently supported)
+
+### LLM Management Endpoints
+- `POST /api/v1/llm` - Configure an LLM programmatically
+- `GET /api/v1/llm` - List all configured LLMs
+- `GET /api/v1/llm/{llm_name}` - Get details of a specific LLM
+
+### Indexing Management Endpoints
+- `POST /api/v1/index/{datasource_id}` - Index schema for a specific datasource
+- `POST /api/v1/index-all` - Index schema for all registered datasources
+- `DELETE /api/v1/index` - Clear the vector store index
+- `GET /api/v1/index/status` - Get the status of the index
+
+## Running the API
+
+```bash
+pip install -e .
+nl2sql-api --host 0.0.0.0 --port 8000 --reload
+```
+
+Or using the server script directly:
+
+```bash
+python -m nl2sql_api.server --host 0.0.0.0 --port 8000 --reload
+```
+
+## Development
+
+Install in development mode:
+
+```bash
+pip install -e .
+```
+
+For detailed API documentation, see [API_DOCS.md](API_DOCS.md).

nl2sql_api-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nl2sql-api"
+version = "0.1.0" # x-release-please-version
+description = "API layer for NL2SQL engine"
+requires-python = ">=3.9"
+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.scripts]
+nl2sql-api = "nl2sql_api.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["nl2sql_api*"]

nl2sql_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nl2sql_api-0.1.0/src/nl2sql_api/dependencies.py

@@ -0,0 +1,44 @@
+from fastapi import Depends, Request
+
+from nl2sql import NL2SQL
+from nl2sql_api.services import (
+    DatasourceService,
+    QueryService,
+    LLMService,
+    IndexingService,
+    HealthService,
+)
+
+
+def get_engine(request: Request) -> NL2SQL:
+    return request.app.state.engine
+
+
+def get_datasource_service(
+    engine: NL2SQL = Depends(get_engine),
+) -> DatasourceService:
+    return DatasourceService(engine)
+
+
+def get_query_service(
+    engine: NL2SQL = Depends(get_engine),
+) -> QueryService:
+    return QueryService(engine)
+
+
+def get_llm_service(
+    engine: NL2SQL = Depends(get_engine),
+) -> LLMService:
+    return LLMService(engine)
+
+
+def get_indexing_service(
+    engine: NL2SQL = Depends(get_engine),
+) -> IndexingService:
+    return IndexingService(engine)
+
+
+def get_health_service(
+    engine: NL2SQL = Depends(get_engine),
+) -> HealthService:
+    return HealthService(engine)

nl2sql_api-0.1.0/src/nl2sql_api/main.py

@@ -0,0 +1,47 @@
+import os
+
+from fastapi import FastAPI
+from contextlib import asynccontextmanager
+
+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
+
+
+@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()
+    yield
+
+
+app = FastAPI(
+    title="NL2SQL API",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.include_router(query.router, prefix="/api/v1")
+app.include_router(health.router, prefix="/api/v1")
+app.include_router(datasource.router, prefix="/api/v1")
+app.include_router(llm.router, prefix="/api/v1")
+app.include_router(indexing.router, prefix="/api/v1")
+
+_origins = [o.strip() for o in os.getenv("NL2SQL_API_CORS_ORIGINS", "").split(",") if o.strip()]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=_origins,
+    allow_credentials=bool(_origins),
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+

nl2sql_api-0.1.0/src/nl2sql_api/models/datasource.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+from typing import Dict, Any, Optional
+
+class DatasourceRequest(BaseModel):
+    config: Dict[str, Any]
+
+
+class DatasourceResponse(BaseModel):
+    success: bool
+    message: str
+    datasource_id: Optional[str] = None

nl2sql_api-0.1.0/src/nl2sql_api/models/llm.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel
+from typing import Dict, Any, Optional
+
+class LLMRequest(BaseModel):
+    config: Dict[str, Any]
+
+
+class LLMResponse(BaseModel):
+    success: bool
+    message: str
+    llm_name: Optional[str] = None

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

@@ -0,0 +1,33 @@
+from pydantic import BaseModel, Field
+from typing import Optional, Dict, Any, List
+
+
+class QueryRequest(BaseModel):
+    natural_language: str
+    datasource_id: Optional[str] = None
+    execute: bool = True
+    user_context: Optional[Dict[str, Any]] = None
+
+
+class SubQueryResponse(BaseModel):
+    """One decomposed sub-query and the SQL generated for it."""
+    id: str = ""
+    intent: str = ""
+    sql: str = ""
+    datasource_id: str = ""
+    schema_version: str = ""
+
+
+class QueryResponse(BaseModel):
+    """Mirrors ``nl2sql.api.query_api.QueryResult``.
+
+    Result rows are not inlined; they live in artifact storage and are addressable
+    through ``artifact_refs``.
+    """
+    sub_queries: List[SubQueryResponse] = Field(default_factory=list)
+    final_answer: Optional[Dict[str, Any]] = None
+    errors: List[Dict[str, Any]] = Field(default_factory=list)
+    trace_id: Optional[str] = None
+    reasoning: List[Dict[str, Any]] = Field(default_factory=list)
+    warnings: List[Dict[str, Any]] = Field(default_factory=list)
+    artifact_refs: Dict[str, Dict[str, Any]] = Field(default_factory=dict)

nl2sql_api-0.1.0/src/nl2sql_api/models/response.py

@@ -0,0 +1,13 @@
+from pydantic import BaseModel
+from typing import Optional, List, Dict, Any
+
+class ErrorResponse(BaseModel):
+    error_code: str
+    message: str
+    details: Optional[Dict[str, Any]] = None
+
+
+class SuccessResponse(BaseModel):
+    success: bool
+    data: Optional[Dict[str, Any]] = None
+    message: Optional[str] = None

nl2sql_api-0.1.0/src/nl2sql_api/models/schema.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel
+from typing import Optional, List, Dict, Any
+
+class SchemaResponse(BaseModel):
+    datasource_id: str
+    tables: List[Dict[str, Any]]
+    relationships: List[Dict[str, Any]]
+    metadata: Optional[Dict[str, Any]] = None

nl2sql_api-0.1.0/src/nl2sql_api/routes/datasource.py

@@ -0,0 +1,57 @@
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Dict, Any, Annotated
+
+from nl2sql_api.models.datasource import DatasourceRequest, DatasourceResponse
+from nl2sql_api.dependencies import get_datasource_service
+from nl2sql_api.services import DatasourceService
+
+router = APIRouter()
+
+DatasourceSvc = Annotated[DatasourceService, Depends(get_datasource_service)]
+
+
+@router.post("/datasource", response_model=DatasourceResponse)
+def add_datasource(
+    payload: DatasourceRequest,
+    service: DatasourceSvc,
+):
+    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])
+def list_datasources(
+    service: DatasourceSvc,
+):
+    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])
+def get_datasource(
+    datasource_id: str,
+    service: DatasourceSvc,
+):
+    try:
+        return service.get_datasource(datasource_id)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.delete("/datasource/{datasource_id}", response_model=Dict[str, Any])
+def remove_datasource(
+    datasource_id: str,
+    service: DatasourceSvc,
+):
+    try:
+        return service.remove_datasource(datasource_id)
+    except ValueError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

nl2sql_api-0.1.0/src/nl2sql_api/routes/health.py

@@ -0,0 +1,22 @@
+from fastapi import APIRouter, Depends
+from typing import Annotated
+from nl2sql_api.models.response import SuccessResponse
+from nl2sql_api.dependencies import get_health_service
+from nl2sql_api.services import HealthService
+
+router = APIRouter()
+
+HealthSvc = Annotated[HealthService, Depends(get_health_service)]
+
+@router.get("/health", response_model=SuccessResponse)
+async def health_check(
+    service: HealthSvc
+):
+    return service.health_check()
+
+
+@router.get("/ready", response_model=SuccessResponse)
+async def readiness_check(
+    service: HealthSvc,
+):
+    return service.readiness_check()

nl2sql_api-0.1.0/src/nl2sql_api/routes/indexing.py

@@ -0,0 +1,73 @@
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Dict, Any, Annotated
+
+from nl2sql_api.dependencies import get_indexing_service
+from nl2sql_api.services import IndexingService
+router = APIRouter()
+
+IndexingSvc = Annotated[IndexingService, Depends(get_indexing_service)]
+
+@router.post("/index/{datasource_id}", response_model=Dict[str, Any])
+def index_datasource(
+    datasource_id: str,
+    service: IndexingSvc
+):
+    try:
+        result = service.index_datasource(datasource_id)
+
+        return {
+            "success": True,
+            "datasource_id": datasource_id,
+            "indexing_stats": result,
+            "message": f"Successfully indexed datasource '{datasource_id}'",
+        }
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to index datasource '{datasource_id}': {str(e)}",
+        )
+
+
+@router.post("/index-all", response_model=Dict[str, Any])
+def index_all_datasources(
+    service: IndexingSvc
+):
+    try:
+        results = service.index_all_datasources()
+
+        return {
+            "success": True,
+            "indexing_results": results,
+            "message": "Successfully initiated indexing for all datasources",
+        }
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to index all datasources: {str(e)}",
+        )
+
+
+@router.delete("/index", response_model=Dict[str, Any])
+def clear_index(
+    service: IndexingSvc
+):
+    try:
+        return service.clear_index()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to clear index: {str(e)}",
+        )
+
+
+@router.get("/index/status", response_model=Dict[str, Any])
+def get_index_status(
+    service: IndexingSvc
+):
+    try:
+        return service.get_index_status()
+    except Exception as e:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to get index status: {str(e)}",
+        )

nl2sql_api-0.1.0/src/nl2sql_api/routes/llm.py

@@ -0,0 +1,41 @@
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Dict, Any, Annotated
+
+from nl2sql_api.models.llm import LLMRequest, LLMResponse
+from nl2sql_api.dependencies import get_llm_service
+from nl2sql_api.services import LLMService
+
+router = APIRouter()
+
+LLMSvc = Annotated[LLMService, Depends(get_llm_service)]
+
+@router.post("/llm", response_model=LLMResponse)
+def configure_llm(
+    payload: LLMRequest,
+    service: LLMSvc,
+):
+    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])
+def list_llms(
+    service: LLMSvc,
+):
+    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])
+def get_llm(
+    llm_name: str,
+    service: LLMSvc,
+):
+    try:
+        return service.get_llm(llm_name)
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))

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

@@ -0,0 +1,29 @@
+import logging
+
+from fastapi import APIRouter, HTTPException, Depends
+from typing import Annotated
+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()
+
+QuerySvc = Annotated[QueryService, Depends(get_query_service)]
+
+
+# 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)
+def execute_query(
+    payload: QueryRequest,
+    service: QuerySvc,
+):
+    try:
+        return service.execute_query(payload)
+    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.0/src/nl2sql_api/server.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+"""
+NL2SQL API Startup Script
+
+This script starts the NL2SQL API server.
+"""
+
+import argparse
+import sys
+from nl2sql_api.main import app
+import uvicorn
+
+def main():
+    parser = argparse.ArgumentParser(description='NL2SQL API Server')
+    parser.add_argument('--host', default='127.0.0.1', help='Host to bind to (default: 127.0.0.1)')
+    parser.add_argument('--port', type=int, default=8000, help='Port to bind to (default: 8000)')
+    parser.add_argument('--reload', action='store_true', help='Enable auto-reload (development)')
+    
+    args = parser.parse_args()
+    
+    uvicorn.run(
+        'nl2sql_api.main:app',
+        host=args.host,
+        port=args.port,
+        reload=args.reload,
+        log_level="info"
+    )
+
+if __name__ == '__main__':
+    main()

nl2sql_api-0.1.0/src/nl2sql_api/services/__init__.py

@@ -0,0 +1,15 @@
+
+from .datasource import DatasourceService
+from .llm import LLMService
+from .health import HealthService
+from .query import QueryService
+from .indexing import IndexingService
+
+
+__all__ = [
+    "DatasourceService",
+    "LLMService",
+    "HealthService",
+    "QueryService",
+    "IndexingService"
+]

nl2sql_api-0.1.0/src/nl2sql_api/services/datasource.py

@@ -0,0 +1,43 @@
+from typing import Dict, Any, Optional
+
+from nl2sql import NL2SQL
+from nl2sql_api.models.datasource import DatasourceRequest, DatasourceResponse
+
+
+class DatasourceService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def add_datasource(self, request: DatasourceRequest) -> DatasourceResponse:
+        """Add a new datasource programmatically."""
+        self.engine.add_datasource(request.config)
+        return DatasourceResponse(
+            success=True,
+            message=f"Datasource '{request.config.get('id')}' added successfully",
+            datasource_id=request.config.get('id')
+        )
+
+    def list_datasources(self) -> list:
+        """List all registered datasources."""
+        return self.engine.list_datasources()
+
+    def get_datasource(self, datasource_id: str) -> dict:
+        """Get details of a specific datasource."""
+        datasource_ids = self.engine.list_datasources()
+        if datasource_id not in datasource_ids:
+            raise ValueError(f"Datasource '{datasource_id}' not found")
+        
+        # In a real implementation, we would return detailed information about the datasource
+        return {"datasource_id": datasource_id, "exists": True}
+
+    def remove_datasource(self, datasource_id: str) -> dict:
+        """Remove a datasource (not directly supported by the engine, but could be implemented)."""
+        datasource_ids = self.engine.list_datasources()
+        if datasource_id not in datasource_ids:
+            raise ValueError(f"Datasource '{datasource_id}' not found")
+        
+        return {
+            "success": False,
+            "message": "Removing datasources is not currently supported by the engine",
+            "datasource_id": datasource_id
+        }

nl2sql_api-0.1.0/src/nl2sql_api/services/health.py

@@ -0,0 +1,22 @@
+from typing import Dict, Any, Optional
+from nl2sql import NL2SQL
+
+
+class HealthService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def health_check(self) -> dict:
+        """Perform health check."""
+        return {
+            "success": True,
+            "message": "NL2SQL API is running"
+        }
+
+    def readiness_check(self) -> dict:
+        """Perform readiness check."""
+        # Add actual readiness checks (database connections, etc.)
+        return {
+            "success": True,
+            "message": "NL2SQL API is ready"
+        }

nl2sql_api-0.1.0/src/nl2sql_api/services/indexing.py

@@ -0,0 +1,30 @@
+from typing import Dict, Any, Optional
+from nl2sql import NL2SQL
+
+
+class IndexingService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def index_datasource(self, datasource_id: str) -> Dict[str, int]:
+        """Index schema for a specific datasource."""
+        return self.engine.indexing.index_datasource(datasource_id)
+
+    def index_all_datasources(self) -> Dict[str, Dict[str, int]]:
+        """Index schema for all registered datasources."""
+        return self.engine.indexing.index_all_datasources()
+
+    def clear_index(self) -> None:
+        """Clear the vector store index."""
+        self.engine.indexing.clear_index()
+        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
+        }

nl2sql_api-0.1.0/src/nl2sql_api/services/llm.py

@@ -0,0 +1,25 @@
+from typing import Dict, Any, Optional
+from nl2sql import NL2SQL
+from nl2sql_api.models.llm import LLMRequest, LLMResponse
+
+
+class LLMService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def configure_llm(self, request: LLMRequest) -> LLMResponse:
+        """Configure an LLM programmatically."""
+        self.engine.configure_llm(request.config)
+        return LLMResponse(
+            success=True,
+            message=f"LLM '{request.config.get('name', 'default')}' configured successfully",
+            llm_name=request.config.get('name', 'default')
+        )
+
+    def list_llms(self) -> list:
+        """List all configured LLMs."""
+        return self.engine.list_llms()
+
+    def get_llm(self, llm_name: str) -> dict:
+        """Get details of a specific LLM."""
+        return self.engine.get_llm(llm_name)

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

@@ -0,0 +1,34 @@
+from nl2sql import NL2SQL
+from nl2sql_api.models.query import QueryRequest, QueryResponse
+from nl2sql.auth.models import UserContext
+
+
+class QueryService:
+    def __init__(self, engine: NL2SQL):
+        self.engine = engine
+
+    def execute_query(self, request: QueryRequest) -> QueryResponse:
+        # Convert user_context if provided
+        user_context = None
+        if request.user_context:
+            user_context = UserContext(**request.user_context)
+
+        result = self.engine.run_query(
+            request.natural_language,
+            datasource_id=request.datasource_id,
+            execute=request.execute,
+            user_context=user_context,
+        )
+
+        return QueryResponse(
+            sub_queries=[sub_query.model_dump() for sub_query in result.sub_queries],
+            final_answer=result.final_answer,
+            errors=result.errors,
+            trace_id=result.trace_id,
+            reasoning=result.reasoning,
+            warnings=result.warnings,
+            artifact_refs={
+                node_id: ref.model_dump(mode="json")
+                for node_id, ref in result.artifact_refs.items()
+            },
+        )

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

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: nl2sql-api
+Version: 0.1.0
+Summary: API layer for NL2SQL engine
+Requires-Python: >=3.9
+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-0.1.0/src/nl2sql_api.egg-info/SOURCES.txt

@@ -0,0 +1,34 @@
+README.md
+pyproject.toml
+src/nl2sql_api/__init__.py
+src/nl2sql_api/dependencies.py
+src/nl2sql_api/main.py
+src/nl2sql_api/server.py
+src/nl2sql_api.egg-info/PKG-INFO
+src/nl2sql_api.egg-info/SOURCES.txt
+src/nl2sql_api.egg-info/dependency_links.txt
+src/nl2sql_api.egg-info/entry_points.txt
+src/nl2sql_api.egg-info/requires.txt
+src/nl2sql_api.egg-info/top_level.txt
+src/nl2sql_api/models/__init__.py
+src/nl2sql_api/models/datasource.py
+src/nl2sql_api/models/llm.py
+src/nl2sql_api/models/query.py
+src/nl2sql_api/models/response.py
+src/nl2sql_api/models/schema.py
+src/nl2sql_api/routes/__init__.py
+src/nl2sql_api/routes/datasource.py
+src/nl2sql_api/routes/health.py
+src/nl2sql_api/routes/indexing.py
+src/nl2sql_api/routes/llm.py
+src/nl2sql_api/routes/query.py
+src/nl2sql_api/services/__init__.py
+src/nl2sql_api/services/datasource.py
+src/nl2sql_api/services/health.py
+src/nl2sql_api/services/indexing.py
+src/nl2sql_api/services/llm.py
+src/nl2sql_api/services/query.py
+tests/test_app.py
+tests/test_cors.py
+tests/test_query_routes.py
+tests/test_services.py

nl2sql_api-0.1.0/src/nl2sql_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nl2sql_api-0.1.0/src/nl2sql_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nl2sql-api = nl2sql_api.server:main

nl2sql_api-0.1.0/src/nl2sql_api.egg-info/requires.txt

@@ -0,0 +1,6 @@
+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

nl2sql_api-0.1.0/src/nl2sql_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+nl2sql_api

nl2sql_api-0.1.0/tests/test_app.py

@@ -0,0 +1,32 @@
+"""App wiring tests (ported from packages/api/test_api.py)."""
+
+import inspect
+
+from nl2sql_api import dependencies
+from nl2sql_api.main import app
+from nl2sql_api.routes import datasource, indexing, llm, query
+
+
+def test_app_is_constructed():
+    assert app is not None
+    assert app.title == "NL2SQL API"
+
+
+def test_dependency_providers_are_callable():
+    assert callable(dependencies.get_engine)
+    assert callable(dependencies.get_query_service)
+
+
+def test_health_endpoint_is_registered():
+    paths = app.openapi()["paths"]
+    assert "/api/v1/health" in paths
+    assert "/api/v1/query" in paths
+
+
+def test_routes_doing_blocking_work_are_synchronous():
+    """`async def` handlers around blocking calls would serialise the whole API."""
+    for module in (query, datasource, llm, indexing):
+        for name, func in vars(module).items():
+            if name.startswith("_") or not inspect.isfunction(func):
+                continue
+            assert not inspect.iscoroutinefunction(func), f"{module.__name__}.{name} is async"

nl2sql_api-0.1.0/tests/test_cors.py

@@ -0,0 +1,72 @@
+"""CORS configuration tests.
+
+The CORS middleware is attached at import time, so each case reloads
+``nl2sql_api.main`` with the environment it wants and restores the module to its
+default (no configured origins) afterwards.
+"""
+
+import importlib
+
+import pytest
+from fastapi.testclient import TestClient
+
+import nl2sql_api.main
+
+ENV_VAR = "NL2SQL_API_CORS_ORIGINS"
+
+
+@pytest.fixture
+def app_with_cors_env(monkeypatch):
+    """Reload the app under a given ``NL2SQL_API_CORS_ORIGINS`` value."""
+    clients = []
+
+    def _make(origins):
+        if origins is None:
+            monkeypatch.delenv(ENV_VAR, raising=False)
+        else:
+            monkeypatch.setenv(ENV_VAR, origins)
+        module = importlib.reload(nl2sql_api.main)
+        client = TestClient(module.app)
+        clients.append(client)
+        return client
+
+    yield _make
+
+    for client in clients:
+        client.close()
+    # Restore the module to the default configuration for any later test.
+    monkeypatch.delenv(ENV_VAR, raising=False)
+    importlib.reload(nl2sql_api.main)
+
+
+def _preflight(client, origin):
+    return client.options(
+        "/api/v1/health",
+        headers={"Origin": origin, "Access-Control-Request-Method": "POST"},
+    )
+
+
+def test_no_configured_origins_rejects_arbitrary_origin(app_with_cors_env):
+    """Wildcard-with-credentials is unsafe; unset means no cross-origin access."""
+    client = app_with_cors_env(None)
+
+    response = _preflight(client, "https://evil.example")
+
+    assert response.headers.get("access-control-allow-origin") != "*"
+    assert response.headers.get("access-control-allow-origin") is None
+
+
+def test_configured_origin_is_echoed_back(app_with_cors_env):
+    client = app_with_cors_env("https://bi.corp.example")
+
+    response = _preflight(client, "https://bi.corp.example")
+
+    assert response.headers.get("access-control-allow-origin") == "https://bi.corp.example"
+
+
+def test_unconfigured_origin_is_rejected_when_others_are_allowed(app_with_cors_env):
+    client = app_with_cors_env("https://bi.corp.example")
+
+    response = _preflight(client, "https://evil.example")
+
+    assert response.headers.get("access-control-allow-origin") is None

nl2sql_api-0.1.0/tests/test_query_routes.py

@@ -0,0 +1,125 @@
+from datetime import datetime, timezone
+
+from nl2sql.api.query_api import QueryResult, SubQueryResult
+from nl2sql.execution.contracts import ArtifactRef
+
+
+def _artifact_ref() -> ArtifactRef:
+    return ArtifactRef(
+        uri="file:///artifacts/sq-1.parquet",
+        backend="local",
+        format="parquet",
+        row_count=2,
+        columns=["region", "revenue"],
+        bytes=512,
+        content_hash="abc123",
+        created_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
+        path_template="{trace_id}/{node_id}",
+    )
+
+
+def _query_result() -> QueryResult:
+    return QueryResult(
+        sub_queries=[
+            SubQueryResult(
+                id="sq-1",
+                intent="total revenue by region",
+                sql="SELECT region, SUM(revenue) FROM sales GROUP BY region",
+                datasource_id="warehouse",
+                schema_version="v3",
+            )
+        ],
+        final_answer={"summary": "Revenue by region", "format_type": "table", "content": "| region |"},
+        trace_id="trace-123",
+        reasoning=[{"node": "decomposer", "message": "split into 1 sub-query"}],
+        warnings=[{"node": "executor", "message": "row limit applied"}],
+        artifact_refs={"sq-1": _artifact_ref()},
+    )
+
+
+def test_execute_query_returns_sql_and_final_answer(api_client):
+    client, _ = api_client(_query_result())
+
+    response = client.post("/api/v1/query", json={"natural_language": "revenue by region"})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["trace_id"] == "trace-123"
+    assert body["final_answer"]["summary"] == "Revenue by region"
+    assert len(body["sub_queries"]) == 1
+    sub_query = body["sub_queries"][0]
+    assert sub_query["id"] == "sq-1"
+    assert sub_query["sql"] == "SELECT region, SUM(revenue) FROM sales GROUP BY region"
+    assert sub_query["datasource_id"] == "warehouse"
+    assert body["reasoning"][0]["node"] == "decomposer"
+    assert body["warnings"][0]["node"] == "executor"
+
+
+def test_execute_query_returns_artifact_refs_not_rows(api_client):
+    client, _ = api_client(_query_result())
+
+    body = client.post("/api/v1/query", json={"natural_language": "revenue by region"}).json()
+
+    assert "results" not in body
+    assert body["artifact_refs"]["sq-1"]["uri"] == "file:///artifacts/sq-1.parquet"
+    assert body["artifact_refs"]["sq-1"]["row_count"] == 2
+
+
+def test_execute_query_forwards_request_options(api_client):
+    client, engine = api_client(QueryResult())
+
+    client.post(
+        "/api/v1/query",
+        json={
+            "natural_language": "revenue by region",
+            "datasource_id": "warehouse",
+            "execute": False,
+            "user_context": {"user_id": "u-1"},
+        },
+    )
+
+    call = engine.calls[0]
+    assert call["natural_language"] == "revenue by region"
+    assert call["datasource_id"] == "warehouse"
+    assert call["execute"] is False
+    assert call["user_context"].user_id == "u-1"
+
+
+def test_pipeline_errors_are_a_200_response(api_client):
+    client, _ = api_client(
+        QueryResult(
+            trace_id="trace-err",
+            errors=[{"node": "generator", "message": "no such column", "error_code": "SQL_GEN_FAILED", "severity": "ERROR"}],
+        )
+    )
+
+    response = client.post("/api/v1/query", json={"natural_language": "bad query"})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert body["errors"][0]["error_code"] == "SQL_GEN_FAILED"
+    assert body["sub_queries"] == []
+
+
+def test_unexpected_failure_is_a_500_without_internal_detail(api_client):
+    client, _ = api_client(RuntimeError("connection string user=admin password=hunter2"))
+
+    response = client.post("/api/v1/query", json={"natural_language": "revenue by region"})
+
+    assert response.status_code == 500
+    assert "hunter2" not in response.json()["detail"]
+
+
+def test_invalid_payload_is_a_422(api_client):
+    client, _ = api_client(QueryResult())
+
+    assert client.post("/api/v1/query", json={}).status_code == 422
+
+
+def test_query_route_is_not_a_coroutine():
+    """Blocking pipeline work must not run on the event loop."""
+    import inspect
+
+    from nl2sql_api.routes import query as query_routes
+
+    assert not inspect.iscoroutinefunction(query_routes.execute_query)

nl2sql_api-0.1.0/tests/test_services.py

@@ -0,0 +1,55 @@
+"""Service-layer tests (ported from packages/api/test_services_updates.py)."""
+
+from nl2sql_api.models.datasource import DatasourceRequest
+from nl2sql_api.models.llm import LLMRequest
+from nl2sql_api.services.datasource import DatasourceService
+from nl2sql_api.services.llm import LLMService
+
+
+class FakeEngine:
+    def __init__(self) -> None:
+        self._datasources = []
+        self._llms = {}
+
+    def add_datasource(self, config):
+        self._datasources.append(config["id"])
+
+    def list_datasources(self):
+        return list(self._datasources)
+
+    def configure_llm(self, config):
+        name = config.get("name", "default")
+        self._llms[name] = config
+
+    def list_llms(self):
+        return {
+            name: {"name": cfg.get("name", name)}
+            for name, cfg in self._llms.items()
+        }
+
+    def get_llm(self, name):
+        if name in self._llms:
+            return self._llms[name]
+        return self._llms.get("default")
+
+
+def test_datasource_service_live_update():
+    engine = FakeEngine()
+    service = DatasourceService(engine)
+
+    service.add_datasource(DatasourceRequest(config={"id": "ds-1"}))
+
+    assert "ds-1" in service.list_datasources()
+
+
+def test_llm_service_live_update():
+    engine = FakeEngine()
+    service = LLMService(engine)
+
+    service.configure_llm(
+        LLMRequest(config={"name": "custom", "provider": "openai", "model": "gpt"})
+    )
+
+    llms = service.list_llms()
+    assert "custom" in llms
+    assert service.get_llm("custom")["name"] == "custom"