sqlseed-ai

English | 中文

Optional LLM schema analysis and contract-driven configuration repair for sqlseed. The plugin suggests column rules, validates and repairs configurations, and can prepare template values. Accepted configurations can be executed offline by Core.

Supported backend adapters are Google AI Studio, LM Studio, Ollama, and OpenAI-compatible APIs. Model availability and response quality require a real backend test; installing the plugin does not perform one.

Installation

For the 0.2.4 release, use a Python 3.10+ virtual environment:

python -m pip install "sqlseed-ai==0.2.4"

Core 0.2.3 lacks the plugin hooks and target-validation interfaces used here. For development, install Core and the required local plugins together from the repository root:

python -m pip install -e . -e ./plugins/sqlseed-cli -e ./plugins/sqlseed-ai

CLI quick start

Configure a backend, an available model, and credentials as needed by that service. For an OpenAI-compatible endpoint, for example:

export SQLSEED_AI_BACKEND=openai_compat
export SQLSEED_AI_BASE_URL="https://your-service.example/v1"
export SQLSEED_AI_MODEL="your-available-model"
export SQLSEED_AI_API_KEY="your-api-key"

Create the SQLite tables before analysis:

# Analyze one table and validate the suggested configuration
sqlseed ai-suggest app.db --table users --output users.yaml --verify --no-cache

# Analyze all tables with the v4 AutoHealOrchestrator
sqlseed ai-analyze --db app.db --output config.yaml

# Repair an existing configuration
sqlseed auto-heal --db app.db --config broken.yaml --output healed.yaml

# After reviewing the generated rules, execute them offline
sqlseed fill --config users.yaml --no-ai

ai-analyze --tables orders includes referenced parents up to --max-depth 5. --no-dependencies or --max-depth 0 limits the scope to named tables. Unknown table names fail before output is written. --merge requires --output; it replaces selected tables, retains existing dependency and unrelated tables plus root settings, and appends missing generated tables.

auto-heal --config reads that document. An explicit --db or --url selects the output connection. Invalid YAML, configuration structure, or unknown input tables fail without replacing the output file. Candidate repairs are checked for config shape, builtin generators, parameter names and annotated types, then passed through the contract validator. Normal preview and execution are still needed to verify actual generated values and database constraints.

AI MCP server

The AI MCP entry point requires the mcp extra:

python -m pip install "sqlseed-ai[mcp]==0.2.4"
mcp-server-sqlseed-ai

For a source checkout, use python -m pip install -e . -e ./plugins/sqlseed-cli -e "./plugins/sqlseed-ai[mcp]". Configure an MCP client to launch mcp-server-sqlseed-ai. It exposes:

• sqlseed_ai_generate_yaml
• sqlseed_gemma4_analyze
• sqlseed_gemma4_agent_fill
• sqlseed_list_gemma_models

For deterministic YAML generation and data filling without an LLM, use the separate Core MCP package. MCP discovery or a successful model list does not establish that inference works.

Configuration and caching

Configuration is loaded through AIConfig.from_env(). Backend resolution uses the explicit backend, then known URL patterns, then OpenAI-compatible behavior. It does not probe every service as a fallback chain. The tool_calling_protocol setting and its resolver choose the response protocol; a model name alone is insufficient.

AI configuration caches include schema hashes. Schema changes invalidate cached suggestions; --no-cache bypasses them. Review model output before writing data.

Requirements

• Python >=3.10
• sqlseed>=0.2.4.dev0,<0.3
• sqlseed-cli>=0.2.4.dev0,<0.3
• openai>=1.0
• httpx>=0.24.0
• networkx>=3.0
• Optional mcp extra: mcp>=1.0,<2
• A reachable, configured backend for actual model requests

See the AI integration guide, migration guide, and configuration source.

License: AGPL-3.0-or-later. The distribution includes the full LICENSE text.