Merge pull request #20 from nadeem4/feature/demo-env-setup

Feature/demo env setup

Author: nadeem4

.gitignore

@@ -22,3 +22,7 @@ chroma_db
 logs
 
 site
+
+data
+
+last_reasoning.json

README.md

@@ -27,7 +27,21 @@ Detailed documentation is available in the `docs/` directory.
 
 ---
 
-## 🚀 Quick Start
+## 🚀 Try it Now (Demo)
+
+The fastest way to experience the platform is the interactive demo. This sets up a "Manufacturing" environment with 4 SQLite databases and sample data.
+
+```bash
+# 1. Setup Demo Environment
+nl2sql setup --demo
+
+# 2. Run a Query
+nl2sql --env demo run "Show me broken machines in Austin"
+```
+
+---
+
+## 🛠️ Installation & Setup
 
 ### 1. Installation
 
@@ -42,15 +56,15 @@ pip install -e packages/cli  # Installs 'nl2sql' command
 # pip install -e packages/adapters/postgres
 ```
 
-### 2. Setup
+### 2. Setup (Production)
 
-Run the interactive wizard to configure your database and LLM:
+Run the interactive wizard to configure your own database connections (Postgres, MySQL, etc.) and LLM:
 
 ```bash
 nl2sql setup
 ```
 
-*This will create your configuration files and index your schema.*
+*This will inspect your schema and index it into the vector store.*
 
 ### 3. Usage
 
@@ -60,11 +74,13 @@ nl2sql setup
 nl2sql run "Show me the top 5 users by sales"
 ```
 
-**Other Commands**
+**Common Commands**
 
-* `nl2sql doctor` - Diagnose environment issues.
+* `nl2sql index` - Re-index schemas and examples.
 * `nl2sql list-adapters` - Show installed database adapters.
-* `nl2sql benchmark` - Run evaluation suite.
+* `nl2sql doctor` - Diagnose environment issues.
+
+> See [**CLI Reference**](docs/guides/cli_reference.md) for full documentation on flags like `--env` and `--role`.
 
 ---
 

configs/datasources.demo.yaml

@@ -0,0 +1,21 @@
+datasources:
+- id: manufacturing_ref
+  connection:
+    type: sqlite
+    database: data\demo_lite\manufacturing_ref.db
+  description: Master Data (Factories)
+- id: manufacturing_ops
+  connection:
+    type: sqlite
+    database: data\demo_lite\manufacturing_ops.db
+  description: Operational Data (Employees, Machines)
+- id: manufacturing_supply
+  connection:
+    type: sqlite
+    database: data\demo_lite\manufacturing_supply.db
+  description: Supply Chain (Inventory)
+- id: manufacturing_history
+  connection:
+    type: sqlite
+    database: data\demo_lite\manufacturing_history.db
+  description: Historical Data (Sales)

configs/policies.demo.json

@@ -0,0 +1,12 @@
+{
+  "admin": {
+    "description": "Demo Admin",
+    "role": "admin",
+    "allowed_datasources": [
+      "*"
+    ],
+    "allowed_tables": [
+      "*"
+    ]
+  }
+}

configs/sample_questions.demo.yaml

@@ -0,0 +1,22 @@
+manufacturing_ref:
+- List all factories in the US
+- Show me the capacity of Berlin Plant
+- What shifts are available?
+- List all machine types produced by TechCorp
+manufacturing_ops:
+- Show me active employees in the Austin Gigafactory
+- Which machines have error logs in the last 7 days?
+- Who is the operator for machine 5?
+- Count the number of active machines per factory
+- List maintenance logs for Vibration sensor alerts
+manufacturing_supply:
+- Total sales amount for 'Industrial Controller'
+- Find suppliers for high value components
+- Check inventory levels for 'Bolt M5' in Berlin
+- List products with base cost greater than 500
+- Show me suppliers from Germany
+manufacturing_history:
+- Show total sales orders in Q4
+- Calculate average production output per run
+- Summarize sales by customer for last year
+- List the top 5 largest orders

docs/guides/cli_reference.md

@@ -0,0 +1,117 @@
+# CLI Reference
+
+The `nl2sql` Command Line Interface (CLI) is the primary way to interact with the platform.
+
+## Global Options
+
+These flags apply to all commands and must be specified **before** the subcommand.
+
+* `--env`, `-e TEXT`: Environment name (e.g. `dev`, `demo`, `prod`). Isolates configurations and vector stores. Defaults to `default` (Production).
+
+Example:
+
+```bash
+# Uses configs/datasources.yaml
+nl2sql run "query"
+
+# Uses configs/datasources.demo.yaml
+nl2sql --env demo run "query"
+```
+
+## Commands
+
+### `setup`
+
+Interactive wizard to initialize the platform.
+
+```bash
+nl2sql setup [OPTIONS]
+```
+
+**Options:**
+
+* `--demo`: **Quickstart Mode**. Automatically generates a "Manufacturing" demo environment with 4 SQLite databases and sample questions.
+* `--docker`: Used with `--demo` to generate a `docker-compose.yml` for full-fidelity testing (Postgres/MySQL) instead of SQLite.
+
+### Example: Try it Now
+
+```bash
+nl2sql setup --demo
+```
+
+### `index`
+
+Indexes database schemas and examples into the vector store for retrieval.
+
+```bash
+nl2sql index [OPTIONS]
+```
+
+**Features:**
+
+* **Schema Indexing**: Introspects tables, columns, foreign keys, and comments.
+* **Example Indexing**: Indexes sample questions for few-shot routing.
+* **Granular Feedback**: Displays a checklist of indexed items per datasource.
+* **Summary Table**: Shows total tables, columns, and examples indexed.
+
+**Options:**
+
+* `--config PATH`: Path to datasource config.
+* `--vector-store PATH`: Path to vector store directory.
+
+**Example:**
+
+```bash
+nl2sql --env demo index
+```
+
+### `run`
+
+Executes a natural language query against the configured datasources.
+
+```bash
+nl2sql run [QUERY] [OPTIONS]
+```
+
+**Arguments:**
+
+* `QUERY`: The natural language question (e.g. "Show me active users").
+
+**Options:**
+
+* `--role TEXT`: The RBAC role to assume (e.g. `admin`, `analyst`). Defaults to `admin`.
+* `--no-exec`: Plan and Validate only, do not execute SQL.
+* `--verbose`, `-v`: Show detailed reasoning traces and intermediate node outputs.
+* `--show-perf`: Display timing metrics.
+
+**Example:**
+
+```bash
+nl2sql run "Who bought the Bolt M5?" --role sales_analyst --verbose
+```
+
+### `policy`
+
+Manage RBAC policies.
+
+* `validate`: Validates syntax and integrity of `policies.json`.
+
+```bash
+nl2sql policy validate
+```
+
+### `doctor`
+
+Diagnoses environment issues (Python version, missing adapters, connectivity).
+
+```bash
+nl2sql doctor
+```
+
+### `benchmark`
+
+Runs the evaluation suite against a "Golden Dataset".
+
+```bash
+nl2sql benchmark --dataset configs/benchmark.yaml
+```

docs/guides/getting_started.md

@@ -52,3 +52,10 @@ The system will:
 2. Route it to the correct database.
 3. Generate and Validate SQL.
 4. Execute and display the results.
+
+## Next Steps
+
+Explore the full capabilities of the CLI:
+
+* [CLI Reference](cli_reference.md) - Learn about `--env`, `--role`, and `index` options.
+* [Configuration](configuration.md) - Connect to your own databases.