feat: add NL2SQL CLI with interactive setup wizard, diagnostic tools, and PyPI publishing workflow.

Author: nadeem4

.github/workflows/publish_pypi.yaml

@@ -0,0 +1,40 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # IMPORTANT: Mandatory for trusted publishing
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.10'
+
+    - name: Install build tools
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build Adapter SDK
+      run: python -m build packages/adapter-sdk
+
+    - name: Build Core
+      run: python -m build packages/core
+
+    - name: Build CLI
+      run: python -m build packages/cli
+
+    - name: Publish distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        packages-dir: packages/*/dist/
+        # note: 'password' is not needed with trusted publishing

README.md

@@ -30,12 +30,12 @@ Detailed documentation is available in the `docs/` directory.
 
 ### 1. Installation
 
-The platform is a monorepo. Install the core engine:
+The platform is a monorepo. Install the CLI application:
 
 ```bash
 # Core & SDK
 pip install -e packages/adapter-sdk
-pip install -e packages/core
+pip install -e packages/cli  # Installs 'nl2sql' command
 
 # Database Adapters (install as needed)
 pip install -e packages/adapters/postgres
@@ -56,13 +56,13 @@ Create a `datasources.yaml` file defining your connections:
 **a. Indexing** (Required once)
 
 ```bash
-python -m nl2sql.cli --index --config datasources.yaml
+nl2sql --index --config datasources.yaml
 ```
 
 **b. Querying**
 
 ```bash
-python -m nl2sql.cli --query "Show me the top 5 users by sales"
+nl2sql --query "Show me the top 5 users by sales"
 ```
 
 ---

docs/guides/getting_started.md

@@ -18,8 +18,7 @@ cd nl2sql
 
 # Install Core
 pip install -e packages/adapter-sdk
-pip install -e packages/adapter-sqlalchemy
-pip install -e packages/core
+pip install -e packages/cli # Installs 'nl2sql' command
 
 # Install Adapters (e.g. Postgres)
 pip install -e packages/adapters/postgres
@@ -40,15 +39,15 @@ Create a `datasources.yaml` file. This tells the system how to connect to your d
 Before the AI can understand your schema, you must index it. Additional indexing strategies are discussed in the [Configuration Guide](configuration.md).
 
 ```bash
-python -m nl2sql.cli --index --config datasources.yaml
+nl2sql --index --config datasources.yaml
 ```
 
 ## 4. Run a Query
 
 Now you are ready to ask questions!
 
 ```bash
-python -m nl2sql.cli --query "Show me the top 5 users by sales"
+nl2sql --query "Show me the top 5 users by sales"
 ```
 
 The system will:

docs/reference/cli.md

@@ -2,7 +2,7 @@
 
 The Command Line Interface (CLI) is the primary way to interact with the platform.
 
-**Command**: `python -m nl2sql.cli`
+**Command**: `nl2sql`
 
 ## Common Arguments
 

packages/cli/pyproject.toml

@@ -10,14 +10,13 @@ authors = [{name = "Antigravity Team"}]
 readme = "README.md"
 requires-python = ">=3.9"
 dependencies = [
-    "typer[all]>=0.9.0",
+    "nl2sql-core",
     "rich>=13.0.0",
-    "shellingham>=1.5.0",
-    "shellingham>=1.5.0",
+    "typer[all]>=0.9.0",
 ]
 
 [project.scripts]
-nl2sql = "nl2sql_cli.main:app"
+nl2sql = "nl2sql_cli.main:main"
 
 [tool.setuptools.packages.find]
 where = ["src"]

packages/cli/src/nl2sql_cli/__init__.py

@@ -0,0 +1,51 @@
+import importlib.util
+from typing import Dict, Tuple
+import pathlib
+from rich.table import Table
+from nl2sql_cli.console import console, print_success, print_error
+
+def check_package(name: str) -> bool:
+    """Checks if a python package is installed."""
+    import_name = name.replace("-", "_")
+    return importlib.util.find_spec(import_name) is not None
+
+def verify_connectivity(print_table: bool = True) -> bool:
+    """
+    Checks connectivity for all profiles in the default config.
+    Returns True if all checks passed, False otherwise.
+    """
+    from nl2sql.common.settings import settings
+    from nl2sql.datasources import load_profiles
+    from nl2sql.diagnostics import check_connectivity as core_check
+    
+    try:
+        profiles = load_profiles(pathlib.Path(settings.datasource_config_path))
+        
+        with console.status("[bold green]Verifying connectivity...[/bold green]"):
+            results = core_check(list(profiles.values()))
+        
+        all_ok = True
+        
+        if print_table:
+            conn_table = Table(show_header=True, header_style="bold cyan")
+            conn_table.add_column("Datasource ID")
+            conn_table.add_column("Status")
+            conn_table.add_column("Details")
+        
+        for ds_id, (success, msg) in results.items():
+            if not success:
+                all_ok = False
+            
+            if print_table:
+                status = "[green]OK[/green]" if success else "[red]Failed[/red]"
+                details = msg if not success else ""
+                conn_table.add_row(ds_id, status, details)
+        
+        if print_table:
+            console.print(conn_table)
+            
+        return all_ok
+
+    except Exception as e:
+         console.print(f"[red]Connectivity check failed: {e}[/red]")
+         return False

packages/cli/src/nl2sql_cli/checks.py

@@ -1,5 +1,4 @@
 import sys
-import argparse
 import statistics
 import yaml
 from nl2sql.services.llm import parse_llm_config, LLMRegistry, get_usage_summary
@@ -9,17 +8,18 @@
 from nl2sql.pipeline.graph import run_with_graph
 from nl2sql.evaluation.evaluator import ModelEvaluator
 from nl2sql.reporting import ConsolePresenter
+from nl2sql_cli.types import BenchmarkConfig
 
 
 def run_benchmark(
-    args: argparse.Namespace, 
+    config: BenchmarkConfig, 
     datasource_registry: DatasourceRegistry, 
     vector_store: OrchestratorVectorStore
 ) -> None:
     """Runs the benchmark suite based on provided arguments.
 
     Args:
-        args (argparse.Namespace): Command-line arguments.
+        config (BenchmarkConfig): Benchmark run configuration.
         datasource_registry (DatasourceRegistry): Datasource registry.
         vector_store (OrchestratorVectorStore): Vector store instance.
     """
@@ -28,9 +28,9 @@ def run_benchmark(
     # Matrix Benchmarking
     llm_configs = {}
 
-    if args.bench_config and args.bench_config.exists():
+    if config.bench_config_path and config.bench_config_path.exists():
         try:
-            bench_data = yaml.safe_load(args.bench_config.read_text()) or {}
+            bench_data = yaml.safe_load(config.bench_config_path.read_text()) or {}
             for name, cfg_data in bench_data.items():
                 if isinstance(cfg_data, dict):
                      llm_configs[name] = parse_llm_config(cfg_data)
@@ -40,11 +40,11 @@ def run_benchmark(
 
     if not llm_configs:
         llm_cfg = parse_llm_config({"default": {"provider": "openai", "model": "gpt-4o"}}) # Fallback
-        if args.llm_config and args.llm_config.exists():
+        if config.llm_config_path and config.llm_config_path.exists():
             from nl2sql.services.llm import load_llm_config
-            llm_cfg = load_llm_config(args.llm_config)
+            llm_cfg = load_llm_config(config.llm_config_path)
 
-        if getattr(args, "stub_llm", False):
+        if config.stub_llm:
             llm_cfg.default.provider = "stub"
             for agent_cfg in llm_cfg.agents.values():
                 agent_cfg.provider = "stub"
@@ -55,7 +55,7 @@ def run_benchmark(
     for name, llm_cfg in llm_configs.items():
         llm_registry = LLMRegistry(llm_cfg)
         _run_dataset_evaluation(
-            args, 
+            config, 
             datasource_registry, 
             vector_store, 
             llm_registry, 
@@ -64,7 +64,7 @@ def run_benchmark(
 
 
 def _run_dataset_evaluation(
-    args: argparse.Namespace, 
+    config: BenchmarkConfig, 
     datasource_registry: DatasourceRegistry, 
     vector_store: OrchestratorVectorStore,
     llm_registry: LLMRegistry,
@@ -73,7 +73,7 @@ def _run_dataset_evaluation(
     """Runs evaluation against a golden dataset for a specific config.
 
     Args:
-        args (argparse.Namespace): CLI arguments.
+        config (BenchmarkConfig): CLI arguments.
         datasource_registry (DatasourceRegistry): Registry of datasources.
         vector_store (OrchestratorVectorStore): Vector store.
         llm_registry (LLMRegistry): LLM registry.
@@ -84,7 +84,7 @@ def _run_dataset_evaluation(
 
     presenter = ConsolePresenter()
 
-    dataset_path = args.dataset
+    dataset_path = config.dataset_path
     if not dataset_path.exists():
         presenter.print_error(f"Dataset file not found: {dataset_path}")
         sys.exit(1)
@@ -99,10 +99,10 @@ def _run_dataset_evaluation(
         presenter.print_error("Dataset must be a list of test cases.")
         sys.exit(1)
 
-    if args.include_ids:
-        dataset = [item for item in dataset if item.get("id") in args.include_ids]
+    if config.include_ids:
+        dataset = [item for item in dataset if item.get("id") in config.include_ids]
         if not dataset:
-            presenter.print_error(f"No test cases found matching IDs: {args.include_ids}")
+            presenter.print_error(f"No test cases found matching IDs: {config.include_ids}")
             sys.exit(1)
 
     presenter.print_header(f"Evaluating Config: {config_name}")
@@ -122,9 +122,9 @@ def _evaluate_case(item: dict) -> dict:
                 llm_registry=llm_registry,
                 user_query=question,
                 datasource_id=None, 
-                execute=not args.routing_only,
+                execute=not config.routing_only,
                 vector_store=vector_store,
-                vector_store_path=args.vector_store
+                vector_store_path=config.vector_store_path
             )
         except Exception as e:
             return {
@@ -181,7 +181,7 @@ def get_val(obj, key, default=None):
 
         layer_match = (routing_layer == expected_layer)
 
-        if args.routing_only:
+        if config.routing_only:
             return {
                 "id": q_id,
                 "question": question,
@@ -329,7 +329,7 @@ def get_val(obj, key, default=None):
 
     import concurrent.futures
     workers = 5 
-    iterations = args.iterations if args.iterations else 1
+    iterations = config.iterations if config.iterations else 1
 
     with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
         futures = []
@@ -345,11 +345,11 @@ def get_val(obj, key, default=None):
     results.sort(key=lambda x: x["id"])
 
     # Delegate Reporting
-    presenter.print_dataset_benchmark_results(results, iterations=iterations, routing_only=args.routing_only)
+    presenter.print_dataset_benchmark_results(results, iterations=iterations, routing_only=config.routing_only)
 
     # Calculate Metrics and Print Summary
     metrics = ModelEvaluator.calculate_aggregate_metrics(results, len(results))
-    presenter.print_metrics_summary(metrics, results, routing_only=args.routing_only)
+    presenter.print_metrics_summary(metrics, results, routing_only=config.routing_only)
 
-    if args.export_path:
-        presenter.export_results(results, args.export_path)
+    if config.export_path:
+        presenter.export_results(results, config.export_path)