AI NL2SQL

SKILL.md

# NL2SQL · Natural Language to SQL

> Upload CSV/Excel files → Ask questions in plain English → AI generates and executes SQL → Returns readable results + optional charts

---

## Trigger Phrases

`nl2sql` `text to sql` `natural language sql` `ask database` `csv query` `excel sql` `数据查询` `自然语言查数`

---

## Usage

### Command Line

```bash
# Basic query
python -m scripts.main "Which product has the highest sales?" -f data/sales.csv

# Generate chart
python -m scripts.main "Monthly sales trend" -f data/sales.csv --chart line

# Export results
python -m scripts.main "Top 10 customers" -f data/customers.csv --format csv -o result.csv
```

### Python API

```python
from scripts import NL2SQLService, QueryRequest

service = NL2SQLService(api_key="your-api-key")

request = QueryRequest(
    question="Which product has the highest sales?",
    files=["data/sales.csv"],
    chart_type="bar",
    explain=True
)

response = service.query(request)

if response.success:
    print(f"SQL: {response.sql}")
    print(f"Results: {response.data}")
```

---

## Parameters

### QueryRequest

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| question | str | Yes | Natural language question |
| files | List[str] | Yes | File paths (CSV/Excel) |
| chart_type | str | No | Chart type: bar/line/pie/scatter/area/histogram |
| explain | bool | No | Whether to explain the SQL |
| output_format | str | No | Output format: markdown/json/csv (default: markdown) |

### QueryResponse

| Field | Type | Description |
|-------|------|-------------|
| success | bool | Whether the query succeeded |
| sql | str | Generated SQL |
| explanation | str | SQL explanation |
| row_count | int | Number of result rows |
| columns | List[str] | Column names |
| data | List[dict] | Result data |
| chart_base64 | str | Chart image as base64 |
| error | str | Error message if failed |

---

## Supported Formats

| Format | Extensions | Notes |
|--------|-----------|-------|
| CSV | `.csv` | UTF-8/GBK auto-detected |
| Excel | `.xlsx`, `.xls` | Multi-sheet supported |

---

## Tech Stack

- **Parsing**: pandas, openpyxl
- **AI**: OpenAI GPT-4 (via user-provided API key)
- **Charts**: matplotlib
- **Execution**: pandasql (SQL on DataFrame, fully offline sandbox)

---

## Tiered Features

| Feature | FREE | PRO |
|---------|------|-----|
| Queries | 3 per session | Unlimited |
| File size | 5 MB max | 200 MB max |
| JOIN support | No | Yes |
| Chart types | bar, line, pie | All types |
| Export formats | CSV | CSV, Excel, PDF |
| AI SQL generation | No (rule-based) | Yes (GPT-4) |

---

## Billing

**$0.01 USDT per call** — billed via SkillPay at [https://skillpay.me/ai-nl2sql](https://skillpay.me/ai-nl2sql)

> **Privacy Note:** Your Feishu User ID (Open ID) may be transmitted to skillpay.me for billing purposes only.

| Price | $0 (FREE tier) | $0.01 / call (PRO tier) |

> For paid use, visit [https://skillpay.me/ai-nl2sql](https://skillpay.me/ai-nl2sql)

---

## Required Environment Variables

| Variable | Description |
|----------|-------------|
| `SKILL_BILLING_API_KEY` | SkillPay Builder API Key (from skillpay.me) |
| `SKILL_BILLING_SKILL_ID` | Skill ID on SkillPay (default: ai-nl2sql) |

---

## API Key Format

Any non-empty string works as an API key. The tier is determined automatically:
- **No API key** → FREE tier (rule-based SQL only)
- **Any API key** → PRO tier (GPT-4 powered)

---

## Slug

`ai-nl2sql`

---

## Security Notes

- **SQL Safety**: All AI-generated SQL passes through an SQLValidator that blocks all non-SELECT queries (DROP, DELETE, INSERT, UPDATE, CREATE, EXEC, GRANT, etc.). Only read-only queries are permitted.
- **Data Isolation**: SQL execution runs entirely in a local pandas DataFrame sandbox. No real database connection is made. No data leaves the user's environment.
- **External Data Transmission**: Your Feishu User ID (Open ID) is transmitted to [skillpay.me](https://skillpay.me) exclusively for billing purposes. See [## Billing](#billing) for details.

---

## Notes

1. All SQL execution runs in a local pandas DataFrame sandbox — no real database connection
2. AI SQL generation requires a valid OpenAI API key provided by the user
3. Network errors gracefully degrade to FREE tier