{"id":"325e09b3-bbf6-476c-8565-47b2bf55f5d4","entityType":"agent","slug":"clawhub-asksqlai-text2sql","name":"TEXT2SQL","canonicalUrl":"https://www.xpersona.co/agent/clawhub-asksqlai-text2sql","canonicalPath":"/agent/clawhub-asksqlai-text2sql","generatedAt":"2026-10-11T17:41:12.642Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":null},"description":"Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s1746eaqxx1yw5mkstegd982cn84fhj5:text2sql","sourceUrl":"https://clawhub.ai/asksqlai/text2sql","homepage":"https://clawhub.ai/asksqlai/skills/text2sql","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/asksqlai/text2sql","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/asksqlai/skills/text2sql","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":40,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"TEXT2SQL technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":null},"stars":null,"forks":null,"downloads":1045,"packageName":null,"latestVersion":"1.0.2","tractionLabel":"1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T14:58:39.517Z","lastCrawledAt":"2026-10-11T14:58:39.517Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T14:58:39.517Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.2","createdAt":"2026-07-07T22:30:46.663Z","changelog":"- Updated default SQL API service endpoint to https://asksql.ai/ - Removed file: skill-card.md - No other functional or dependency changes included in this version","fileCount":8,"zipByteSize":22712},{"version":"1.0.1","createdAt":"2026-05-07T06:19:20.494Z","changelog":"- Documentation updated for clarity; no code or functionality changes included. - SKILL.md content was reformatted and reorganized without any modifications to dependencies or logic. - Version bump to 1.0.1 with no file changes detected.","fileCount":8,"zipByteSize":21783},{"version":"1.0.0","createdAt":"2026-04-08T01:26:26.445Z","changelog":"text-to-sql 1.0.0 Changelog - Initial release of the Text-to-SQL skill supporting SQL query generation from natural language. - Enables multi-topic database configuration and table structure management. - Offers two data configuration methods: via direct database connection (recommended) or Excel schema files. - Integrates with external API for SQL generation from natural language questions. - Provides clear user guidance for configuration and querying processes. - Requires Python dependencies: pyyaml (>=6.0) and sqlalchemy (>=2.0.0).","fileCount":7,"zipByteSize":20563}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1746eaqxx1yw5mkstegd982cn84fhj5:text2sql","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s1746eaqxx1yw5mkstegd982cn84fhj5:text2sql` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/asksqlai/text2sql before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T17:41:12.637Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-asksqlai-text2sql/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":null},"readme":"Skill: TEXT2SQL\n\nOwner: asksqlai\n\nSummary: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions\n\nTags: latest:1.0.2\n\nVersion history:\n\nv1.0.2 | 2026-07-07T22:30:46.663Z | user\n\n- Updated default SQL API service endpoint to https://asksql.ai/\n- Removed file: skill-card.md\n- No other functional or dependency changes included in this version\n\nv1.0.1 | 2026-05-07T06:19:20.494Z | user\n\n- Documentation updated for clarity; no code or functionality changes included.\n- SKILL.md content was reformatted and reorganized without any modifications to dependencies or logic.\n- Version bump to 1.0.1 with no file changes detected.\n\nv1.0.0 | 2026-04-08T01:26:26.445Z | user\n\ntext-to-sql 1.0.0 Changelog\n\n- Initial release of the Text-to-SQL skill supporting SQL query generation from natural language.\n- Enables multi-topic database configuration and table structure management.\n- Offers two data configuration methods: via direct database connection (recommended) or Excel schema files.\n- Integrates with external API for SQL generation from natural language questions.\n- Provides clear user guidance for configuration and querying processes.\n- Requires Python dependencies: pyyaml (>=6.0) and sqlalchemy (>=2.0.0).\n\nArchive index:\n\nArchive v1.0.2: 8 files, 22712 bytes\n\nFiles: references/open_semantic_interchange_description.md (10569b), scripts/config_db.py (2396b), scripts/generate_yaml.py (9554b), scripts/query_sql.py (6567b), scripts/read_tables.py (28553b), skill-card.md (2479b), SKILL.md (20480b), _meta.json (127b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: text-to-sql\ndescription: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions\ndependency:\n python:\n - pyyaml>=6.0\n - sqlalchemy>=2.0.0\n---\n\n# Text-to-SQL Intelligent Query Skill\n\n## Task Objectives\n\n- This Skill is used for: Generating SQL query statements through natural language, supporting multi-topic database configuration and table structure management\n- Capabilities include: Database configuration, topic management, table structure reading, natural language to SQL\n- Trigger conditions: User needs to configure Text-to-SQL database, create data topics, select data tables, or generate SQL with natural language questions\n\n## Prerequisites\n\n### Dependency Description\n\nRequired packages and versions for scripts:\n\n```\npyyaml>=6.0\nsqlalchemy>=2.0.0\n```\n\n### API Service Description\n\nThis Skill generates SQL through the HTTP API `/api/sql_for_skill/` endpoint:\n\n- Default API address: `https://asksql.ai/`\n- Service needs to be started before calling\n- Supports custom API address (via `--api-url` parameter)\n\n**API Interface Specification**:\n\n- Endpoint path: `POST /api/sql_for_skill/`\n- Request format: `multipart/form-data`\n- Request parameters:\n - `question`: User's natural language question (string)\n - `yaml_file`: YAML configuration file (uploaded as file)\n- Response format: JSON array\n- Response example:\n ```json\n [\n {\n \"STATUS\": \"ok\",\n \"MESSAGE\": \"\",\n \"SQL\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"SQL_NO_PERM\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"QUESTION\": \"This year's total sales\"\n }\n ]\n ```\n- Return value: Extract the `SQL` field from the first element of the response array\n\n## Data Configuration Methods\n\n### Two Configuration Methods Explained\n\nWhen the agent guides users through data configuration, it must clearly explain the following two methods:\n\n**Method 1: Database URL Configuration (Highly Recommended)**\n- Read table structure directly through database connection\n- Real-time data synchronization, ensuring accuracy\n- Supports complete database semantic understanding\n\n**Method 2: Excel File Configuration**\n- Suitable for scenarios where direct database connection is not possible\n- Configure through Excel file with specific format requirements\n\n**Excel File Format (Must Strictly Follow):**\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Excel File: products.xlsx │\n├─────────────────────────────────────────────────────────────────┤\n│ Sheet: orders (Sheet name = Table name) │\n├──────────┬──────────┬────────────┬───────────┬─────────────────┤\n│ order_id │ customer │ order_date │ amount │ status │\n│ (Column) │ (Column) │ (Column) │ (Column) │ (Column) │\n├──────────┼──────────┼────────────┼───────────┼─────────────────┤\n│ 1001 │ John │ 2024-01-15 │ 1500.00 │ completed │\n│ 1002 │ Mary │ 2024-01-16 │ 2300.50 │ pending │\n│ ... │ ... │ ... │ ... │ ... │\n└──────────┴──────────┴────────────┴───────────┴─────────────────┘\n ↑ First row = Column names (field names)\n ↑ Data starts from second row\n```\n\n**Format Requirements:**\n1. **File naming**: Excel filename must match database name (e.g., `products.xlsx` for `products` database)\n2. **Sheet naming**: Each sheet name must exactly match the table name (e.g., `orders` sheet for `orders` table)\n3. **First row**: Must contain column names (field names), cannot be empty\n4. **Second row onwards**: Actual data rows (optional, used for understanding data types)\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.** Only use the Excel file method when users cannot provide a database connection.\n\n### Method 1: Database URL Configuration\n\n#### Configuration Steps\n\n1. Guide the user to provide database connection information\n2. Call the configuration script to save database information:\n\n```bash\npython scripts/config_db.py --db-url --db-password --config-file ./output/text-to-sql-config.json\n```\n\nThis script saves the configuration to `./output/text-to-sql-config.json` file.\n\n#### Database URL Format\n\n```\ndatabase_type://username:password@host:port/database_name\n```\n\nExamples:\n- MySQL: `mysql://root:password@localhost:3306/mydb` (will auto-convert to use pymysql driver)\n- MySQL with explicit driver: `mysql+pymysql://root:password@localhost:3306/mydb`\n- SQL Server: `mssql://sa:password@localhost:1433/mydb`\n\n**Note**: For MySQL connections, the system automatically converts `mysql://` to `mysql+pymysql://` for better compatibility. You can also explicitly specify the driver.\n\n#### Reading Table Structure\n\nAfter configuration, use the following command to read table structure:\n\n```bash\npython scripts/read_tables.py --config-file ./output/text-to-sql-config.json\n```\n\n### Method 2: Excel File Configuration\n\n#### Applicable Scenarios\n\nWhen users cannot provide a database connection, the Excel file method can be used for configuration.\n\n#### Configuration Steps\n\n1. Guide the user to provide the Excel file path\n2. Remind user to follow the Excel file format requirements described above\n3. After the user provides the file, **no parsing operation is needed**, directly call the `read_tables.py` script:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\nExample:\n```bash\npython scripts/read_tables.py --excel-file data_file.xlsx\n```\n\n- Parameter description:\n - `--excel-file`: Complete path to the Excel file\n\n## Operation Steps\n\n### Step 0: Configuration Check (Must Execute on First Call)\n\n**Important: The agent must check the configuration status before performing any operation**\n\nThe agent needs to check whether yaml configuration files exist in the `./output/` directory:\n\n**Check Method**:\n\n```bash\n# Check if .yaml files exist in ./output/ directory\nls ./output/*.yaml 2>/dev/null\n```\n\n**Check Result Handling**:\n\n**Scenario A: yaml configuration files exist**\n\n- Indicates user has completed configuration in advance\n- Agent skips all configuration steps (Step 1 and Step 2)\n- Proceed directly to Step 3 (Query with natural language)\n- Agent informs user: \"Detected existing topic configuration, you can ask questions directly.\"\n- List configured topic names for user reference\n\n**Scenario B: No yaml configuration files**\n\n- Indicates user has not completed configuration\n- Agent proceeds to execute Step 1 (Database Configuration) and Step 2 (Topic Setup)\n- Guide user through the standard configuration process\n\n### Standard Configuration Process\n\n#### Step 1: Database Configuration\n\n**The agent must clearly explain the two configuration methods:**\n\n1. **Method 1: Database URL Configuration (Highly Recommended)**\n - Read table structure directly through database connection\n - Real-time data synchronization, ensuring accuracy\n - Supports complete database semantic understanding\n\n2. **Method 2: Excel File Configuration**\n - Suitable for scenarios where direct database connection is not possible\n - Configure through Excel file schema description\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.**\n\n**If user chooses database URL configuration:**\nGuide user to provide database URL and password, save to local configuration file:\n\n```bash\npython scripts/config_db.py --db-url --db-password \n```\n\nThis script saves the configuration to `text-to-sql-config.json` file.\n\n**If user chooses Excel file configuration:**\n1. Guide user to provide Excel file path\n2. Remind user to follow the **Excel File Format** requirements described in the \"Two Configuration Methods Explained\" section above\n3. After user provides file, **no parsing operation needed**, directly call:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\n#### Step 2: Topic Setup\n\n**Important: The agent must mandatorily guide users to set up topics, table selection step cannot be skipped**\n\nThe agent should guide users through the following process:\n\n**2.1 Clearly inform user that topic setup is mandatory**\n\n- Agent clearly states: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n- Explain benefits of setting up topics: more accurate SQL generation, faster query speed, better business semantic understanding\n\n**2.2 Execute topic setup process**\n\n- Agent must guide user to create topics and select tables, **table selection step cannot be skipped**\n- Multiple topics can be created\n- Execution steps:\n 1. Call script to read all table structures and generate knowledge\n ```bash\n # Method 1: Use database connection (recommended)\n python scripts/read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output\n\n # Method 2: Use Excel file\n python scripts/read_tables.py --excel-file data_file.xlsx\n ```\n This script generates `table_info.json` (table name list) and `column_info.json` (table structure information) files.\n 2. **Agent reads table list from** **`table_info.json`** **file, displays all tables to user completely**, provides clear table descriptions\n 3. **Key emphasis: Table selection is a critical step in topic creation, directly affects SQL generation accuracy and query effectiveness, must be autonomously selected by user based on actual business needs**\n 4. Ask user: \"Please tell me the topic name you want to create (e.g., sales topic, human resources topic)\"\n 5. **Agent is strictly prohibited from selecting tables for topics itself**, must require user to explicitly specify needed tables\n 6. Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n 7. Generate topic configuration file\n ```bash\n python scripts/generate_yaml.py --topic-name --tables --output-path ./output/\n ```\n 8. Ask user: \"Do you want to continue creating other topics?\"\n 9. User can repeat to create multiple topics (no need to re-read table structure, use existing `./output/column_info.json` directly)\n\n**2.3 Agent Guidance Recommendations**\n\n- **Agent is prohibited from making assumptions or guessing user intent**\n- Agent must mandatorily guide user to set up topics, cannot allow skipping\n- **Agent is strictly prohibited from setting topics or selecting tables for topics itself**, must display all table lists to user after reading table structure, let user completely autonomously select relevant tables based on actual business needs\n- Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n- **Key emphasis: Table selection step cannot be skipped, this is a key link to ensure topic configuration accuracy**\n- **Prioritize recommending database connection method to users**, only use Excel file method when user cannot provide database connection\n\n#### Step 3: Query with Natural Language (Includes Topic Selection Logic)\n\n**Important: Step 3 can be executed directly (when Step 0 detects existing configuration)**\n\nAfter configuration is complete (or when existing configuration is detected), users can ask questions in natural language, the agent needs to select topic and generate SQL according to the following logic:\n\n##### 3.1 Topic Selection Logic\n\n**Scenario: One or more topics exist (user has completed topic setup)**\n\n**Case A: User question explicitly mentions topic**\n\n- Agent identifies topic keywords in user question (e.g., \"sales\", \"human resources\", \"inventory\", etc.)\n- Matches corresponding `.yaml` file in `./output/` directory\n- If match is successful, directly use that yaml file to call script\n- If match fails, prompt user that topic does not exist and list available topics\n\n**Case B: User question does not explicitly mention topic**\n\n- Agent analyzes question content, selects most relevant topic from all topics\n- Agent informs user: \"Based on your question, I suggest using [topic name] topic, continue?\"\n- If user confirms, use that topic; if user declines, list all topics for user to select\n\n##### 3.2 Call SQL Generation Script\n\nAfter determining topic, call API to generate SQL:\n\n```bash\npython scripts/query_sql.py --api-url https://asksql.ai/ --question \"user question\" --config ./output/.yaml\n```\n\nThe script calls the API's `/api/sql_for_skill/` endpoint and returns the generated SQL statement.\n\n### Optional Branches\n\n- When user wants to modify topic configuration: Re-call `generate_yaml.py` to overwrite original configuration file\n- When user wants to reconfigure database: Re-call `config_db.py` to overwrite configuration file\n- When user wants to view configured topics: Agent lists yaml files in `./output/` directory\n- When user question is ambiguous and cannot determine topic: Agent actively asks user or lists all topics for selection\n- When API service is not at default address: Use `--api-url` parameter to specify custom API address\n\n## Resource Index\n\n### Required Scripts\n\n- [scripts/config_db.py](scripts/config_db.py) - Save database configuration to local file\n- [scripts/read_tables.py](scripts/read_tables.py) - Read database table structure (supports both database connection and Excel file methods)\n- [scripts/generate_yaml.py](scripts/generate_yaml.py) - Generate topic configuration file (supports all parameter)\n- [scripts/query_sql.py](scripts/query_sql.py) - Generate SQL by calling generate_sql API endpoint\n\n### Output Files\n\nAll generated files are stored in `./output/` directory:\n- `table_info.json` - Table name list\n- `column_info.json` - Table structure information\n- `.yaml` - Topic configuration files\n- [references/open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) - YAML file format specification and field definitions (refer to this document when users ask about YAML format, field meanings, or configuration details)\n\n## Notes\n\n- All scripts are pure functional tools without interaction logic, all inputs are passed through parameters\n- Database URL and password are saved in local configuration file `./output/text-to-sql-config.json`\n- Topic configuration files are stored in yaml format for easy version management and viewing\n- Only `query_sql.py` calls API, other scripts are all executed locally\n- If database connection fails, check if URL and password are correct\n- If API service connection fails, check if service is started and address is correct\n- **Prioritize database connection method**, only use Excel file method when database connection cannot be provided\n- **When users ask about YAML file format, field definitions, or configuration details**, refer to the [open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) document which contains complete specification of the semantic model YAML structure\n\n## Usage Examples\n\n### Example 0: Detected Existing Configuration (Direct Query)\n\n1. User: \"Query last month's total sales\"\n2. Agent: Check ./output/ directory\n3. Agent: Detect existing topic configuration files\n4. Agent: \"Detected existing topic configuration, you can ask questions directly.\"\n5. Agent: Identify topic relevant to the question, use corresponding topic configuration file\n6. Agent: Call query_sql.py to generate SQL\n\n### Example 1: Intelligently Guide User to Set Up Topic (Recommended Process)\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create a topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"No need\"\n16. User: \"Query the top 10 products with highest sales last month\"\n17. Agent: Identify topic relevant to the question, use corresponding topic configuration file to call query_sql.py to generate SQL\n\n### Example 2: Configure with Excel File\n\n1. User: \"Help me configure Text-to-SQL, but I don't have a database\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Okay, you can use the Excel file method for configuration. Please provide an Excel file with format requirements: each sheet corresponds to a table name, first row is column names\"\n5. User: \"Provide Excel file path\"\n6. Agent: Call read_tables.py --excel-file data_file.xlsx to read Excel data\n7. Agent: \"Topic setup is a mandatory step...\"\n8. Follow same process as Example 1\n\n### Example 3: Set Up Multiple Topics\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file text-to-sql-config.json to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create first topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"Create another topic\"\n16. Agent: \"Please select tables to include in this topic from the database tables\"\n17. User: \"Select relevant tables\"\n18. Agent: Call generate_yaml.py to generate topic configuration file\n19. Agent: \"Do you want to continue creating other topics?\"\n20. User: \"No need\"\n21. User: \"Query average salary of technical department\"\n22. Agent: Identify topic relevant to the question, determine most relevant topic\n23. Agent: \"Based on your question, I suggest using relevant topic, continue?\"\n24. User: \"Yes\"\n25. Agent: Call query_sql.py using corresponding topic configuration file to generate SQL\n\n### Example 4: User Explicitly Specifies Topic\n\n1. User configured multiple topics\n2. User: \"Use a specific topic to query total orders in 2024\"\n3. Agent: Check ./output/ directory (existing configuration)\n4. Agent: Identify topic explicitly specified by user, directly use corresponding topic configuration file\n5. Agent: Call query_sql.py to generate SQL\n\n### Example 5: Custom API Address\n\n1. User: \"My Text-to-SQL service is deployed at http://127.0.1.100:8080\"\n2. Agent: All query_sql.py calls use --api-url http://127.0.1.101:8080 parameter\n3. User: \"Query sales data\"\n4. Agent: Call query_sql.py --api-url http://127.0.1.101:8080 --config using corresponding topic configuration file to generate SQL\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn74572dhgzsd1yb43y0xdvcd584e5ht\",\n \"slug\": \"text2sql\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1783463446663\n}\n\nFile v1.0.2:references/open_semantic_interchange_description.md\n\n# Open Semantic Interchange (OSI) - Field Specification\n\n## 1. Introduction\n\nThis document provides a comprehensive field specification for the Open Semantic Interchange (OSI) YAML configuration file. The semantic model defines the structure for domain-specific data queries and analysis across various business contexts.\n\nThe YAML file serves as a metadata layer that enables AI-powered query generation and data interpretation for structured datasets.\n\n## 2. Document Structure\n\nThis specification is organized hierarchically to mirror the YAML file structure:\n\n- **Top-Level Fields**: Global configuration fields\n- **Semantic Model**: Theme-level definitions\n- **Datasets**: Individual data source definitions\n- **Fields**: Detailed field specifications within each dataset\n\n## 3. Top-Level Fields\n\n### 3.1 `yaml-language-server`\n\n**Data Type**: Comment directive\n\n**Description**: Specifies the JSON schema path for YAML language server validation and IDE auto-completion support.\n\n**Format**: `$schema=`\n\n**Constraints**: Must reference a valid schema file path relative to the YAML file location.\n\n---\n\n### 3.2 `version`\n\n**Data Type**: String\n\n**Description**: Defines the semantic model version number using semantic versioning convention.\n\n**Format**: `MAJOR.MINOR.PATCH`\n\n**Constraints**: \n- Must follow semantic versioning format\n- Each component must be a non-negative integer\n\n**Default Value**: `0.0.1`\n\n---\n\n### 3.3 `semantic_model`\n\n**Data Type**: Object\n\n**Description**: The semantic model definition. In the current generator implementation, this file contains exactly one semantic model object.\n\n**Required Sub-fields**:\n- `name`\n- `description`\n- `ai_context`\n- `datasets`\n- `relationships`\n- `metrics`\n- `terms`\n- `rules`\n\n---\n\n## 4. Semantic Model Object\n\n### 4.1 `name`\n\n**Data Type**: String\n\n**Description**: The theme name that identifies the semantic model's thematic classification.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be unique within the system\n\n---\n\n### 4.2 `description`\n\n**Data Type**: String\n\n**Description**: A brief description explaining the semantic model's purpose and scope.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the theme's domain\n\n---\n\n### 4.3 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration containing instruction information for AI processing.\n\n#### 4.3.1 `instructions`\n\n**Data Type**: String\n\n**Description**: AI processing instructions that guide the AI on how to utilize this semantic model for data queries and analysis.\n\n**Constraints**: \n- Must be a non-empty string\n- Should provide clear guidance on the model's usage\n\n---\n\n### 4.4 `datasets`\n\n**Data Type**: Array of objects\n\n**Description**: List of datasets, where each dataset corresponds to a database table or view.\n\n**Required Sub-fields** (for each dataset):\n- `name`\n- `source`\n- `description`\n- `ai_context`\n- `fields`\n\n---\n\n### 4.5 `relationships`\n\n**Data Type**: Array of objects\n\n**Description**: Relationship definitions derived from foreign keys (table-to-table joins).\n\n**Default Value**: `[]`\n\n**Required Sub-fields** (for each relationship):\n- `name`\n- `from_table`\n- `to_table`\n- `from_columns`\n- `to_columns`\n\n---\n\n### 4.6 `metrics`\n\n**Data Type**: Array of objects\n\n**Description**: Reserved for metric definitions (not populated by the current generator, but present in the output schema).\n\n**Default Value**: `[]`\n\n---\n\n### 4.7 `terms`\n\n**Data Type**: Array of objects\n\n**Description**: Reserved for terminology definitions (not populated by the current generator, but present in the output schema).\n\n**Default Value**: `[]`\n\n---\n\n### 4.8 `rules`\n\n**Data Type**: Array of objects\n\n**Description**: Reserved for rule definitions (not populated by the current generator, but present in the output schema).\n\n**Default Value**: `[]`\n\n---\n\n## 5. Dataset Object\n\n### 5.1 `name`\n\n**Data Type**: String\n\n**Description**: Dataset identifier that should correspond to the database table name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must be unique within the semantic model\n- Should match the actual database table name\n\n---\n\n### 5.2 `source`\n\n**Data Type**: String\n\n**Description**: Complete data source path specifying the database and table location.\n\n**Format**: `database_name.table_name`\n\n**Constraints**: \n- Must follow the format `.
`\n- Both database and table names must be valid identifiers\n\n---\n\n### 5.3 `description`\n\n**Data Type**: String\n\n**Description**: Dataset description explaining the dataset's purpose or content.\n\n**Constraints**: \n- Must be a non-empty string\n- Should briefly describe what the dataset contains\n\n---\n\n### 5.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration for the dataset.\n\n#### 5.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized name for the dataset, used for natural language query processing.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be consistent with the dataset name or description\n\n---\n\n#### 5.4.2 `weight`\n\n**Data Type**: Integer\n\n**Description**: Dataset weight for ranking/recall bias during matching. Higher value means the dataset is more likely to be selected.\n\n**Default Value**: `3`\n\n---\n\n#### 5.4.3 `synonyms`\n\n**Data Type**: Array of strings\n\n**Description**: Alternative dataset names used for matching.\n\n**Default Value**: `[]`\n\n---\n\n#### 5.4.4 `default_datetime_field`\n\n**Data Type**: String\n\n**Description**: The default time field name for the dataset, selected by the generator by scoring date/time columns. This replaces the need for a field-level `is_default` flag in the current YAML output.\n\n**Default Value**: `` (empty string)\n\n**Constraints**:\n- If provided, it should match one of the dataset `fields[*].name`\n\n---\n\n### 5.5 `fields`\n\n**Data Type**: Array of objects\n\n**Description**: List of field definitions for the dataset. Each field represents a column in the database table.\n\n---\n\n## 6. Field Object\n\n### 6.1 `name`\n\n**Data Type**: String\n\n**Description**: Field identifier that must match the database column name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must exactly match the database column name\n- Must be unique within the dataset\n\n---\n\n### 6.2 `type`\n\n**Data Type**: String\n\n**Description**: Field data type that determines query methods and presentation format.\n\n**Allowed Values**:\n\n| Value | Description | Usage |\n|-------|-------------|-------|\n| `TEXT` | Text/string data | Names, codes, descriptions |\n| `NUMBER` | Numeric data | Counts, measurements, amounts |\n| `DATE` | Date data | Date-only values |\n| `TIME` | Time/date-time data | Timestamps, datetime |\n| `ID` | Identifier | UUID/GUID-like identifiers |\n| `OTHER` | Other types | Fallback when type is not recognized |\n\n**Constraints**: \n- Must be one of the allowed values\n- Must match the actual database column data type\n\n---\n\n### 6.3 `description`\n\n**Data Type**: String\n\n**Description**: Human-readable field description used for UI display and documentation.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the field's meaning\n- Typically written in the local language for the target domain\n\n---\n\n### 6.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: Field-level AI context configuration containing metadata for AI processing.\n\n**Common Sub-fields**:\n- `ai_name`\n- `property`\n- `ai_type` (optional)\n- `value_list` (optional, for enum)\n\n#### 6.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized field name, typically identical to the `description` field.\n\n**Constraints**: \n- Must be a non-empty string\n- Should match or be similar to the `description` value\n\n---\n\n#### 6.4.2 `property`\n\n**Data Type**: String\n\n**Description**: Field property type that indicates special field attributes.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `normal` | Normal field | Standard data fields |\n| `dimension` | Dimension field | Used for grouping/filtering, e.g. date/time dimensions or enum dimensions |\n| `detail_only` | Detail query only | Fields displayed only in detail queries, not used in aggregations |\n\n**Default Value**: `normal`\n\n**Constraints**: \n- Must be one of the allowed values\n\n---\n\n#### 6.4.3 `ai_type`\n\n**Data Type**: String\n\n**Description**: AI field type indicator for special processing requirements.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `date` | Date type | Reserved for date-specific processing (not always emitted by the current generator) |\n| `enum` | Enumeration type | Fields with fixed allowable values (emitted when enum is detected) |\n\n**Default Value**: `` (empty string)\n\n**Constraints**: \n- Must be one of the allowed values\n- If `enum`, then `value_list` must be provided\n\n---\n\n#### 6.4.4 `value_list`\n\n**Data Type**: Array of scalars (strings and/or numbers)\n\n**Description**: List of allowable values for enumeration-type fields.\n\n**Usage**: \n- Required when `ai_type` is `enum`\n- Should be omitted or empty for non-enumeration fields\n\n**Constraints**: \n- Must be an array (can be empty)\n- For enumeration fields, must contain all valid values (as extracted from samples / metadata)\n\n---\n\n## 7. Relationship Object\n\nRelationship entries live under `semantic_model.relationships`.\n\n### 7.1 `name`\n\n**Data Type**: String\n\n**Description**: Human-readable relationship name. The generator uses the form ` to `.\n\n---\n\n### 7.2 `from_table`\n\n**Data Type**: String\n\n**Description**: Source table for the relationship.\n\n---\n\n### 7.3 `to_table`\n\n**Data Type**: String\n\n**Description**: Target table for the relationship.\n\n---\n\n### 7.4 `from_columns`\n\n**Data Type**: Array of strings\n\n**Description**: Column list on `from_table` participating in the join.\n\n---\n\n### 7.5 `to_columns`\n\n**Data Type**: Array of strings\n\n**Description**: Column list on `to_table` participating in the join. It should align positionally with `from_columns`.\n\n---\n\n## 8. Numeric Format (`num_format`) Object\n\n`num_format` is an optional object on a field, emitted when the generator detects unit/level/decimal hints.\n\n### 8.1 `unit`\n\n**Data Type**: String\n\n**Description**: Display unit hint (e.g. 元, 万, %, etc.).\n\n---\n\n### 8.2 `num_level`\n\n**Data Type**: String\n\n**Description**: Numeric magnitude/level hint (e.g. 千/万/亿) used for formatting.\n\n---\n\n### 8.3 `num_decimal`\n\n**Data Type**: String or Integer\n\n**Description**: Decimal precision hint for formatting.\n\nFile v1.0.2:skill-card.md\n\n## Description:\n\nSupport generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[asksqlai](https://clawhub.ai/user/asksqlai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and data teams use TEXT2SQL to configure database or Excel-backed semantic topics, inspect table structures, generate topic YAML files, and request SQL from natural-language questions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can collect and upload database metadata, table samples, topic YAML, questions, or spreadsheet data to asksql.ai.\n\nMitigation: Use a least-privilege read-only database account, avoid confidential spreadsheets unless remote processing is accepted, and inspect or restrict what is sent to the remote service.\n\nRisk: Database passwords may be passed on the command line and saved in a local configuration file.\n\nMitigation: Use temporary or scoped credentials, protect the output directory, and rotate credentials after use when handling sensitive environments.\n\nRisk: Generated SQL may be incorrect for the intended business question or unsafe to run without review.\n\nMitigation: Review generated SQL before execution and run it first against non-production data or with read-only permissions.\n\n## Reference(s):\n\n- [Open Semantic Interchange field specification](references/open_semantic_interchange_description.md)\n- [AskSqlAI SQL API service](https://asksql.ai/)\n- [TEXT2SQL ClawHub release](https://clawhub.ai/asksqlai/skills/text2sql)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, JSON status output, YAML configuration files, and SQL text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes local output files for database configuration, table metadata, column metadata, and topic YAML; generated SQL is returned when the remote API call succeeds.]\n\n## Skill Version(s):\n\n1.0.2 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.1: 8 files, 21783 bytes\n\nFiles: references/open_semantic_interchange_description.md (7749b), scripts/config_db.py (2396b), scripts/generate_yaml.py (9584b), scripts/query_sql.py (6585b), scripts/read_tables.py (28399b), skill-card.md (2333b), SKILL.md (20498b), _meta.json (127b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: text-to-sql\ndescription: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions\ndependency:\n python:\n - pyyaml>=6.0\n - sqlalchemy>=2.0.0\n---\n\n# Text-to-SQL Intelligent Query Skill\n\n## Task Objectives\n\n- This Skill is used for: Generating SQL query statements through natural language, supporting multi-topic database configuration and table structure management\n- Capabilities include: Database configuration, topic management, table structure reading, natural language to SQL\n- Trigger conditions: User needs to configure Text-to-SQL database, create data topics, select data tables, or generate SQL with natural language questions\n\n## Prerequisites\n\n### Dependency Description\n\nRequired packages and versions for scripts:\n\n```\npyyaml>=6.0\nsqlalchemy>=2.0.0\n```\n\n### API Service Description\n\nThis Skill generates SQL through the HTTP API `/api/sql_for_skill/` endpoint:\n\n- Default API address: `https://asksql.ucap.com.cn/`\n- Service needs to be started before calling\n- Supports custom API address (via `--api-url` parameter)\n\n**API Interface Specification**:\n\n- Endpoint path: `POST /api/sql_for_skill/`\n- Request format: `multipart/form-data`\n- Request parameters:\n - `question`: User's natural language question (string)\n - `yaml_file`: YAML configuration file (uploaded as file)\n- Response format: JSON array\n- Response example:\n ```json\n [\n {\n \"STATUS\": \"ok\",\n \"MESSAGE\": \"\",\n \"SQL\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"SQL_NO_PERM\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"QUESTION\": \"This year's total sales\"\n }\n ]\n ```\n- Return value: Extract the `SQL` field from the first element of the response array\n\n## Data Configuration Methods\n\n### Two Configuration Methods Explained\n\nWhen the agent guides users through data configuration, it must clearly explain the following two methods:\n\n**Method 1: Database URL Configuration (Highly Recommended)**\n- Read table structure directly through database connection\n- Real-time data synchronization, ensuring accuracy\n- Supports complete database semantic understanding\n\n**Method 2: Excel File Configuration**\n- Suitable for scenarios where direct database connection is not possible\n- Configure through Excel file with specific format requirements\n\n**Excel File Format (Must Strictly Follow):**\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Excel File: products.xlsx │\n├─────────────────────────────────────────────────────────────────┤\n│ Sheet: orders (Sheet name = Table name) │\n├──────────┬──────────┬────────────┬───────────┬─────────────────┤\n│ order_id │ customer │ order_date │ amount │ status │\n│ (Column) │ (Column) │ (Column) │ (Column) │ (Column) │\n├──────────┼──────────┼────────────┼───────────┼─────────────────┤\n│ 1001 │ John │ 2024-01-15 │ 1500.00 │ completed │\n│ 1002 │ Mary │ 2024-01-16 │ 2300.50 │ pending │\n│ ... │ ... │ ... │ ... │ ... │\n└──────────┴──────────┴────────────┴───────────┴─────────────────┘\n ↑ First row = Column names (field names)\n ↑ Data starts from second row\n```\n\n**Format Requirements:**\n1. **File naming**: Excel filename must match database name (e.g., `products.xlsx` for `products` database)\n2. **Sheet naming**: Each sheet name must exactly match the table name (e.g., `orders` sheet for `orders` table)\n3. **First row**: Must contain column names (field names), cannot be empty\n4. **Second row onwards**: Actual data rows (optional, used for understanding data types)\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.** Only use the Excel file method when users cannot provide a database connection.\n\n### Method 1: Database URL Configuration\n\n#### Configuration Steps\n\n1. Guide the user to provide database connection information\n2. Call the configuration script to save database information:\n\n```bash\npython scripts/config_db.py --db-url --db-password --config-file ./output/text-to-sql-config.json\n```\n\nThis script saves the configuration to `./output/text-to-sql-config.json` file.\n\n#### Database URL Format\n\n```\ndatabase_type://username:password@host:port/database_name\n```\n\nExamples:\n- MySQL: `mysql://root:password@localhost:3306/mydb` (will auto-convert to use pymysql driver)\n- MySQL with explicit driver: `mysql+pymysql://root:password@localhost:3306/mydb`\n- SQL Server: `mssql://sa:password@localhost:1433/mydb`\n\n**Note**: For MySQL connections, the system automatically converts `mysql://` to `mysql+pymysql://` for better compatibility. You can also explicitly specify the driver.\n\n#### Reading Table Structure\n\nAfter configuration, use the following command to read table structure:\n\n```bash\npython scripts/read_tables.py --config-file ./output/text-to-sql-config.json\n```\n\n### Method 2: Excel File Configuration\n\n#### Applicable Scenarios\n\nWhen users cannot provide a database connection, the Excel file method can be used for configuration.\n\n#### Configuration Steps\n\n1. Guide the user to provide the Excel file path\n2. Remind user to follow the Excel file format requirements described above\n3. After the user provides the file, **no parsing operation is needed**, directly call the `read_tables.py` script:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\nExample:\n```bash\npython scripts/read_tables.py --excel-file data_file.xlsx\n```\n\n- Parameter description:\n - `--excel-file`: Complete path to the Excel file\n\n## Operation Steps\n\n### Step 0: Configuration Check (Must Execute on First Call)\n\n**Important: The agent must check the configuration status before performing any operation**\n\nThe agent needs to check whether yaml configuration files exist in the `./output/` directory:\n\n**Check Method**:\n\n```bash\n# Check if .yaml files exist in ./output/ directory\nls ./output/*.yaml 2>/dev/null\n```\n\n**Check Result Handling**:\n\n**Scenario A: yaml configuration files exist**\n\n- Indicates user has completed configuration in advance\n- Agent skips all configuration steps (Step 1 and Step 2)\n- Proceed directly to Step 3 (Query with natural language)\n- Agent informs user: \"Detected existing topic configuration, you can ask questions directly.\"\n- List configured topic names for user reference\n\n**Scenario B: No yaml configuration files**\n\n- Indicates user has not completed configuration\n- Agent proceeds to execute Step 1 (Database Configuration) and Step 2 (Topic Setup)\n- Guide user through the standard configuration process\n\n### Standard Configuration Process\n\n#### Step 1: Database Configuration\n\n**The agent must clearly explain the two configuration methods:**\n\n1. **Method 1: Database URL Configuration (Highly Recommended)**\n - Read table structure directly through database connection\n - Real-time data synchronization, ensuring accuracy\n - Supports complete database semantic understanding\n\n2. **Method 2: Excel File Configuration**\n - Suitable for scenarios where direct database connection is not possible\n - Configure through Excel file schema description\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.**\n\n**If user chooses database URL configuration:**\nGuide user to provide database URL and password, save to local configuration file:\n\n```bash\npython scripts/config_db.py --db-url --db-password \n```\n\nThis script saves the configuration to `text-to-sql-config.json` file.\n\n**If user chooses Excel file configuration:**\n1. Guide user to provide Excel file path\n2. Remind user to follow the **Excel File Format** requirements described in the \"Two Configuration Methods Explained\" section above\n3. After user provides file, **no parsing operation needed**, directly call:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\n#### Step 2: Topic Setup\n\n**Important: The agent must mandatorily guide users to set up topics, table selection step cannot be skipped**\n\nThe agent should guide users through the following process:\n\n**2.1 Clearly inform user that topic setup is mandatory**\n\n- Agent clearly states: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n- Explain benefits of setting up topics: more accurate SQL generation, faster query speed, better business semantic understanding\n\n**2.2 Execute topic setup process**\n\n- Agent must guide user to create topics and select tables, **table selection step cannot be skipped**\n- Multiple topics can be created\n- Execution steps:\n 1. Call script to read all table structures and generate knowledge\n ```bash\n # Method 1: Use database connection (recommended)\n python scripts/read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output\n\n # Method 2: Use Excel file\n python scripts/read_tables.py --excel-file data_file.xlsx\n ```\n This script generates `table_info.json` (table name list) and `column_info.json` (table structure information) files.\n 2. **Agent reads table list from** **`table_info.json`** **file, displays all tables to user completely**, provides clear table descriptions\n 3. **Key emphasis: Table selection is a critical step in topic creation, directly affects SQL generation accuracy and query effectiveness, must be autonomously selected by user based on actual business needs**\n 4. Ask user: \"Please tell me the topic name you want to create (e.g., sales topic, human resources topic)\"\n 5. **Agent is strictly prohibited from selecting tables for topics itself**, must require user to explicitly specify needed tables\n 6. Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n 7. Generate topic configuration file\n ```bash\n python scripts/generate_yaml.py --topic-name --tables
--output-path ./output/\n ```\n 8. Ask user: \"Do you want to continue creating other topics?\"\n 9. User can repeat to create multiple topics (no need to re-read table structure, use existing `./output/column_info.json` directly)\n\n**2.3 Agent Guidance Recommendations**\n\n- **Agent is prohibited from making assumptions or guessing user intent**\n- Agent must mandatorily guide user to set up topics, cannot allow skipping\n- **Agent is strictly prohibited from setting topics or selecting tables for topics itself**, must display all table lists to user after reading table structure, let user completely autonomously select relevant tables based on actual business needs\n- Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n- **Key emphasis: Table selection step cannot be skipped, this is a key link to ensure topic configuration accuracy**\n- **Prioritize recommending database connection method to users**, only use Excel file method when user cannot provide database connection\n\n#### Step 3: Query with Natural Language (Includes Topic Selection Logic)\n\n**Important: Step 3 can be executed directly (when Step 0 detects existing configuration)**\n\nAfter configuration is complete (or when existing configuration is detected), users can ask questions in natural language, the agent needs to select topic and generate SQL according to the following logic:\n\n##### 3.1 Topic Selection Logic\n\n**Scenario: One or more topics exist (user has completed topic setup)**\n\n**Case A: User question explicitly mentions topic**\n\n- Agent identifies topic keywords in user question (e.g., \"sales\", \"human resources\", \"inventory\", etc.)\n- Matches corresponding `.yaml` file in `./output/` directory\n- If match is successful, directly use that yaml file to call script\n- If match fails, prompt user that topic does not exist and list available topics\n\n**Case B: User question does not explicitly mention topic**\n\n- Agent analyzes question content, selects most relevant topic from all topics\n- Agent informs user: \"Based on your question, I suggest using [topic name] topic, continue?\"\n- If user confirms, use that topic; if user declines, list all topics for user to select\n\n##### 3.2 Call SQL Generation Script\n\nAfter determining topic, call API to generate SQL:\n\n```bash\npython scripts/query_sql.py --api-url https://asksql.ucap.com.cn/ --question \"user question\" --config ./output/.yaml\n```\n\nThe script calls the API's `/api/sql_for_skill/` endpoint and returns the generated SQL statement.\n\n### Optional Branches\n\n- When user wants to modify topic configuration: Re-call `generate_yaml.py` to overwrite original configuration file\n- When user wants to reconfigure database: Re-call `config_db.py` to overwrite configuration file\n- When user wants to view configured topics: Agent lists yaml files in `./output/` directory\n- When user question is ambiguous and cannot determine topic: Agent actively asks user or lists all topics for selection\n- When API service is not at default address: Use `--api-url` parameter to specify custom API address\n\n## Resource Index\n\n### Required Scripts\n\n- [scripts/config_db.py](scripts/config_db.py) - Save database configuration to local file\n- [scripts/read_tables.py](scripts/read_tables.py) - Read database table structure (supports both database connection and Excel file methods)\n- [scripts/generate_yaml.py](scripts/generate_yaml.py) - Generate topic configuration file (supports all parameter)\n- [scripts/query_sql.py](scripts/query_sql.py) - Generate SQL by calling generate_sql API endpoint\n\n### Output Files\n\nAll generated files are stored in `./output/` directory:\n- `table_info.json` - Table name list\n- `column_info.json` - Table structure information\n- `.yaml` - Topic configuration files\n- [references/open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) - YAML file format specification and field definitions (refer to this document when users ask about YAML format, field meanings, or configuration details)\n\n## Notes\n\n- All scripts are pure functional tools without interaction logic, all inputs are passed through parameters\n- Database URL and password are saved in local configuration file `./output/text-to-sql-config.json`\n- Topic configuration files are stored in yaml format for easy version management and viewing\n- Only `query_sql.py` calls API, other scripts are all executed locally\n- If database connection fails, check if URL and password are correct\n- If API service connection fails, check if service is started and address is correct\n- **Prioritize database connection method**, only use Excel file method when database connection cannot be provided\n- **When users ask about YAML file format, field definitions, or configuration details**, refer to the [open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) document which contains complete specification of the semantic model YAML structure\n\n## Usage Examples\n\n### Example 0: Detected Existing Configuration (Direct Query)\n\n1. User: \"Query last month's total sales\"\n2. Agent: Check ./output/ directory\n3. Agent: Detect existing topic configuration files\n4. Agent: \"Detected existing topic configuration, you can ask questions directly.\"\n5. Agent: Identify topic relevant to the question, use corresponding topic configuration file\n6. Agent: Call query_sql.py to generate SQL\n\n### Example 1: Intelligently Guide User to Set Up Topic (Recommended Process)\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create a topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"No need\"\n16. User: \"Query the top 10 products with highest sales last month\"\n17. Agent: Identify topic relevant to the question, use corresponding topic configuration file to call query_sql.py to generate SQL\n\n### Example 2: Configure with Excel File\n\n1. User: \"Help me configure Text-to-SQL, but I don't have a database\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Okay, you can use the Excel file method for configuration. Please provide an Excel file with format requirements: each sheet corresponds to a table name, first row is column names\"\n5. User: \"Provide Excel file path\"\n6. Agent: Call read_tables.py --excel-file data_file.xlsx to read Excel data\n7. Agent: \"Topic setup is a mandatory step...\"\n8. Follow same process as Example 1\n\n### Example 3: Set Up Multiple Topics\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file text-to-sql-config.json to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create first topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"Create another topic\"\n16. Agent: \"Please select tables to include in this topic from the database tables\"\n17. User: \"Select relevant tables\"\n18. Agent: Call generate_yaml.py to generate topic configuration file\n19. Agent: \"Do you want to continue creating other topics?\"\n20. User: \"No need\"\n21. User: \"Query average salary of technical department\"\n22. Agent: Identify topic relevant to the question, determine most relevant topic\n23. Agent: \"Based on your question, I suggest using relevant topic, continue?\"\n24. User: \"Yes\"\n25. Agent: Call query_sql.py using corresponding topic configuration file to generate SQL\n\n### Example 4: User Explicitly Specifies Topic\n\n1. User configured multiple topics\n2. User: \"Use a specific topic to query total orders in 2024\"\n3. Agent: Check ./output/ directory (existing configuration)\n4. Agent: Identify topic explicitly specified by user, directly use corresponding topic configuration file\n5. Agent: Call query_sql.py to generate SQL\n\n### Example 5: Custom API Address\n\n1. User: \"My Text-to-SQL service is deployed at http://127.0.1.100:8080\"\n2. Agent: All query_sql.py calls use --api-url http://127.0.1.101:8080 parameter\n3. User: \"Query sales data\"\n4. Agent: Call query_sql.py --api-url http://127.0.1.101:8080 --config using corresponding topic configuration file to generate SQL\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn74572dhgzsd1yb43y0xdvcd584e5ht\",\n \"slug\": \"text2sql\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1778134760494\n}\n\nFile v1.0.1:references/open_semantic_interchange_description.md\n\n# Open Semantic Interchange (OSI) - Field Specification\n\n## 1. Introduction\n\nThis document provides a comprehensive field specification for the Open Semantic Interchange (OSI) YAML configuration file. The semantic model defines the structure for domain-specific data queries and analysis across various business contexts.\n\nThe YAML file serves as a metadata layer that enables AI-powered query generation and data interpretation for structured datasets.\n\n## 2. Document Structure\n\nThis specification is organized hierarchically to mirror the YAML file structure:\n\n- **Top-Level Fields**: Global configuration fields\n- **Semantic Model**: Theme-level definitions\n- **Datasets**: Individual data source definitions\n- **Fields**: Detailed field specifications within each dataset\n\n## 3. Top-Level Fields\n\n### 3.1 `yaml-language-server`\n\n**Data Type**: Comment directive\n\n**Description**: Specifies the JSON schema path for YAML language server validation and IDE auto-completion support.\n\n**Format**: `$schema=`\n\n**Constraints**: Must reference a valid schema file path relative to the YAML file location.\n\n---\n\n### 3.2 `version`\n\n**Data Type**: String\n\n**Description**: Defines the semantic model version number using semantic versioning convention.\n\n**Format**: `MAJOR.MINOR.PATCH`\n\n**Constraints**: \n- Must follow semantic versioning format\n- Each component must be a non-negative integer\n\n**Default Value**: `0.0.1`\n\n---\n\n### 3.3 `semantic_model`\n\n**Data Type**: Array of objects\n\n**Description**: Contains one or more theme definitions. Each theme represents a logical grouping of related datasets.\n\n**Required Sub-fields**:\n- `name`\n- `description`\n- `ai_context`\n- `datasets`\n\n---\n\n## 4. Semantic Model Object\n\n### 4.1 `name`\n\n**Data Type**: String\n\n**Description**: The theme name that identifies the semantic model's thematic classification.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be unique within the system\n\n---\n\n### 4.2 `description`\n\n**Data Type**: String\n\n**Description**: A brief description explaining the semantic model's purpose and scope.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the theme's domain\n\n---\n\n### 4.3 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration containing instruction information for AI processing.\n\n#### 4.3.1 `instructions`\n\n**Data Type**: String\n\n**Description**: AI processing instructions that guide the AI on how to utilize this semantic model for data queries and analysis.\n\n**Constraints**: \n- Must be a non-empty string\n- Should provide clear guidance on the model's usage\n\n---\n\n### 4.4 `datasets`\n\n**Data Type**: Array of objects\n\n**Description**: List of datasets, where each dataset corresponds to a database table or view.\n\n**Required Sub-fields** (for each dataset):\n- `name`\n- `source`\n- `description`\n- `ai_context`\n- `fields`\n\n---\n\n## 5. Dataset Object\n\n### 5.1 `name`\n\n**Data Type**: String\n\n**Description**: Dataset identifier that should correspond to the database table name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must be unique within the semantic model\n- Should match the actual database table name\n\n---\n\n### 5.2 `source`\n\n**Data Type**: String\n\n**Description**: Complete data source path specifying the database and table location.\n\n**Format**: `database_name.table_name`\n\n**Constraints**: \n- Must follow the format `.
`\n- Both database and table names must be valid identifiers\n\n---\n\n### 5.3 `description`\n\n**Data Type**: String\n\n**Description**: Dataset description explaining the dataset's purpose or content.\n\n**Constraints**: \n- Must be a non-empty string\n- Should briefly describe what the dataset contains\n\n---\n\n### 5.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration for the dataset.\n\n#### 5.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized name for the dataset, used for natural language query processing.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be consistent with the dataset name or description\n\n---\n\n### 5.5 `fields`\n\n**Data Type**: Array of objects\n\n**Description**: List of field definitions for the dataset. Each field represents a column in the database table.\n\n---\n\n## 6. Field Object\n\n### 6.1 `name`\n\n**Data Type**: String\n\n**Description**: Field identifier that must match the database column name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must exactly match the database column name\n- Must be unique within the dataset\n\n---\n\n### 6.2 `type`\n\n**Data Type**: String\n\n**Description**: Field data type that determines query methods and presentation format.\n\n**Allowed Values**:\n\n| Value | Description | Usage |\n|-------|-------------|-------|\n| `text` | Text/string data | Names, codes, descriptions |\n| `number` | Numeric data | Counts, measurements, amounts |\n| `date` | Date/time data | Timestamps, dates |\n\n**Constraints**: \n- Must be one of the allowed values\n- Must match the actual database column data type\n\n---\n\n### 6.3 `description`\n\n**Data Type**: String\n\n**Description**: Human-readable field description used for UI display and documentation.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the field's meaning\n- Typically written in the local language for the target domain\n\n---\n\n### 6.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: Field-level AI context configuration containing metadata for AI processing.\n\n**Required Sub-fields**:\n- `ai_name`\n- `property`\n- `ai_type`\n- `value_list`\n- `is_default`\n\n#### 6.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized field name, typically identical to the `description` field.\n\n**Constraints**: \n- Must be a non-empty string\n- Should match or be similar to the `description` value\n\n---\n\n#### 6.4.2 `property`\n\n**Data Type**: String\n\n**Description**: Field property type that indicates special field attributes.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `normal` | Normal field | Standard data fields |\n| `date` | Date field | Time-related fields used for filtering/grouping |\n| `detail_only` | Detail query only | Fields displayed only in detail queries, not used in aggregations |\n\n**Default Value**: `normal`\n\n**Constraints**: \n- Must be one of the allowed values\n\n---\n\n#### 6.4.3 `ai_type`\n\n**Data Type**: String\n\n**Description**: AI field type indicator for special processing requirements.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `date` | Date type | Fields requiring date-specific processing |\n| `enum` | Enumeration type | Fields with fixed allowable values |\n\n**Default Value**: `` (empty string)\n\n**Constraints**: \n- Must be one of the allowed values\n- If `enum`, then `value_list` must be provided\n\n---\n\n#### 6.4.4 `value_list`\n\n**Data Type**: Array of strings\n\n**Description**: List of allowable values for enumeration-type fields.\n\n**Usage**: \n- Required when `ai_type` is `enum`\n- Must be empty array `[]` for non-enumeration fields\n\n**Constraints**: \n- Must be an array (can be empty)\n- Each element must be a string\n- For enumeration fields, must contain all valid values\n\n---\n\n#### 6.4.5 `is_default`\n\n**Data Type**: Boolean\n\n**Description**: Indicates whether this field serves as the default time dimension for the dataset.\n\n**Allowed Values**:\n\n| Value | Description |\n|-------|-------------|\n| `true` | Serves as the primary time dimension for default time range filtering |\n| `false` | Not used as default time dimension |\n\n**Default Value**: `false`\n\n**Constraints**: \n- Must be a boolean value\n- Each dataset should have exactly one field with `is_default: true` (typically a date field)\n\nFile v1.0.1:skill-card.md\n\n## Description:
\nSupports generating SQL queries from natural language after configuring database or spreadsheet schema context and topic-specific YAML files.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[asksqlai](https://clawhub.ai/user/asksqlai)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, data teams, and agent users use this skill to configure database or Excel-backed semantic context, create topic YAML files, and request SQL from natural-language questions.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Database schema details, sampled values or enum lists, natural-language questions, YAML topic files, and Excel workbook contents may be sent to the configured API provider.
\nMitigation: Use least-privilege read-only database access, avoid regulated or production data, and install only when that data handling is acceptable.
\nRisk: Database credentials can be written to a local configuration file.
\nMitigation: Protect generated output files, remove plaintext credentials when no longer needed, and rotate credentials after use when appropriate.
\nRisk: Generated SQL can be incorrect, incomplete, or too broad for the user's intent.
\nMitigation: Review generated SQL before execution and test against non-production data or read-only environments first.
\n\n\n## Reference(s):
\n- [Open Semantic Interchange field specification](references/open_semantic_interchange_description.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Guidance, Shell commands, Configuration, JSON, YAML, SQL]
\n**Output Format:** [Markdown guidance with shell commands, JSON status files, YAML topic files, and SQL text]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Creates local output files for database configuration, table metadata, column metadata, and topic-specific semantic YAML.]
\n\n## Skill Version(s):
\n1.0.1 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.0: 7 files, 20563 bytes\n\nFiles: references/open_semantic_interchange_description.md (7749b), scripts/config_db.py (2396b), scripts/generate_yaml.py (9589b), scripts/query_sql.py (6585b), scripts/read_tables.py (28399b), SKILL.md (20498b), _meta.json (127b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: text-to-sql\ndescription: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions\ndependency:\n python:\n - pyyaml>=6.0\n - sqlalchemy>=2.0.0\n---\n\n# Text-to-SQL Intelligent Query Skill\n\n## Task Objectives\n\n- This Skill is used for: Generating SQL query statements through natural language, supporting multi-topic database configuration and table structure management\n- Capabilities include: Database configuration, topic management, table structure reading, natural language to SQL\n- Trigger conditions: User needs to configure Text-to-SQL database, create data topics, select data tables, or generate SQL with natural language questions\n\n## Prerequisites\n\n### Dependency Description\n\nRequired packages and versions for scripts:\n\n```\npyyaml>=6.0\nsqlalchemy>=2.0.0\n```\n\n### API Service Description\n\nThis Skill generates SQL through the HTTP API `/api/sql_for_skill/` endpoint:\n\n- Default API address: `https://asksql.ucap.com.cn/`\n- Service needs to be started before calling\n- Supports custom API address (via `--api-url` parameter)\n\n**API Interface Specification**:\n\n- Endpoint path: `POST /api/sql_for_skill/`\n- Request format: `multipart/form-data`\n- Request parameters:\n - `question`: User's natural language question (string)\n - `yaml_file`: YAML configuration file (uploaded as file)\n- Response format: JSON array\n- Response example:\n ```json\n [\n {\n \"STATUS\": \"ok\",\n \"MESSAGE\": \"\",\n \"SQL\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"SQL_NO_PERM\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"QUESTION\": \"This year's total sales\"\n }\n ]\n ```\n- Return value: Extract the `SQL` field from the first element of the response array\n\n## Data Configuration Methods\n\n### Two Configuration Methods Explained\n\nWhen the agent guides users through data configuration, it must clearly explain the following two methods:\n\n**Method 1: Database URL Configuration (Highly Recommended)**\n- Read table structure directly through database connection\n- Real-time data synchronization, ensuring accuracy\n- Supports complete database semantic understanding\n\n**Method 2: Excel File Configuration**\n- Suitable for scenarios where direct database connection is not possible\n- Configure through Excel file with specific format requirements\n\n**Excel File Format (Must Strictly Follow):**\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Excel File: products.xlsx │\n├─────────────────────────────────────────────────────────────────┤\n│ Sheet: orders (Sheet name = Table name) │\n├──────────┬──────────┬────────────┬───────────┬─────────────────┤\n│ order_id │ customer │ order_date │ amount │ status │\n│ (Column) │ (Column) │ (Column) │ (Column) │ (Column) │\n├──────────┼──────────┼────────────┼───────────┼─────────────────┤\n│ 1001 │ John │ 2024-01-15 │ 1500.00 │ completed │\n│ 1002 │ Mary │ 2024-01-16 │ 2300.50 │ pending │\n│ ... │ ... │ ... │ ... │ ... │\n└──────────┴──────────┴────────────┴───────────┴─────────────────┘\n ↑ First row = Column names (field names)\n ↑ Data starts from second row\n```\n\n**Format Requirements:**\n1. **File naming**: Excel filename must match database name (e.g., `products.xlsx` for `products` database)\n2. **Sheet naming**: Each sheet name must exactly match the table name (e.g., `orders` sheet for `orders` table)\n3. **First row**: Must contain column names (field names), cannot be empty\n4. **Second row onwards**: Actual data rows (optional, used for understanding data types)\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.** Only use the Excel file method when users cannot provide a database connection.\n\n### Method 1: Database URL Configuration\n\n#### Configuration Steps\n\n1. Guide the user to provide database connection information\n2. Call the configuration script to save database information:\n\n```bash\npython scripts/config_db.py --db-url --db-password --config-file ./output/text-to-sql-config.json\n```\n\nThis script saves the configuration to `./output/text-to-sql-config.json` file.\n\n#### Database URL Format\n\n```\ndatabase_type://username:password@host:port/database_name\n```\n\nExamples:\n- MySQL: `mysql://root:password@localhost:3306/mydb` (will auto-convert to use pymysql driver)\n- MySQL with explicit driver: `mysql+pymysql://root:password@localhost:3306/mydb`\n- SQL Server: `mssql://sa:password@localhost:1433/mydb`\n\n**Note**: For MySQL connections, the system automatically converts `mysql://` to `mysql+pymysql://` for better compatibility. You can also explicitly specify the driver.\n\n#### Reading Table Structure\n\nAfter configuration, use the following command to read table structure:\n\n```bash\npython scripts/read_tables.py --config-file ./output/text-to-sql-config.json\n```\n\n### Method 2: Excel File Configuration\n\n#### Applicable Scenarios\n\nWhen users cannot provide a database connection, the Excel file method can be used for configuration.\n\n#### Configuration Steps\n\n1. Guide the user to provide the Excel file path\n2. Remind user to follow the Excel file format requirements described above\n3. After the user provides the file, **no parsing operation is needed**, directly call the `read_tables.py` script:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\nExample:\n```bash\npython scripts/read_tables.py --excel-file data_file.xlsx\n```\n\n- Parameter description:\n - `--excel-file`: Complete path to the Excel file\n\n## Operation Steps\n\n### Step 0: Configuration Check (Must Execute on First Call)\n\n**Important: The agent must check the configuration status before performing any operation**\n\nThe agent needs to check whether yaml configuration files exist in the `./output/` directory:\n\n**Check Method**:\n\n```bash\n# Check if .yaml files exist in ./output/ directory\nls ./output/*.yaml 2>/dev/null\n```\n\n**Check Result Handling**:\n\n**Scenario A: yaml configuration files exist**\n\n- Indicates user has completed configuration in advance\n- Agent skips all configuration steps (Step 1 and Step 2)\n- Proceed directly to Step 3 (Query with natural language)\n- Agent informs user: \"Detected existing topic configuration, you can ask questions directly.\"\n- List configured topic names for user reference\n\n**Scenario B: No yaml configuration files**\n\n- Indicates user has not completed configuration\n- Agent proceeds to execute Step 1 (Database Configuration) and Step 2 (Topic Setup)\n- Guide user through the standard configuration process\n\n### Standard Configuration Process\n\n#### Step 1: Database Configuration\n\n**The agent must clearly explain the two configuration methods:**\n\n1. **Method 1: Database URL Configuration (Highly Recommended)**\n - Read table structure directly through database connection\n - Real-time data synchronization, ensuring accuracy\n - Supports complete database semantic understanding\n\n2. **Method 2: Excel File Configuration**\n - Suitable for scenarios where direct database connection is not possible\n - Configure through Excel file schema description\n\n**The agent should clearly recommend users to prioritize the database URL configuration method.**\n\n**If user chooses database URL configuration:**\nGuide user to provide database URL and password, save to local configuration file:\n\n```bash\npython scripts/config_db.py --db-url --db-password \n```\n\nThis script saves the configuration to `text-to-sql-config.json` file.\n\n**If user chooses Excel file configuration:**\n1. Guide user to provide Excel file path\n2. Remind user to follow the **Excel File Format** requirements described in the \"Two Configuration Methods Explained\" section above\n3. After user provides file, **no parsing operation needed**, directly call:\n\n```bash\npython scripts/read_tables.py --excel-file \n```\n\n#### Step 2: Topic Setup\n\n**Important: The agent must mandatorily guide users to set up topics, table selection step cannot be skipped**\n\nThe agent should guide users through the following process:\n\n**2.1 Clearly inform user that topic setup is mandatory**\n\n- Agent clearly states: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n- Explain benefits of setting up topics: more accurate SQL generation, faster query speed, better business semantic understanding\n\n**2.2 Execute topic setup process**\n\n- Agent must guide user to create topics and select tables, **table selection step cannot be skipped**\n- Multiple topics can be created\n- Execution steps:\n 1. Call script to read all table structures and generate knowledge\n ```bash\n # Method 1: Use database connection (recommended)\n python scripts/read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output\n\n # Method 2: Use Excel file\n python scripts/read_tables.py --excel-file data_file.xlsx\n ```\n This script generates `table_info.json` (table name list) and `column_info.json` (table structure information) files.\n 2. **Agent reads table list from** **`table_info.json`** **file, displays all tables to user completely**, provides clear table descriptions\n 3. **Key emphasis: Table selection is a critical step in topic creation, directly affects SQL generation accuracy and query effectiveness, must be autonomously selected by user based on actual business needs**\n 4. Ask user: \"Please tell me the topic name you want to create (e.g., sales topic, human resources topic)\"\n 5. **Agent is strictly prohibited from selecting tables for topics itself**, must require user to explicitly specify needed tables\n 6. Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n 7. Generate topic configuration file\n ```bash\n python scripts/generate_yaml.py --topic-name --tables
--output-path ./output/\n ```\n 8. Ask user: \"Do you want to continue creating other topics?\"\n 9. User can repeat to create multiple topics (no need to re-read table structure, use existing `./output/column_info.json` directly)\n\n**2.3 Agent Guidance Recommendations**\n\n- **Agent is prohibited from making assumptions or guessing user intent**\n- Agent must mandatorily guide user to set up topics, cannot allow skipping\n- **Agent is strictly prohibited from setting topics or selecting tables for topics itself**, must display all table lists to user after reading table structure, let user completely autonomously select relevant tables based on actual business needs\n- Agent can provide brief table descriptions and recommendations, but final selection must be completely left to user\n- **Key emphasis: Table selection step cannot be skipped, this is a key link to ensure topic configuration accuracy**\n- **Prioritize recommending database connection method to users**, only use Excel file method when user cannot provide database connection\n\n#### Step 3: Query with Natural Language (Includes Topic Selection Logic)\n\n**Important: Step 3 can be executed directly (when Step 0 detects existing configuration)**\n\nAfter configuration is complete (or when existing configuration is detected), users can ask questions in natural language, the agent needs to select topic and generate SQL according to the following logic:\n\n##### 3.1 Topic Selection Logic\n\n**Scenario: One or more topics exist (user has completed topic setup)**\n\n**Case A: User question explicitly mentions topic**\n\n- Agent identifies topic keywords in user question (e.g., \"sales\", \"human resources\", \"inventory\", etc.)\n- Matches corresponding `.yaml` file in `./output/` directory\n- If match is successful, directly use that yaml file to call script\n- If match fails, prompt user that topic does not exist and list available topics\n\n**Case B: User question does not explicitly mention topic**\n\n- Agent analyzes question content, selects most relevant topic from all topics\n- Agent informs user: \"Based on your question, I suggest using [topic name] topic, continue?\"\n- If user confirms, use that topic; if user declines, list all topics for user to select\n\n##### 3.2 Call SQL Generation Script\n\nAfter determining topic, call API to generate SQL:\n\n```bash\npython scripts/query_sql.py --api-url https://asksql.ucap.com.cn/ --question \"user question\" --config ./output/.yaml\n```\n\nThe script calls the API's `/api/sql_for_skill/` endpoint and returns the generated SQL statement.\n\n### Optional Branches\n\n- When user wants to modify topic configuration: Re-call `generate_yaml.py` to overwrite original configuration file\n- When user wants to reconfigure database: Re-call `config_db.py` to overwrite configuration file\n- When user wants to view configured topics: Agent lists yaml files in `./output/` directory\n- When user question is ambiguous and cannot determine topic: Agent actively asks user or lists all topics for selection\n- When API service is not at default address: Use `--api-url` parameter to specify custom API address\n\n## Resource Index\n\n### Required Scripts\n\n- [scripts/config_db.py](scripts/config_db.py) - Save database configuration to local file\n- [scripts/read_tables.py](scripts/read_tables.py) - Read database table structure (supports both database connection and Excel file methods)\n- [scripts/generate_yaml.py](scripts/generate_yaml.py) - Generate topic configuration file (supports all parameter)\n- [scripts/query_sql.py](scripts/query_sql.py) - Generate SQL by calling generate_sql API endpoint\n\n### Output Files\n\nAll generated files are stored in `./output/` directory:\n- `table_info.json` - Table name list\n- `column_info.json` - Table structure information\n- `.yaml` - Topic configuration files\n- [references/open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) - YAML file format specification and field definitions (refer to this document when users ask about YAML format, field meanings, or configuration details)\n\n## Notes\n\n- All scripts are pure functional tools without interaction logic, all inputs are passed through parameters\n- Database URL and password are saved in local configuration file `./output/text-to-sql-config.json`\n- Topic configuration files are stored in yaml format for easy version management and viewing\n- Only `query_sql.py` calls API, other scripts are all executed locally\n- If database connection fails, check if URL and password are correct\n- If API service connection fails, check if service is started and address is correct\n- **Prioritize database connection method**, only use Excel file method when database connection cannot be provided\n- **When users ask about YAML file format, field definitions, or configuration details**, refer to the [open_semantic_interchange_description.md](references/open_semantic_interchange_description.md) document which contains complete specification of the semantic model YAML structure\n\n## Usage Examples\n\n### Example 0: Detected Existing Configuration (Direct Query)\n\n1. User: \"Query last month's total sales\"\n2. Agent: Check ./output/ directory\n3. Agent: Detect existing topic configuration files\n4. Agent: \"Detected existing topic configuration, you can ask questions directly.\"\n5. Agent: Identify topic relevant to the question, use corresponding topic configuration file\n6. Agent: Call query_sql.py to generate SQL\n\n### Example 1: Intelligently Guide User to Set Up Topic (Recommended Process)\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file ./output/text-to-sql-config.json --output-dir ./output to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create a topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"No need\"\n16. User: \"Query the top 10 products with highest sales last month\"\n17. Agent: Identify topic relevant to the question, use corresponding topic configuration file to call query_sql.py to generate SQL\n\n### Example 2: Configure with Excel File\n\n1. User: \"Help me configure Text-to-SQL, but I don't have a database\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Okay, you can use the Excel file method for configuration. Please provide an Excel file with format requirements: each sheet corresponds to a table name, first row is column names\"\n5. User: \"Provide Excel file path\"\n6. Agent: Call read_tables.py --excel-file data_file.xlsx to read Excel data\n7. Agent: \"Topic setup is a mandatory step...\"\n8. Follow same process as Example 1\n\n### Example 3: Set Up Multiple Topics\n\n1. User: \"Help me configure Text-to-SQL\"\n2. Agent: Check ./output/ directory\n3. Agent: No yaml configuration files found, need to execute configuration process\n4. Agent: \"Please provide database URL and password\"\n5. User: \"Database URL is URL\"\n6. Agent: Call config_db.py to save configuration\n7. Agent: \"Topic setup is a mandatory step, it will help you get more accurate SQL generation results and better query performance.\"\n8. Agent: Call read_tables.py --config-file text-to-sql-config.json to read all tables\n9. Agent: \"There are multiple tables in the database, what topic do you want to create?\"\n10. User: \"Create first topic\"\n11. Agent: \"Please select tables to include in this topic from the database tables\"\n12. User: \"Select relevant tables\"\n13. Agent: Call generate_yaml.py to generate topic configuration file\n14. Agent: \"Do you want to continue creating other topics?\"\n15. User: \"Create another topic\"\n16. Agent: \"Please select tables to include in this topic from the database tables\"\n17. User: \"Select relevant tables\"\n18. Agent: Call generate_yaml.py to generate topic configuration file\n19. Agent: \"Do you want to continue creating other topics?\"\n20. User: \"No need\"\n21. User: \"Query average salary of technical department\"\n22. Agent: Identify topic relevant to the question, determine most relevant topic\n23. Agent: \"Based on your question, I suggest using relevant topic, continue?\"\n24. User: \"Yes\"\n25. Agent: Call query_sql.py using corresponding topic configuration file to generate SQL\n\n### Example 4: User Explicitly Specifies Topic\n\n1. User configured multiple topics\n2. User: \"Use a specific topic to query total orders in 2024\"\n3. Agent: Check ./output/ directory (existing configuration)\n4. Agent: Identify topic explicitly specified by user, directly use corresponding topic configuration file\n5. Agent: Call query_sql.py to generate SQL\n\n### Example 5: Custom API Address\n\n1. User: \"My Text-to-SQL service is deployed at http://127.0.1.100:8080\"\n2. Agent: All query_sql.py calls use --api-url http://127.0.1.101:8080 parameter\n3. User: \"Query sales data\"\n4. Agent: Call query_sql.py --api-url http://127.0.1.101:8080 --config using corresponding topic configuration file to generate SQL\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn74572dhgzsd1yb43y0xdvcd584e5ht\",\n \"slug\": \"text2sql\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1775611586445\n}\n\nFile v1.0.0:references/open_semantic_interchange_description.md\n\n# Open Semantic Interchange (OSI) - Field Specification\n\n## 1. Introduction\n\nThis document provides a comprehensive field specification for the Open Semantic Interchange (OSI) YAML configuration file. The semantic model defines the structure for domain-specific data queries and analysis across various business contexts.\n\nThe YAML file serves as a metadata layer that enables AI-powered query generation and data interpretation for structured datasets.\n\n## 2. Document Structure\n\nThis specification is organized hierarchically to mirror the YAML file structure:\n\n- **Top-Level Fields**: Global configuration fields\n- **Semantic Model**: Theme-level definitions\n- **Datasets**: Individual data source definitions\n- **Fields**: Detailed field specifications within each dataset\n\n## 3. Top-Level Fields\n\n### 3.1 `yaml-language-server`\n\n**Data Type**: Comment directive\n\n**Description**: Specifies the JSON schema path for YAML language server validation and IDE auto-completion support.\n\n**Format**: `$schema=`\n\n**Constraints**: Must reference a valid schema file path relative to the YAML file location.\n\n---\n\n### 3.2 `version`\n\n**Data Type**: String\n\n**Description**: Defines the semantic model version number using semantic versioning convention.\n\n**Format**: `MAJOR.MINOR.PATCH`\n\n**Constraints**: \n- Must follow semantic versioning format\n- Each component must be a non-negative integer\n\n**Default Value**: `0.0.1`\n\n---\n\n### 3.3 `semantic_model`\n\n**Data Type**: Array of objects\n\n**Description**: Contains one or more theme definitions. Each theme represents a logical grouping of related datasets.\n\n**Required Sub-fields**:\n- `name`\n- `description`\n- `ai_context`\n- `datasets`\n\n---\n\n## 4. Semantic Model Object\n\n### 4.1 `name`\n\n**Data Type**: String\n\n**Description**: The theme name that identifies the semantic model's thematic classification.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be unique within the system\n\n---\n\n### 4.2 `description`\n\n**Data Type**: String\n\n**Description**: A brief description explaining the semantic model's purpose and scope.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the theme's domain\n\n---\n\n### 4.3 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration containing instruction information for AI processing.\n\n#### 4.3.1 `instructions`\n\n**Data Type**: String\n\n**Description**: AI processing instructions that guide the AI on how to utilize this semantic model for data queries and analysis.\n\n**Constraints**: \n- Must be a non-empty string\n- Should provide clear guidance on the model's usage\n\n---\n\n### 4.4 `datasets`\n\n**Data Type**: Array of objects\n\n**Description**: List of datasets, where each dataset corresponds to a database table or view.\n\n**Required Sub-fields** (for each dataset):\n- `name`\n- `source`\n- `description`\n- `ai_context`\n- `fields`\n\n---\n\n## 5. Dataset Object\n\n### 5.1 `name`\n\n**Data Type**: String\n\n**Description**: Dataset identifier that should correspond to the database table name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must be unique within the semantic model\n- Should match the actual database table name\n\n---\n\n### 5.2 `source`\n\n**Data Type**: String\n\n**Description**: Complete data source path specifying the database and table location.\n\n**Format**: `database_name.table_name`\n\n**Constraints**: \n- Must follow the format `.
`\n- Both database and table names must be valid identifiers\n\n---\n\n### 5.3 `description`\n\n**Data Type**: String\n\n**Description**: Dataset description explaining the dataset's purpose or content.\n\n**Constraints**: \n- Must be a non-empty string\n- Should briefly describe what the dataset contains\n\n---\n\n### 5.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration for the dataset.\n\n#### 5.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized name for the dataset, used for natural language query processing.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be consistent with the dataset name or description\n\n---\n\n### 5.5 `fields`\n\n**Data Type**: Array of objects\n\n**Description**: List of field definitions for the dataset. Each field represents a column in the database table.\n\n---\n\n## 6. Field Object\n\n### 6.1 `name`\n\n**Data Type**: String\n\n**Description**: Field identifier that must match the database column name.\n\n**Constraints**: \n- Must use snake_case naming convention\n- Must exactly match the database column name\n- Must be unique within the dataset\n\n---\n\n### 6.2 `type`\n\n**Data Type**: String\n\n**Description**: Field data type that determines query methods and presentation format.\n\n**Allowed Values**:\n\n| Value | Description | Usage |\n|-------|-------------|-------|\n| `text` | Text/string data | Names, codes, descriptions |\n| `number` | Numeric data | Counts, measurements, amounts |\n| `date` | Date/time data | Timestamps, dates |\n\n**Constraints**: \n- Must be one of the allowed values\n- Must match the actual database column data type\n\n---\n\n### 6.3 `description`\n\n**Data Type**: String\n\n**Description**: Human-readable field description used for UI display and documentation.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the field's meaning\n- Typically written in the local language for the target domain\n\n---\n\n### 6.4 `ai_context`\n\n**Data Type**: Object\n\n**Description**: Field-level AI context configuration containing metadata for AI processing.\n\n**Required Sub-fields**:\n- `ai_name`\n- `property`\n- `ai_type`\n- `value_list`\n- `is_default`\n\n#### 6.4.1 `ai_name`\n\n**Data Type**: String\n\n**Description**: AI-recognized field name, typically identical to the `description` field.\n\n**Constraints**: \n- Must be a non-empty string\n- Should match or be similar to the `description` value\n\n---\n\n#### 6.4.2 `property`\n\n**Data Type**: String\n\n**Description**: Field property type that indicates special field attributes.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `normal` | Normal field | Standard data fields |\n| `date` | Date field | Time-related fields used for filtering/grouping |\n| `detail_only` | Detail query only | Fields displayed only in detail queries, not used in aggregations |\n\n**Default Value**: `normal`\n\n**Constraints**: \n- Must be one of the allowed values\n\n---\n\n#### 6.4.3 `ai_type`\n\n**Data Type**: String\n\n**Description**: AI field type indicator for special processing requirements.\n\n**Allowed Values**:\n\n| Value | Description | Usage Scenario |\n|-------|-------------|----------------|\n| `date` | Date type | Fields requiring date-specific processing |\n| `enum` | Enumeration type | Fields with fixed allowable values |\n\n**Default Value**: `` (empty string)\n\n**Constraints**: \n- Must be one of the allowed values\n- If `enum`, then `value_list` must be provided\n\n---\n\n#### 6.4.4 `value_list`\n\n**Data Type**: Array of strings\n\n**Description**: List of allowable values for enumeration-type fields.\n\n**Usage**: \n- Required when `ai_type` is `enum`\n- Must be empty array `[]` for non-enumeration fields\n\n**Constraints**: \n- Must be an array (can be empty)\n- Each element must be a string\n- For enumeration fields, must contain all valid values\n\n---\n\n#### 6.4.5 `is_default`\n\n**Data Type**: Boolean\n\n**Description**: Indicates whether this field serves as the default time dimension for the dataset.\n\n**Allowed Values**:\n\n| Value | Description |\n|-------|-------------|\n| `true` | Serves as the primary time dimension for default time range filtering |\n| `false` | Not used as default time dimension |\n\n**Default Value**: `false`\n\n**Constraints**: \n- Must be a boolean value\n- Each dataset should have exactly one field with `is_default: true` (typically a date field)","readmeExcerpt":"Skill: TEXT2SQL Owner: asksqlai Summary: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions Tags: latest:1.0.2 Version history: v1.0.2 | 2026-07-07T22:30:46.663Z | user - Updated default SQL API service endpoint to https://asksql.ai/ - Removed file: skill-card.md - No other functional or de","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"pyyaml>=6.0\nsqlalchemy>=2.0.0"},{"language":"json","snippet":"[\n {\n \"STATUS\": \"ok\",\n \"MESSAGE\": \"\",\n \"SQL\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"SQL_NO_PERM\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"QUESTION\": \"This year's total sales\"\n }\n ]"},{"language":"text","snippet":"┌─────────────────────────────────────────────────────────────────┐\n│ Excel File: products.xlsx │\n├─────────────────────────────────────────────────────────────────┤\n│ Sheet: orders (Sheet name = Table name) │\n├──────────┬──────────┬────────────┬───────────┬─────────────────┤\n│ order_id │ customer │ order_date │ amount │ status │\n│ (Column) │ (Column) │ (Column) │ (Column) │ (Column) │\n├──────────┼──────────┼────────────┼───────────┼─────────────────┤\n│ 1001 │ John │ 2024-01-15 │ 1500.00 │ completed │\n│ 1002 │ Mary │ 2024-01-16 │ 2300.50 │ pending │\n│ ... │ ... │ ... │ ... │ ... │\n└──────────┴──────────┴────────────┴───────────┴─────────────────┘\n ↑ First row = Column names (field names)\n ↑ Data starts from second row"},{"language":"bash","snippet":"python scripts/config_db.py --db-url --db-password --config-file ./output/text-to-sql-config.json"},{"language":"text","snippet":"database_type://username:password@host:port/database_name"},{"language":"bash","snippet":"python scripts/read_tables.py --config-file ./output/text-to-sql-config.json"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: text-to-sql\ndescription: Support generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions\ndependency:\n python:\n - pyyaml>=6.0\n - sqlalchemy>=2.0.0\n---\n\n# Text-to-SQL Intelligent Query Skill\n\n## Task Objectives\n\n- This Skill is used for: Generating SQL query statements through natural language, supporting multi-topic database configuration and table structure management\n- Capabilities include: Database configuration, topic management, table structure reading, natural language to SQL\n- Trigger conditions: User needs to configure Text-to-SQL database, create data topics, select data tables, or generate SQL with natural language questions\n\n## Prerequisites\n\n### Dependency Description\n\nRequired packages and versions for scripts:\n\n```\npyyaml>=6.0\nsqlalchemy>=2.0.0\n```\n\n### API Service Description\n\nThis Skill generates SQL through the HTTP API `/api/sql_for_skill/` endpoint:\n\n- Default API address: `https://asksql.ai/`\n- Service needs to be started before calling\n- Supports custom API address (via `--api-url` parameter)\n\n**API Interface Specification**:\n\n- Endpoint path: `POST /api/sql_for_skill/`\n- Request format: `multipart/form-data`\n- Request parameters:\n - `question`: User's natural language question (string)\n - `yaml_file`: YAML configuration file (uploaded as file)\n- Response format: JSON array\n- Response example:\n ```json\n [\n {\n \"STATUS\": \"ok\",\n \"MESSAGE\": \"\",\n \"SQL\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"SQL_NO_PERM\": \"SELECT SUM(total_amount) AS total_sales FROM orders WHERE YEAR(signing_date) = 2026\",\n \"QUESTION\": \"This year's total sales\"\n }\n ]\n ```\n- Return value: Extract the `SQL` field from the first element of the response array\n\n## Data Configuration Methods\n\n### Two Configuration Methods Explained\n\nWhen the agent guides users through data configuration, it must clearly explain the following two methods:\n\n**Method 1: Database URL Configuration (Highly Recommended)**\n- Read table structure directly through database connection\n- Real-time data synchronization, ensuring accuracy\n- Supports complete database semantic understanding\n\n**Method 2: Excel File Configuration**\n- Suitable for scenarios where direct database connection is not possible\n- Configure through Excel file with specific format requirements\n\n**Excel File Format (Must Strictly Follow):**\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│ Excel File: products.xlsx │\n├─────────────────────────────────────────────────────────────────┤\n│ Sheet: orders (Sheet name = Table name) │\n├──────────┬──────────┬────────────┬───────────┬─────────────────┤\n│ order_id │ customer │ order_date │ amount │ status │\n│ (Column) │ (Column) │ (Column) │ (Column) │ (Column) │\n├──"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn74572dhgzsd1yb43y0xdvcd584e5ht\",\n \"slug\": \"text2sql\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1783463446663\n}"},{"path":"references/open_semantic_interchange_description.md","content":"# Open Semantic Interchange (OSI) - Field Specification\n\n## 1. Introduction\n\nThis document provides a comprehensive field specification for the Open Semantic Interchange (OSI) YAML configuration file. The semantic model defines the structure for domain-specific data queries and analysis across various business contexts.\n\nThe YAML file serves as a metadata layer that enables AI-powered query generation and data interpretation for structured datasets.\n\n## 2. Document Structure\n\nThis specification is organized hierarchically to mirror the YAML file structure:\n\n- **Top-Level Fields**: Global configuration fields\n- **Semantic Model**: Theme-level definitions\n- **Datasets**: Individual data source definitions\n- **Fields**: Detailed field specifications within each dataset\n\n## 3. Top-Level Fields\n\n### 3.1 `yaml-language-server`\n\n**Data Type**: Comment directive\n\n**Description**: Specifies the JSON schema path for YAML language server validation and IDE auto-completion support.\n\n**Format**: `$schema=`\n\n**Constraints**: Must reference a valid schema file path relative to the YAML file location.\n\n---\n\n### 3.2 `version`\n\n**Data Type**: String\n\n**Description**: Defines the semantic model version number using semantic versioning convention.\n\n**Format**: `MAJOR.MINOR.PATCH`\n\n**Constraints**: \n- Must follow semantic versioning format\n- Each component must be a non-negative integer\n\n**Default Value**: `0.0.1`\n\n---\n\n### 3.3 `semantic_model`\n\n**Data Type**: Object\n\n**Description**: The semantic model definition. In the current generator implementation, this file contains exactly one semantic model object.\n\n**Required Sub-fields**:\n- `name`\n- `description`\n- `ai_context`\n- `datasets`\n- `relationships`\n- `metrics`\n- `terms`\n- `rules`\n\n---\n\n## 4. Semantic Model Object\n\n### 4.1 `name`\n\n**Data Type**: String\n\n**Description**: The theme name that identifies the semantic model's thematic classification.\n\n**Constraints**: \n- Must be a non-empty string\n- Should be unique within the system\n\n---\n\n### 4.2 `description`\n\n**Data Type**: String\n\n**Description**: A brief description explaining the semantic model's purpose and scope.\n\n**Constraints**: \n- Must be a non-empty string\n- Should clearly describe the theme's domain\n\n---\n\n### 4.3 `ai_context`\n\n**Data Type**: Object\n\n**Description**: AI context configuration containing instruction information for AI processing.\n\n#### 4.3.1 `instructions`\n\n**Data Type**: String\n\n**Description**: AI processing instructions that guide the AI on how to utilize this semantic model for data queries and analysis.\n\n**Constraints**: \n- Must be a non-empty string\n- Should provide clear guidance on the model's usage\n\n---\n\n### 4.4 `datasets`\n\n**Data Type**: Array of objects\n\n**Description**: List of datasets, where each dataset corresponds to a database table or view.\n\n**Required Sub-fields** (for each dataset):\n- `name`\n- `source`\n- `description`\n- `ai_context`\n- `fields`\n\n---\n\n### 4.5 `relationships`\n\n**Data Type**: Array of objects\n"},{"path":"skill-card.md","content":"## Description:\n\nSupport generating SQL queries through natural language; use when users need to configure Text-to-SQL database, manage data topics, or generate SQL with natural language questions.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[asksqlai](https://clawhub.ai/user/asksqlai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and data teams use TEXT2SQL to configure database or Excel-backed semantic topics, inspect table structures, generate topic YAML files, and request SQL from natural-language questions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can collect and upload database metadata, table samples, topic YAML, questions, or spreadsheet data to asksql.ai.\n\nMitigation: Use a least-privilege read-only database account, avoid confidential spreadsheets unless remote processing is accepted, and inspect or restrict what is sent to the remote service.\n\nRisk: Database passwords may be passed on the command line and saved in a local configuration file.\n\nMitigation: Use temporary or scoped credentials, protect the output directory, and rotate credentials after use when handling sensitive environments.\n\nRisk: Generated SQL may be incorrect for the intended business question or unsafe to run without review.\n\nMitigation: Review generated SQL before execution and run it first against non-production data or with read-only permissions.\n\n## Reference(s):\n\n- [Open Semantic Interchange field specification](references/open_semantic_interchange_description.md)\n- [AskSqlAI SQL API service](https://asksql.ai/)\n- [TEXT2SQL ClawHub release](https://clawhub.ai/asksqlai/skills/text2sql)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with shell commands, JSON status output, YAML configuration files, and SQL text]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Writes local output files for database configuration, table metadata, column metadata, and topic YAML; generated SQL is returned when the remote API call succeeds.]\n\n## Skill Version(s):\n\n1.0.2 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1477,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T14:58:39.517Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T17:41:12.642Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}