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

These instructions target version 0.2.5. Check Releases for publication status; use the source installation below to test an unpublished candidate. Use a Python 3.10+ virtual environment:

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

Core 0.2.4 and older lack the shared diagnostic interfaces required by this version. 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.

Single-table ai-suggest checks that the target exists before contacting the model. Suggestions and cached results must name that same table, including when using --no-verify or --max-retries 0. SQLite case aliases remain supported; export preserves real table and column names, including leading punctuation. Rejected suggestions leave existing output files unchanged.

The prompt requests one JSON object configuring only the named table, preserving its table and column names. Other table names are reference context, not additional output targets; the response still passes target validation.

Direct analysis (--no-verify or --max-retries 0), streaming or non-streaming, reports empty replies, invalid JSON, output-limit truncation, and empty configuration objects separately, without echoing the model response in these diagnostics. It announces a retry only when another existing shorter-prompt level remains. Once those levels are exhausted, it reports the final cause and exits unsuccessfully; it does not increase the request budget or change the existing output YAML or database.

Direct Python callers can pass preserve_names=True to SchemaAnalyzer.call_llm() or call_llm_streaming() before validating against their schema. The default retains the existing leading-punctuation cleanup.

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.5"
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 requests to localhost and loopback IP addresses connect directly even when an HTTP proxy is configured. Remote services keep the environment proxy settings; SSL_CERT_FILE and SSL_CERT_DIR remain effective for HTTPS certificate validation.

For Python callers, SchemaAnalyzer.call_llm(..., strict_json=True) and call_llm_streaming(..., strict_json=True) distinguish empty replies, invalid JSON, and output-limit truncation using content-free JSONResponseError.code values. JSON parsing can complete missing final } or ] delimiters, including inside code fences, but never fills missing values or strings. An output-limit response is rejected even if its prefix parses, including a streaming length marker in a separate empty terminal chunk. Both methods default to strict_json=False. Strict local calls request JSON sampling constraints: LM Studio uses its JSON-schema grammar interface, and Ollama uses JSON object mode. A server that explicitly rejects the format gets one text-mode compatibility attempt; the same strict parser still rejects invalid or truncated output. The CLI's direct path and both refiner modes keep their existing prompt/refinement retry budgets. Strict tool calling also rejects arrays, scalars and null arguments as invalid_json; compatibility mode may still fall back to response text. Parsed suggestions still require scope and rule validation.

AI configuration caches include schema hashes. Schema changes invalidate cached suggestions; --no-cache bypasses them. Malformed cache metadata or configuration containers are treated as cache misses. Review model output before writing data.

Requirements

These metadata requirements apply to version 0.2.5 and its source candidates. Use local Core and plugins together when developing from source.

• Python >=3.10
• sqlseed>=0.2.5.dev0,<0.3
• sqlseed-cli>=0.2.4.dev0,<0.3
• openai>=1.55.3 (SDK transport defaults with HTTPX 0.28 compatibility)
• 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.