fix: restore OpenRouter as free option, fix lint/mypy errors

- Restore OpenRouter documentation as openai_compat backend example

- Fix ruff import sorting in analyzer.py

- Fix ruff format in 4 plugin files

- Fix mypy no-any-return in analyzer.py

- Fix mypy attr-defined for signal.alarm on Windows

Author: sunbos

README.md

@@ -681,7 +681,9 @@ sqlseed-ai supports Gemma 4 model family (2B/4B/26B/31B) with Native Function Ca
 | **Google AI Studio** | Official API, recommended for Gemma 4 26B/31B | `--backend google_ai_studio` or `SQLSEED_AI_BACKEND=google_ai_studio` |
 | **LM Studio** | Local inference, suitable for Gemma 4 2B/4B | `--backend lm_studio` or `SQLSEED_AI_BACKEND=lm_studio` |
 | **Ollama** | Local inference, suitable for Gemma 4 2B/4B/26B | `--backend ollama` or `SQLSEED_AI_BACKEND=ollama` |
-| **OpenAI-compatible** | Generic OpenAI-compatible endpoint | `--backend openai_compat` or `SQLSEED_AI_BACKEND=openai_compat` |
+| **OpenAI-compatible** | Generic OpenAI-compatible endpoint (e.g., OpenRouter, DeepSeek) | `--backend openai_compat` or `SQLSEED_AI_BACKEND=openai_compat` |
+
+> **💡 OpenRouter (Free)**: For users without a paid API key, OpenRouter provides free models. Set `SQLSEED_AI_BACKEND=openai_compat`, `SQLSEED_AI_BASE_URL=https://openrouter.ai/api/v1`, and `SQLSEED_AI_MODEL=<free-model-name>`.
 
 ```bash
 # Skip cache

README.zh-CN.md

@@ -574,10 +574,12 @@ sqlseed-ai 支持 Gemma 4 系列模型（2B/4B/26B/31B）通过 GEMMA_TOOLS 协
 
 | 后端 | 说明 | 配置方式 |
 | :--- | :--- | :--- |
-| **Google AI Studio** | 官方 API，推荐 Gemma 4 26B/31B | `--backend google` 或 `SQLSEED_AI_BACKEND=google` |
-| **LM Studio** | 本地推理，适合 Gemma 4 2B/4B | `--backend lm-studio` 或 `SQLSEED_AI_BACKEND=lm-studio` |
+| **Google AI Studio** | 官方 API，推荐 Gemma 4 26B/31B | `--backend google_ai_studio` 或 `SQLSEED_AI_BACKEND=google_ai_studio` |
+| **LM Studio** | 本地推理，适合 Gemma 4 2B/4B | `--backend lm_studio` 或 `SQLSEED_AI_BACKEND=lm_studio` |
 | **Ollama** | 本地推理，适合 Gemma 4 2B/4B/26B | `--backend ollama` 或 `SQLSEED_AI_BACKEND=ollama` |
-| **OpenAI-compatible** | 通用 OpenAI 兼容端点 | `--backend openai_compat` 或 `SQLSEED_AI_BACKEND=openai_compat` |
+| **OpenAI-compatible** | 通用 OpenAI 兼容端点（如 OpenRouter、DeepSeek） | `--backend openai_compat` 或 `SQLSEED_AI_BACKEND=openai_compat` |
+
+> **💡 OpenRouter（免费方案）**：没有付费 API Key 的用户，可以使用 OpenRouter 的免费模型。设置 `SQLSEED_AI_BACKEND=openai_compat`、`SQLSEED_AI_BASE_URL=https://openrouter.ai/api/v1`、`SQLSEED_AI_MODEL=<免费模型名>`。
 
 > **💡 环境变量**：支持 `SQLSEED_AI_API_KEY`、`SQLSEED_AI_BASE_URL`、`SQLSEED_AI_MODEL`、`SQLSEED_AI_BACKEND`。也支持 `OPENAI_API_KEY` / `OPENAI_BASE_URL` 作为回退。
 

plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/server.py

@@ -322,10 +322,12 @@ def sqlseed_list_gemma_models() -> dict[str, Any]:
     """
     models = []
     for member in GemmaModel:
-        models.append({
-            "id": member.value,
-            "display_name": member.display_name,
-        })
+        models.append(
+            {
+                "id": member.value,
+                "display_name": member.display_name,
+            }
+        )
 
     backends = [
         {"id": "google_ai_studio", "description": "Google AI Studio API (free tier available, recommended)"},

plugins/sqlseed-ai/README.md

@@ -4,7 +4,7 @@
 
 AI-powered data generation plugin for [sqlseed](https://github.com/sunbos/sqlseed).
 
-LLM-driven schema analysis, self-correcting config generation, and template pool assistance. Supports multiple backends: Google AI Studio (Gemma 4 Native Function Calling), LM Studio, Ollama, and any OpenAI-compatible API.
+LLM-driven schema analysis, self-correcting config generation, and template pool assistance. Supports multiple backends: Google AI Studio (Gemma 4 Native Function Calling), LM Studio, Ollama, and any OpenAI-compatible API (OpenRouter, OpenAI, DeepSeek, etc.).
 
 ## Installation
 
@@ -54,7 +54,14 @@ When using the `google_ai_studio` backend (default), the `GemmaModel` enum provi
 
 1. **Google AI Studio**: Defaults to `gemma-4-26b-it` (recommended balance of quality and speed).
 2. **LM Studio / Ollama**: User must specify a loaded model via `--model` or `SQLSEED_AI_MODEL`.
-3. **OpenAI-compatible**: User must specify both `--model` and `--base-url`.
+3. **OpenAI-compatible** (OpenRouter, DeepSeek, etc.): User must specify both `--model` and `--base-url`.
+
+For **OpenRouter free models**, set:
+```bash
+export SQLSEED_AI_BACKEND=openai_compat
+export SQLSEED_AI_BASE_URL=https://openrouter.ai/api/v1
+export SQLSEED_AI_MODEL=<free-model-name>
+```
 
 Skip auto-selection by specifying `--model` or `SQLSEED_AI_MODEL`.
 

plugins/sqlseed-ai/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 [sqlseed](https://github.com/sunbos/sqlseed) 的 AI 驱动数据生成插件。
 
-LLM 驱动的 Schema 分析、自纠正配置生成和模板池辅助。支持多种后端：Google AI Studio（Gemma 4 原生函数调用）、LM Studio、Ollama，以及任何 OpenAI 兼容 API。
+LLM 驱动的 Schema 分析、自纠正配置生成和模板池辅助。支持多种后端：Google AI Studio（Gemma 4 原生函数调用）、LM Studio、Ollama，以及任何 OpenAI 兼容 API（OpenRouter、OpenAI、DeepSeek 等）。
 
 ## 安装
 
@@ -54,7 +54,14 @@ sqlseed ai-suggest app.db --table users -o users.yaml --no-cache
 
 1. **Google AI Studio**：默认使用 `gemma-4-26b-it`（推荐的质量与速度平衡）。
 2. **LM Studio / Ollama**：用户需通过 `--model` 或 `SQLSEED_AI_MODEL` 指定已加载的模型。
-3. **OpenAI-compatible**：用户需同时指定 `--model` 和 `--base-url`。
+3. **OpenAI-compatible**（OpenRouter、DeepSeek 等）：用户需同时指定 `--model` 和 `--base-url`。
+
+**OpenRouter 免费模型**设置：
+```bash
+export SQLSEED_AI_BACKEND=openai_compat
+export SQLSEED_AI_BASE_URL=https://openrouter.ai/api/v1
+export SQLSEED_AI_MODEL=<免费模型名>
+```
 
 通过 `--model` 或 `SQLSEED_AI_MODEL` 跳过自动选择。
 

plugins/sqlseed-ai/src/sqlseed_ai/_model_selector.py

@@ -73,16 +73,14 @@ def select_next_gemma_model(failed_model: str) -> str | None:
 
 def get_available_gemma_models() -> list[dict[str, str]]:
     """Return list of available Gemma 4 models with display info."""
-    return [
-        {"id": m.value, "display_name": m.display_name}
-        for m in _GEMMA_MODEL_PRIORITY
-    ]
+    return [{"id": m.value, "display_name": m.display_name} for m in _GEMMA_MODEL_PRIORITY]
 
 
 # ── Legacy compatibility ─────────────────────────────────────────────
 # These functions maintain backward compatibility with code that
 # referenced the old OpenRouter-based model selector.
 
+
 def select_best_free_model() -> str:
     """Legacy compat: returns the default Gemma 4 model."""
     return select_gemma_model()

plugins/sqlseed-ai/src/sqlseed_ai/analyzer.py

@@ -7,7 +7,7 @@
 from sqlseed_ai._client import get_openai_client
 from sqlseed_ai._json_utils import parse_json_response
 from sqlseed_ai._model_selector import select_next_gemma_model
-from sqlseed_ai.config import AIConfig, AIBackend
+from sqlseed_ai.config import AIBackend, AIConfig
 from sqlseed_ai.examples import FEW_SHOT_EXAMPLES
 
 from sqlseed._utils.logger import get_logger
@@ -343,9 +343,7 @@ def _call_llm_once(self, messages: list[dict[str, str]]) -> dict[str, Any]:
             return {}
         return self._parse_json_response(content)
 
-    def _try_tool_calling(
-        self, client: Any, kwargs: dict[str, Any]
-    ) -> dict[str, Any] | None:
+    def _try_tool_calling(self, client: Any, kwargs: dict[str, Any]) -> dict[str, Any] | None:
         """Attempt Gemma 4 native function calling.
 
         If the model supports tool use, it will invoke the `analyze_schema`
@@ -374,7 +372,7 @@ def _try_tool_calling(
                         args_str = tool_call.function.arguments
                         if args_str:
                             try:
-                                result = json.loads(args_str)
+                                result: dict[str, Any] | None = json.loads(args_str)
                                 logger.info(
                                     "Gemma 4 native function calling succeeded",
                                     tool="analyze_schema",

plugins/sqlseed-ai/src/sqlseed_ai/config.py

@@ -10,6 +10,7 @@
 
 logger = get_logger(__name__)
 
+
 # ── Gemma 4 model registry ──────────────────────────────────────────
 class GemmaModel(str, Enum):
     """Supported Gemma 4 model variants."""
@@ -60,15 +61,9 @@ class AIConfig(BaseModel):
     @classmethod
     def from_env(cls) -> AIConfig:
         api_key = (
-            os.environ.get("SQLSEED_AI_API_KEY")
-            or os.environ.get("GOOGLE_API_KEY")
-            or os.environ.get("OPENAI_API_KEY")
-        )
-        base_url = (
-            os.environ.get("SQLSEED_AI_BASE_URL")
-            or os.environ.get("OPENAI_BASE_URL")
-            or None
+            os.environ.get("SQLSEED_AI_API_KEY") or os.environ.get("GOOGLE_API_KEY") or os.environ.get("OPENAI_API_KEY")
         )
+        base_url = os.environ.get("SQLSEED_AI_BASE_URL") or os.environ.get("OPENAI_BASE_URL") or None
         model = os.environ.get("SQLSEED_AI_MODEL") or None
         backend_str = os.environ.get("SQLSEED_AI_BACKEND", "").lower()
         timeout_str = os.environ.get("SQLSEED_AI_TIMEOUT")
@@ -82,9 +77,7 @@ def from_env(cls) -> AIConfig:
             backend = AIBackend.OLLAMA
         elif backend_str == "openai_compat":
             backend = AIBackend.OPENAI_COMPAT
-        elif backend_str == "google_ai_studio" or (
-            base_url and "generativelanguage.googleapis.com" in base_url
-        ):
+        elif backend_str == "google_ai_studio" or (base_url and "generativelanguage.googleapis.com" in base_url):
             backend = AIBackend.GOOGLE_AI_STUDIO
         elif base_url and ("127.0.0.1:1234" in base_url or "localhost:1234" in base_url):
             backend = AIBackend.LM_STUDIO
@@ -130,13 +123,15 @@ def resolve_api_key(self) -> str | None:
 
         # Try environment variables
         return (
-            os.environ.get("SQLSEED_AI_API_KEY")
-            or os.environ.get("GOOGLE_API_KEY")
-            or os.environ.get("OPENAI_API_KEY")
+            os.environ.get("SQLSEED_AI_API_KEY") or os.environ.get("GOOGLE_API_KEY") or os.environ.get("OPENAI_API_KEY")
         )
 
     def apply_overrides(
-        self, *, api_key: str | None = None, base_url: str | None = None, model: str | None = None,
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str | None = None,
         backend: AIBackend | None = None,
     ) -> AIConfig:
         if api_key:

src/sqlseed/cli/main.py

@@ -495,13 +495,13 @@ def ai_suggest(
     old_handler: Any = None
     if hasattr(signal, "SIGALRM"):
         old_handler = signal.signal(signal.SIGALRM, lambda _s, _f: _sigalrm_handler(total_timeout))
-        signal.alarm(int(total_timeout))
+        signal.alarm(int(total_timeout))  # type: ignore[attr-defined]
 
     try:
         result = _run_ai_analysis(analyzer, db_path, table, verify, max_retries, no_cache)
     finally:
         if hasattr(signal, "SIGALRM"):
-            signal.alarm(0)
+            signal.alarm(0)  # type: ignore[attr-defined]
             if old_handler is not None:
                 signal.signal(signal.SIGALRM, old_handler)