natquery 1.0.0__tar.gz

natquery-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tanmai Raghava
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

natquery-1.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: natquery
+Version: 1.0.0
+Summary: Interact with PostgreSQL databases using natural language via a secure, performance-aware CLI
+Author-email: Tanmai Raghava <tanmairaghava@kgpian.iitkgp.ac.in>, Krishna Chaitanya <krish89@kgpian.iitkgp.ac.in>, Thania Joshi <thaniavjoshi@kgpian.iitkgp.ac.in>, Lokeswara Reddy <lokeswarareddy2006@gmail.com>, Manasa Vankam <vankammanasa45@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/N-T-Raghava/NatQuery
+Project-URL: Documentation, https://github.com/N-T-Raghava/NatQuery#readme
+Project-URL: Repository, https://github.com/N-T-Raghava/NatQuery
+Project-URL: Issues, https://github.com/N-T-Raghava/NatQuery/issues
+Keywords: nlp,database,postgres,natural-language,cli,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: groq>=0.4.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black==25.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.6; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+
+# NatQuery
+natquery is a Python package that enables users to interact with relational databases using natural language via a secure, performance-aware command-line interface along with database driven machine learning analytics.
+
+```
+natquery/
+│
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+│── src/
+├   ├── natquery/
+│       ├── __init__.py
+│
+│       # =========================
+│       # 1. CLI LAYER
+│       # =========================
+│       ├── cli/
+│       │   ├── __init__.py
+│       │   ├── main.py              # Entry point
+│       │   ├── shell.py             # Interactive REPL
+│       │   ├── commands.py          # CLI command registry
+│
+│       # =========================
+│       # 2. CONFIG LAYER
+│       # =========================
+│       ├── config/
+│       │   ├── __init__.py
+│       │   ├── settings.py          # API keys, DB config
+│       │   ├── connection.py        # PostgreSQL connection manager
+│
+│       # =========================
+│       # 3. ORCHESTRATION LAYER
+│       # =========================
+│       ├── orchestration/
+│       │   ├── __init__.py
+│       │   ├── pipeline.py          # End-to-end coordinator
+│       │   ├── error_handler.py
+│
+│       # =========================
+│       # 4. SCHEMA MODULE
+│       # =========================
+│       ├── schema/
+│       │   ├── __init__.py
+│       │   ├── extractor.py         # Dynamic schema extraction
+│       │   ├── formatter.py         # Convert schema to prompt-friendly text
+│
+│       # =========================
+│       # 5. PROMPT BUILDER
+│       # =========================
+│       ├── prompt/
+│       │   ├── __init__.py
+│       │   ├── builder.py           # Structured prompt construction
+│
+│       # =========================
+│       # 6. LLM CLIENT
+│       # =========================
+│       ├── llm/
+│       │   ├── __init__.py
+│       │   ├── client.py            # LLM API calls
+│       │   ├── self_corrector.py    # Retry & correction mechanism
+│
+│       # =========================
+│       # 7. SECURITY + VALIDATION
+│       # =========================
+│       ├── security/
+│       │   ├── __init__.py
+│       │   ├── validator.py         # SELECT-only enforcement
+│       │   ├── limiter.py           # LIMIT enforcement
+│
+│       # =========================
+│       # 8. EXECUTION ENGINE
+│       # =========================
+│       ├── execution/
+│       │   ├── __init__.py
+│       │   ├── engine.py            # SQL execution
+│       │   ├── explain.py           # EXPLAIN / ANALYZE
+│
+│       # =========================
+│       # 9. MACHINE LEARNING
+│       # =========================
+│       ├── ml/
+│       │   ├── __init__.py
+│       │   ├── preprocessing.py
+│       │   ├── trainer.py
+│       │   ├── inference.py
+│       │
+│       # =========================
+│       # 10. PERFORMANCE + LOGGING
+│       # =========================
+│       ├── observability/
+│          ├── __init__.py
+│          ├── logger.py
+│          ├── cost_analyzer.py
+│          ├── index_recommender.py
+│
+│
+├── database/
+│   ├── schema.sql
+│   ├── seed.py
+│   ├── synthetic_data.py
+│
+├── tests/
+│   ├── test_pipeline.py
+│   ├── test_security.py
+│   ├── test_ml.py
+│
+└── benchmarks/
+    ├── nl_queries.json

natquery-1.0.0/README.md

@@ -0,0 +1,108 @@
+# NatQuery
+natquery is a Python package that enables users to interact with relational databases using natural language via a secure, performance-aware command-line interface along with database driven machine learning analytics.
+
+```
+natquery/
+│
+├── pyproject.toml
+├── README.md
+├── requirements.txt
+│── src/
+├   ├── natquery/
+│       ├── __init__.py
+│
+│       # =========================
+│       # 1. CLI LAYER
+│       # =========================
+│       ├── cli/
+│       │   ├── __init__.py
+│       │   ├── main.py              # Entry point
+│       │   ├── shell.py             # Interactive REPL
+│       │   ├── commands.py          # CLI command registry
+│
+│       # =========================
+│       # 2. CONFIG LAYER
+│       # =========================
+│       ├── config/
+│       │   ├── __init__.py
+│       │   ├── settings.py          # API keys, DB config
+│       │   ├── connection.py        # PostgreSQL connection manager
+│
+│       # =========================
+│       # 3. ORCHESTRATION LAYER
+│       # =========================
+│       ├── orchestration/
+│       │   ├── __init__.py
+│       │   ├── pipeline.py          # End-to-end coordinator
+│       │   ├── error_handler.py
+│
+│       # =========================
+│       # 4. SCHEMA MODULE
+│       # =========================
+│       ├── schema/
+│       │   ├── __init__.py
+│       │   ├── extractor.py         # Dynamic schema extraction
+│       │   ├── formatter.py         # Convert schema to prompt-friendly text
+│
+│       # =========================
+│       # 5. PROMPT BUILDER
+│       # =========================
+│       ├── prompt/
+│       │   ├── __init__.py
+│       │   ├── builder.py           # Structured prompt construction
+│
+│       # =========================
+│       # 6. LLM CLIENT
+│       # =========================
+│       ├── llm/
+│       │   ├── __init__.py
+│       │   ├── client.py            # LLM API calls
+│       │   ├── self_corrector.py    # Retry & correction mechanism
+│
+│       # =========================
+│       # 7. SECURITY + VALIDATION
+│       # =========================
+│       ├── security/
+│       │   ├── __init__.py
+│       │   ├── validator.py         # SELECT-only enforcement
+│       │   ├── limiter.py           # LIMIT enforcement
+│
+│       # =========================
+│       # 8. EXECUTION ENGINE
+│       # =========================
+│       ├── execution/
+│       │   ├── __init__.py
+│       │   ├── engine.py            # SQL execution
+│       │   ├── explain.py           # EXPLAIN / ANALYZE
+│
+│       # =========================
+│       # 9. MACHINE LEARNING
+│       # =========================
+│       ├── ml/
+│       │   ├── __init__.py
+│       │   ├── preprocessing.py
+│       │   ├── trainer.py
+│       │   ├── inference.py
+│       │
+│       # =========================
+│       # 10. PERFORMANCE + LOGGING
+│       # =========================
+│       ├── observability/
+│          ├── __init__.py
+│          ├── logger.py
+│          ├── cost_analyzer.py
+│          ├── index_recommender.py
+│
+│
+├── database/
+│   ├── schema.sql
+│   ├── seed.py
+│   ├── synthetic_data.py
+│
+├── tests/
+│   ├── test_pipeline.py
+│   ├── test_security.py
+│   ├── test_ml.py
+│
+└── benchmarks/
+    ├── nl_queries.json

natquery-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "natquery"
+version = "1.0.0"
+description = "Interact with PostgreSQL databases using natural language via a secure, performance-aware CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Tanmai Raghava", email = "tanmairaghava@kgpian.iitkgp.ac.in"},
+    {name = "Krishna Chaitanya", email = "krish89@kgpian.iitkgp.ac.in"},
+    {name = "Thania Joshi", email = "thaniavjoshi@kgpian.iitkgp.ac.in"},
+    {name = "Lokeswara Reddy", email = "lokeswarareddy2006@gmail.com"},
+    {name = "Manasa Vankam", email = "vankammanasa45@gmail.com"}
+]
+keywords = ["nlp", "database", "postgres", "natural-language", "cli", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Utilities",
+]
+
+dependencies = [
+    "psycopg2-binary>=2.9.0",
+    "groq>=0.4.0",
+    "rich>=13.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/N-T-Raghava/NatQuery"
+Documentation = "https://github.com/N-T-Raghava/NatQuery#readme"
+Repository = "https://github.com/N-T-Raghava/NatQuery"
+Issues = "https://github.com/N-T-Raghava/NatQuery/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "black==25.1.0",
+    "ruff==0.15.6",
+    "build>=1.0.0",
+    "twine>=4.0.0"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.scripts]
+natquery = "natquery.cli.main:main"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: marks integration tests"
+]
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

natquery-1.0.0/setup.cfg

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

natquery-1.0.0/src/natquery/cli/commands.py

@@ -0,0 +1,256 @@
+import json
+from pathlib import Path
+from getpass import getpass
+from urllib.parse import urlparse
+from natquery.config.settings import Settings
+from natquery.observability.performance_api import (
+    get_last_run,
+    compare_last_two_runs,
+    get_slowest_queries,
+)
+
+
+BASE_DIR = Path.home() / ".natquery"
+CONFIG_FILE = BASE_DIR / "config.json"
+
+
+def extract_db_name_from_dsn(dsn: str) -> str:
+    """
+    Extract database name from a PostgreSQL DSN.
+    Supports both URL format (postgresql://) and key-value format (dbname=).
+    """
+    parsed = urlparse(dsn)
+
+    if parsed.scheme:  # URL format
+        db_name = parsed.path.lstrip("/").split("?")[
+            0
+        ]  # Remove leading / and query params
+        return db_name if db_name else "unknown_db"
+
+    # Fallback: key-value DSN (e.g., "dbname=mydb user=postgres host=localhost")
+    parts = dsn.split()
+    for part in parts:
+        if part.startswith("dbname="):
+            return part.split("=", 1)[1]
+
+    return "unknown_db"
+
+
+def connect_command(dsn_arg=None):
+    """
+    Setup for NatQuery.
+    If dsn_arg is provided, extracts DB name and uses it as workspace.
+    Otherwise, runs interactive setup for standard or DSN connections.
+    """
+
+    print("============ NatQuery Setup ============")
+
+    BASE_DIR.mkdir(exist_ok=True)
+
+    # If DSN was provided as argument
+    if dsn_arg:
+        db_name = extract_db_name_from_dsn(dsn_arg)
+        workspace_name = db_name
+
+        print(f"Your Datbase Name: {db_name}")
+        print(f"Workspace Name: {workspace_name}")
+
+        config = {
+            "connection_type": "dsn",
+            "db_dsn": dsn_arg,
+            "db_name": db_name,
+            "workspace_name": workspace_name,
+        }
+
+    else:
+        db_name = input("Database Name: ").strip()
+        workspace_name = db_name
+
+        db_dir = BASE_DIR / workspace_name
+        db_dir.mkdir(parents=True, exist_ok=True)
+
+        ssl_input = input("Use SSL? (yes/no): ").strip().lower()
+        use_ssl = ssl_input in {"yes", "y"}
+
+        config = {
+            "connection_type": "standard",
+            "db_host": input("DB Host (e.g. 127.0.0.1): ").strip(),
+            "db_port": input("DB Port (e.g. 5432): ").strip(),
+            "db_name": db_name,
+            "db_user": input("DB User: ").strip(),
+            "db_password": getpass("DB Password: "),
+            "workspace_name": workspace_name,
+        }
+
+        if use_ssl:
+            config["sslmode"] = "require"
+
+    db_dir = BASE_DIR / workspace_name
+    db_dir.mkdir(parents=True, exist_ok=True)
+
+    # LLM config (common to both)
+    config.update(
+        {
+            "llm_provider": input("LLM Provider (groq): ").strip(),
+            "llm_api_key": getpass("LLM API Key: "),
+            "llm_model": input("LLM Model (e.g. llama-3.1-70b-versatile): ").strip(),
+        }
+    )
+
+    config_file = db_dir / "config.json"
+
+    with open(config_file, "w") as f:
+        json.dump(config, f, indent=2)
+
+    # Set active database
+    (BASE_DIR / "current_db").write_text(workspace_name)
+
+    print(f"\nConfiguration saved for workspace: {workspace_name}")
+    print("You can now run: natquery\n")
+
+
+def reset_command():
+    """
+    Deletes the active database configuration.
+    """
+
+    try:
+        config_path = Settings._get_config_path()
+    except RuntimeError:
+        print("No active database configured.")
+        return
+
+    if config_path.exists():
+        config_path.unlink()
+        print("Configuration removed for active database.")
+    else:
+        print("No configuration found.")
+
+
+def show_config_command():
+    """
+    Display current active DB configuration (without secrets).
+    """
+
+    try:
+        config = Settings.load_config()
+    except RuntimeError:
+        print("NatQuery not configured.")
+        print("Run: natquery connect")
+        return
+
+    safe_config = config.copy()
+
+    if "db_password" in safe_config:
+        safe_config["db_password"] = "********"
+
+    if "llm_api_key" in safe_config:
+        safe_config["llm_api_key"] = "********"
+
+    print(json.dumps(safe_config, indent=2))
+
+
+def select_database_command():
+    """
+    List all configured databases and allow user to select one as the active database.
+    Updates the current_db file without requiring reconnection.
+    """
+
+    BASE_DIR.mkdir(exist_ok=True)
+
+    # Find all database directories (those containing config.json)
+    databases = []
+
+    if BASE_DIR.exists():
+        for item in BASE_DIR.iterdir():
+            if item.is_dir() and (item / "config.json").exists():
+                databases.append(item.name)
+
+    if not databases:
+        print("No configured databases found.")
+        print("Run: natquery connect")
+        return
+
+    # Get current database
+    current_db_file = BASE_DIR / "current_db"
+    current_db = (
+        current_db_file.read_text().strip() if current_db_file.exists() else None
+    )
+
+    # Display databases
+    print("\n========== Configured Databases ==========")
+    for i, db in enumerate(databases, 1):
+        marker = " (current)" if db == current_db else ""
+        print(f"{i}. {db}{marker}")
+
+    print("\n")
+
+    # Get user selection
+    while True:
+        try:
+            selection = input("Select a database (enter number): ").strip()
+            index = int(selection) - 1
+
+            if 0 <= index < len(databases):
+                selected_db = databases[index]
+                break
+            else:
+                print(
+                    f"Invalid selection. Please enter a number between 1 and {len(databases)}."
+                )
+        except ValueError:
+            print("Invalid input. Please enter a number.")
+
+    # Update current database
+    current_db_file.write_text(selected_db)
+    print(f"\nActive database switched to: {selected_db}")
+
+
+def performance_summary_command():
+    db_name = Settings.get_db_config()["dbname"]
+
+    last = get_last_run(db_name)
+
+    if not last:
+        print("No performance data available.")
+        return
+
+    print("\n====== Performance Summary ======")
+    print(f"Execution Time: {last['execution_time_ms']} ms")
+    print(f"Total Cost: {last['total_cost']}")
+    print(f"Planning Time: {last['planning_time_ms']} ms")
+
+    print("\n--- Suggestions ---")
+    for s in last["suggestions"]:
+        print(f"- {s}")
+
+
+def performance_compare_command():
+    db_name = Settings.get_db_config()["dbname"]
+
+    comp = compare_last_two_runs(db_name)
+
+    if not comp:
+        print("Oops! Not enough data to compare.")
+        return
+
+    print("\n====== Performance Comparison ======")
+
+    print(f"Execution Time Change: {comp['execution_time_diff']} ms")
+    print(f"Cost Change: {comp['cost_diff']}")
+
+    if comp["execution_time_diff"] < 0:
+        print("Booyah! Query improved!")
+    else:
+        print("Oops! Query got slower.")
+
+
+def performance_slowest_command():
+    db_name = Settings.get_db_config()["dbname"]
+
+    slow = get_slowest_queries(db_name)
+
+    print("\n====== Slowest Queries ======")
+
+    for i, q in enumerate(slow, 1):
+        print(f"{i}. {q['execution_time_ms']} ms → {q['sql']}")