lucid-skill

AI-native data analysis skill. Connect Excel, CSV, MySQL, PostgreSQL — understand business semantics, query with SQL.

No API key required. No LLM inside — the AI agent is the brain; lucid-skill is the hands.

Features

• Multi-source: Excel (.xlsx/.xls), CSV, MySQL, PostgreSQL — all unified into SQL
• Semantic Layer: Define business meanings for tables and columns; persist as YAML, Git-friendly
• JOIN Discovery: Automatically find join paths between tables (direct + indirect)
• Domain Clustering: Auto-group tables into business domains
• Embedding Search: Optional multilingual vector search for table discovery
• Read-only Safety: Only SELECT allowed — mutating SQL is blocked at the engine level

Install

npm install -g @wiseria/lucid-skill

Quick Start

# Connect a data source
lucid-skill connect csv /path/to/sales.csv

# Explore schema and semantics
lucid-skill init-semantic

# Search tables by business meaning
lucid-skill search "销售额 客户"

# Query with SQL
lucid-skill query "SELECT product, SUM(amount) FROM sales GROUP BY product ORDER BY 2 DESC LIMIT 10"

Architecture

Agent ──→ lucid-skill CLI ──→ Connectors (Excel/CSV/MySQL/PG)
                │                      │
                ├── Catalog (SQLite)    └── DuckDB (in-memory query engine)
                └── Semantic Store (YAML)

• No LLM inside — lucid-skill provides data access; the AI agent handles reasoning
• Read-write separation — file/DB sources are registered into DuckDB for read-only querying
• Semantic persistence — YAML definitions survive restarts, shareable via Git

Supported Data Sources

| Type | Format | Notes | |------|--------|-------| | Excel | .xlsx, .xls | Multiple sheets supported | | CSV | .csv | Auto-detects encoding and delimiter | | MySQL | 5.7+ / 8.0+ | Reads foreign keys and column comments | | PostgreSQL | 12+ | Reads foreign keys and column comments |

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | LUCID_DATA_DIR | ~/.lucid-skill/ | Data directory (catalog, semantic store, models) | | LUCID_EMBEDDING_ENABLED | false | Enable vector search (~460 MB model download on first use) |

Security

• Read-only: Only SELECT / WITH statements are allowed; all mutating SQL is blocked
• No credentials stored: Database passwords are never written to disk
• Local only: All data stays on your machine

MCP Server Mode

lucid-skill also works as an MCP Server for platforms that support it:

lucid-skill serve

Development

git clone https://github.com/WiseriaAI/lucid-skill
cd lucid-skill
npm install
npm run build
npm test

License

MIT