From c9b38771bcfb1d72ac1cb79cd50aebb686ebc499 Mon Sep 17 00:00:00 2001 From: Zay-M3 Date: Sun, 19 Apr 2026 13:05:08 -0500 Subject: [PATCH] add: add new documentation, link with pypi and npm version of naturalsql also add in about the principal contrubutor of the typescript version --- app/client/nginx/default.conf | 87 -------- app/client/src/pages/About.tsx | 19 +- app/client/src/pages/Chat.tsx | 50 ++++- app/client/src/pages/Documentation.tsx | 290 +++++++++++++++++++++++++ 4 files changed, 353 insertions(+), 93 deletions(-) delete mode 100644 app/client/nginx/default.conf diff --git a/app/client/nginx/default.conf b/app/client/nginx/default.conf deleted file mode 100644 index ba28f9b..0000000 --- a/app/client/nginx/default.conf +++ /dev/null @@ -1,87 +0,0 @@ -# Basic worker defaults (inherited from image) - -# Preserve real client IP from reverse proxy/LB when present -map $http_x_forwarded_for $client_real_ip { - "" $remote_addr; - default $http_x_forwarded_for; -} - -# Force HTTPS when proxy indicates plain HTTP -map $http_x_forwarded_proto $redirect_to_https { - default 1; - https 0; -} - -# Request rate zones -limit_req_zone $client_real_ip zone=auth_limit:10m rate=5r/m; -limit_req_zone $client_real_ip zone=chat_limit:10m rate=5r/m; - -upstream backend_upstream { - server backend:8000; - keepalive 16; -} - -server { - listen 80; - server_name _; - - # If traffic reaches this Nginx over HTTP at the edge, redirect to HTTPS. - if ($redirect_to_https = 1) { - return 301 https://$host$request_uri; - } - - root /usr/share/nginx/html; - index index.html; - - # Security headers - add_header X-Frame-Options "SAMEORIGIN" always; - add_header X-Content-Type-Options "nosniff" always; - add_header Referrer-Policy "strict-origin-when-cross-origin" always; - add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always; - add_header Cross-Origin-Opener-Policy "same-origin" always; - add_header Cross-Origin-Resource-Policy "same-origin" always; - add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https://naturalsql.online; font-src 'self' data:; frame-ancestors 'self'; base-uri 'self'; form-action 'self';" always; - - # Backend API reverse proxy (private Docker network) - location /api/auth/login { - limit_req zone=auth_limit burst=5 nodelay; - - proxy_pass http://backend_upstream/api/auth/login; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto; - proxy_read_timeout 300s; - proxy_send_timeout 300s; - } - - location /api/chat/message { - limit_req zone=chat_limit burst=10 nodelay; - - proxy_pass http://backend_upstream/api/chat/message; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto; - proxy_read_timeout 300s; - proxy_send_timeout 300s; - } - - location /api/ { - proxy_pass http://backend_upstream/api/; - proxy_http_version 1.1; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto; - proxy_read_timeout 300s; - proxy_send_timeout 300s; - } - - # Static assets and SPA fallback - location / { - try_files $uri /index.html; - } -} diff --git a/app/client/src/pages/About.tsx b/app/client/src/pages/About.tsx index 49a1a7c..6a4922a 100644 --- a/app/client/src/pages/About.tsx +++ b/app/client/src/pages/About.tsx @@ -20,7 +20,7 @@ export default function About() { database structure.

- NaturalSQL logo + NaturalSQL logo + +
+

+ TypeScript version contributor +

+

+ Main contributor and builder of the TypeScript version. +

+ +
diff --git a/app/client/src/pages/Chat.tsx b/app/client/src/pages/Chat.tsx index f9e31c8..af5b18d 100644 --- a/app/client/src/pages/Chat.tsx +++ b/app/client/src/pages/Chat.tsx @@ -48,6 +48,51 @@ export const Chat = () => {

NaturalSQL

Please log in to access the chat.

+ +
+ +

+ This chat is connected to a fixed playground database. Ask questions that are related to + the existing schema and tables shown below. +

+

+ Questions outside this database context can produce irrelevant answers. +

+
    + {playgroundTables.map((table) => ( +
  • + {table} +
    • + ))} +
+ +
+ +
+ +

+ Explore and install the package from your preferred ecosystem. +

+
+ + Open on npm + + + Open on PyPI + +
+ +
) @@ -179,8 +224,3 @@ export const Chat = () => { ) } -// {messages.length === 0 ? ( -//
  • -//

    NaturalSQL

    -//
    • -// ) : null} diff --git a/app/client/src/pages/Documentation.tsx b/app/client/src/pages/Documentation.tsx index b3d3ab9..c8c2536 100644 --- a/app/client/src/pages/Documentation.tsx +++ b/app/client/src/pages/Documentation.tsx @@ -9,10 +9,12 @@ import { Tabs } from '../components/ui/Tabs' import { Topbar } from '../components/ui/Topbar' const DOCS_VERSION = '1.2.5' +const TYPESCRIPT_DOCS_VERSION = '1.2.5' const sidebarItems = [ { id: 'problem-solution', label: 'Problem & Solution' }, { id: 'installation', label: 'Installation' }, + { id: 'typescript-docs', label: 'TypeScript' }, { id: 'sql-engines', label: 'Supported SQL Engines' }, { id: 'quick-start', label: 'Quick Start' }, { id: 'cache-performance', label: 'Cache & Performance' }, @@ -141,6 +143,101 @@ const e2eTabs = [ }, ] +const tsInstallCode = [ + '# Base package', + 'npm i naturalsql', + '', + '# Chroma + local embeddings', + 'npm i chromadb @xenova/transformers', + '', + '# SQLite + local embeddings', + 'npm i better-sqlite3 @xenova/transformers', + '', + '# SQLite + Gemini embeddings', + 'npm i better-sqlite3 @google/generative-ai', + '', + '# Chroma + Gemini embeddings', + 'npm i chromadb @google/generative-ai', + '', + '# PostgreSQL driver support', + 'npm i pg', + '', + '# MySQL driver support', + 'npm i mysql2', + '', + '# SQL Server driver support', + 'npm i mssql', +].join('\n') + +const tsQuickStartCode = [ + 'import { NaturalSQL } from "naturalsql";', + '', + 'const nsql = new NaturalSQL({', + ' dbUrl: "postgresql://user:password@localhost:5432/mydb",', + ' dbType: "postgresql"', + '});', + '', + 'const result = await nsql.buildVectorDb("./metadata_vdb");', + 'console.log(`Indexed tables: ${result.indexedTables}`);', + 'console.log(`From cache: ${result.fromCache}`);', + '', + 'const tables = await nsql.search("Show me sales from last month", {', + ' storagePath: "./metadata_vdb",', + ' limit: 3', + '});', + '', + 'for (const table of tables) {', + ' console.log(table);', + '}', +].join('\n') + +const tsE2EChromaLocalCode = [ + 'import { NaturalSQL } from "naturalsql";', + '', + 'const nsql = new NaturalSQL({', + ' dbUrl: "postgresql://user:pass@localhost:5432/mydb",', + ' dbType: "postgresql",', + ' vectorBackend: "chroma",', + ' embeddingProvider: "local",', + ' vectorDistanceThreshold: 0.35', + '});', + '', + 'await nsql.buildVectorDb("./metadata_vdb", { forceReset: false });', + 'const tables = await nsql.search("sales for the last month", {', + ' storagePath: "./metadata_vdb",', + ' limit: 3', + '});', + 'console.log(tables);', +].join('\n') + +const tsE2ESqliteGeminiCode = [ + 'import { NaturalSQL } from "naturalsql";', + '', + 'const nsql = new NaturalSQL({', + ' dbUrl: "sqlite:///./app.db",', + ' dbType: "sqlite",', + ' vectorBackend: "sqlite",', + ' embeddingProvider: "gemini",', + ' geminiApiKey: process.env.GEMINI_API_KEY,', + ' geminiEmbeddingModel: "text-embedding-004"', + '});', + '', + 'await nsql.buildVectorDb("./metadata_vdb_sqlite", { forceReset: false });', + 'const tables = await nsql.search("users with recent purchases", {', + ' storagePath: "./metadata_vdb_sqlite",', + ' limit: 3', + '});', + 'console.log(tables);', +].join('\n') + +const tsBuildPromptCode = [ + 'import { buildPrompt } from "naturalsql";', + '', + 'const prompt = buildPrompt(tables, "Show me sales from last month");', +].join('\n') + +const tsDevCommandsCode = ['npm run test', 'npm run typecheck', 'npm run build'].join('\n') + export default function Documentation() { return (
    @@ -184,6 +281,199 @@ export default function Documentation() { +
    + + Node.js >=18 is required. For Gemini, use @google/generative-ai and + environment variables like GEMINI_API_KEY (never hardcode secrets). + + + Sometimes you want to interact with SQL databases through an LLM without pulling in large frameworks + with many unrelated features. + + + NaturalSQL extracts your database schema, vectorizes it using a configurable backend + (chroma or sqlite) and embedding provider (local or + gemini), then retrieves relevant schema context for your LLM. + + + + + + + + + + + +

    + buildVectorDb() reuses vector storage when possible (same storage path + schema cache + key), unless forceReset: true is provided. +

    +

    + Also, search() reuses the in-memory VectorManager for the same + storagePath to reduce repeated initialization cost. +

    +     + + +
      +
    • PostgreSQL
      • +
    • MySQL
      • +
    • SQL Server
      • +
    • SQLite
      • +
    +     + + + +
    + + + + +

    + new NaturalSQL(options?) creates an instance with DB and embedding configuration. +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ParameterTypeDefaultDescription
    dbUrlstring | nullnullDatabase connection URL
    dbTypestringsqlitepostgresql, mysql, sqlite, sqlserver
    normalizeEmbeddingsbooleantrueNormalize embedding vectors
    devicestringcpuEmbedding device: cpu or cuda
    vectorBackendchroma | sqlitesqliteVector backend
    embeddingProviderlocal | geminilocalEmbedding provider
    geminiApiKeystring | nullnullRequired when embeddingProvider=gemini
    geminiEmbeddingModelstringtext-embedding-004Gemini embedding model
    vectorDistanceThresholdnumber0.35Max distance threshold used by search()
    +
    + +

    Supported backend/provider combinations

    +
      +
    • chroma + local
      • +
    • sqlite + local
      • +
    • sqlite + gemini
      • +
    • chroma + gemini
      • +
    + +
    + + + + + + + + + + + + + + + + + + + + + +
    MethodSummary
    + await nsql.buildVectorDb(storagePath, options?) + + Extracts schema and indexes it. Supports forceReset and optional + cacheKey. Returns storagePath, indexedTables, and + fromCache. +
    await nsql.search(request, options?) + Retrieves semantically relevant tables. Options include storagePath (default + ./metadata_vdb) and limit (default 3). +
    + buildPrompt(relevantTables, userQuestion) + + Helper to create an LLM prompt from retrieved tables and a user question. +
    +
    + +
    + +
    +     + + +
      +
    1. Connection via native drivers (pg, mysql2, mssql) or SQLite support.
      2. +
    2. Schema extraction via engine-specific metadata queries or PRAGMA for SQLite.
      3. +
    3. Vectorization into semantic documents indexed in chroma or sqlite.
      4. +
    4. Retrieval via nearest-neighbor search with vectorDistanceThreshold filtering.
      5. +
    5. Caching through schema-key reuse and in-memory manager reuse.
      6. +
    +     + + + + +
    +