AI NL2SQL

Convert natural language questions into SQL queries on your uploaded CSV/Excel files, execute them offline, and return results with optional charts.

Security Scan

The skill generally implements offline NL→SQL over CSV/Excel and charting, but there are inconsistencies around declared environment requirements, billing behaviour, and telemetry claims that merit caution before installing.

Purpose & Capability

The code implements the stated purpose (local parsing, rule-based fallback, optional OpenAI GPT-4 generation, pandasql execution, and charting). However registry metadata claims no required env vars or credentials while SKILL.md and code expect SKILL_BILLING_API_KEY/SKILL_BILLING_SKILL_ID for billing and the code accepts a user-provided OpenAI API key for AI generation — the omission in the registry metadata is an inconsistency.

Instruction Scope

Runtime instructions (SKILL.md) map to the provided CLI/API usage and the code. The skill runs locally on user-supplied files and uses pandas/pandasql for offline execution. The only network calls in the runtime are to skillpay.me for billing and to OpenAI if you provide an API key. SKILL.md mentions a Feishu user ID may be transmitted for billing, but the code uses fixed user_id strings ('api_user' / 'cli_user') when calling charge_user — another mismatch to be aware of.

Install Mechanism

There is no install spec (instruction-only install) and the repository contains only Python source and a requirements list; no external archives or obscure download URLs are used. Dependencies are standard PyPI packages listed in requirements.txt.

Credentials

The code reads SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID from the environment and will send the API key as X-API-Key to https://skillpay.me. The registry metadata declares no required env vars which is inconsistent with SKILL.md and the code. The OpenAI API key is not read from a fixed env var in the service (it is passed in as an argument), but the skill will use any provided non-empty key and treat it as 'PRO' without server-side validation — this design can lead to surprising billing or external API use. No unrelated secrets (AWS, etc.) are requested.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system settings, and does not install persistent system services. It performs network calls only when billing or AI generation is invoked.

What to consider before installing

This skill largely does what it says: it converts questions to SQL (rule-based if no OpenAI key), runs queries on user-supplied CSV/Excel files locally, and can generate charts. Key things to consider before installing or running it: - Registry metadata vs SKILL.md mismatch: the skill bundle metadata lists no required environment variables but the SKILL.md and code use SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID for billing. Treat the billing API key as sensitive — it will be sent to https://skillpay.me as X-API-Key. - Billing behaviour: when a billing API key is present the code will call skillpay.me to charge per call. In 'dev' or empty key mode the code skips charging. Verify that you trust skillpay.me before providing a real billing key. - OpenAI usage: AI-powered SQL/explanation uses the OpenAI API key you supply (via CLI arg or by passing into the API). The code treats any non-empty key as 'PRO' without remote token validation — you will be billed by OpenAI if you provide a real key. Prefer passing a scoped/test key first. - Telemetry/identity claims: SKILL.md says your Feishu user ID 'may' be transmitted for billing, but the implemented code sends static user IDs ('api_user'/'cli_user') to the billing endpoint. If you expect real user-identifying data to be transmitted, ask the author for clarification. - If you want to evaluate safely: run in a controlled environment (no real billing key, dev/test billing mode), inspect network traffic or run with network disabled to confirm local-only behavior, and review or run the code locally rather than granting system-wide permissions. If you will provide keys, limit them (test keys) and confirm the trustworthiness/policies of skillpay.me.

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

# 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

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

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

---

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

---

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