feat(ai): align Gemma 4 model IDs with platform-specific formats

Add GemmaModel.to_backend_id() for per-platform model ID conversion (Google AI Studio, LM Studio, Ollama, OpenRouter). Update model fallback chain to skip cloud-unavailable 12B variant. Fix ruff RET504/RET505 lint errors. Update all AGENTS.md/CLAUDE.md/GEMINI.md docs with corrected model tables, env vars, and function names.

Author: sunbos

AGENTS.md

@@ -66,7 +66,7 @@ sqlseed/
 
 - **Provider fallback chain**: mimesis → faker → base (auto-degrades)
 - **AI backend fallback chain**: Google AI Studio → LM Studio → Ollama (multi-backend)
-- **Gemma 4 Native Function Calling**: `GEMMA_TOOLS` (analyze_schema, generate_column_values) with auto-fallback to JSON mode
+- **Gemma 4 Native Function Calling**: `GEMMA_TOOLS` (analyze_schema) with auto-fallback to JSON mode
 - **Context manager pattern**: `DataOrchestrator` is a context manager
 - **Plugin mediation**: `PluginMediator` bridges plugins and core (not direct calls)
 - **DAG-based column ordering**: `ColumnDAG` handles derive_from dependencies

CLAUDE.md

@@ -64,7 +64,7 @@ _utils/ → (no internal deps, used by all layers)
 ### Key Modules
 
 - **`core/orchestrator.py`** — `DataOrchestrator` is the central coordinator. Uses `CoreCtx` (db, schema, mapper, relation, shared_pool) and `ExtCtx` (registry, plugins, mediator, enrichment, metrics) dataclasses. `fill_table()` is the main entry point; `fill()` is its alias.
-- **`core/mapper.py`** — `ColumnMapper` with 9-level strategy chain (autoincrement PK → user config → exact match → default check → pattern match → nullable → type fallback). 74 exact rules, 26 regex patterns.
+- **`core/mapper.py`** — `ColumnMapper` with 9-level strategy chain (autoincrement PK → user config → exact match → default check → pattern match → nullable → type fallback). 74 exact rules, 27 regex patterns.
 - **`core/schema.py`** — `SchemaInferrer` reads SQLite schema + `CREATE TABLE` SQL for autoincrement detection.
 - **`core/relation.py`** — `RelationResolver` + `SharedPool` for cross-table FK integrity. Implicit associations via name matching, explicit via `ColumnAssociation` config.
 - **`core/column_dag.py`** — Topological sort for `derive_from` column dependencies.
@@ -74,7 +74,8 @@ _utils/ → (no internal deps, used by all layers)
 - **`database/`** — `DatabaseAdapter` protocol with two implementations: `SQLiteUtilsAdapter` (default, requires `sqlite-utils`) and `RawSQLiteAdapter` (fallback). `_compat.py` controls `HAS_SQLITE_UTILS` flag.
 - **`plugins/`** — 11 pluggy hooks. `PluginManager` + `PluginMediator` bridge plugins and core.
 - **`config/`** — Pydantic models (`GeneratorConfig`, `TableConfig`, `ColumnConfig`, `ColumnAssociation`), YAML/JSON loader, `SnapshotManager`.
-- **`cli/main.py`** — Click commands: `fill`, `preview`, `inspect`, `ai-suggest`, `config-generate`. CLI log level via `SQLSEED_LOG_LEVEL` env var (default `WARNING`). Cache dir via `SQLSEED_CACHE_DIR` env var.
+- **`cli/main.py`** — Click commands: `fill`, `preview`, `inspect`, `init`, `replay`, `ai-suggest`. CLI log level via `SQLSEED_LOG_LEVEL` env var (default `WARNING`). Cache dir via `SQLSEED_CACHE_DIR` env var.
+- **`_utils/paths.py`** — Platform-aware cache directory resolution (`get_cache_dir()`). Supports macOS/Linux/Windows, overridable via `SQLSEED_CACHE_DIR` env var.
 
 ### Public API (`src/sqlseed/__init__.py`)
 
@@ -154,7 +155,7 @@ Run `pytest tests/test_doc_sync.py` to verify doc sync after changes.
 
 ## Testing
 
-- Fixtures in `tests/conftest.py`: `tmp_db` (users + orders tables), `tmp_db_with_data`, `unique_test_db`, `create_project_info_db()` (project_info table with unique indexes), `raw_adapter`, `raw_adapter_with_data`
+- Fixtures in `tests/conftest.py`: `tmp_db` (users + orders tables), `tmp_db_with_data`, `unique_test_db`, `create_project_info_db()` (project_info table with unique indexes), `raw_adapter`, `raw_adapter_with_data`. Helper: `make_column_info()` factory for `ColumnInfo` objects.
 - Use real SQLite via `tmp_path` fixture, never mock the database layer
 - CLI tests: use `click.testing.CliRunner`, never subprocess
 - AI plugin tests: `pytest.importorskip("sqlseed_ai")`
@@ -206,6 +207,6 @@ When preparing a new version release:
 
 ## Dependencies
 
-**Core**: sqlite-utils, pydantic, pluggy, structlog, pyyaml, click, rich, typing_extensions, simpleeval, rstr
-**Optional**: faker (`sqlseed[faker]`), mimesis (`sqlseed[mimesis]`)
+**Core**: pydantic, pluggy, structlog, pyyaml, click, rich, typing_extensions, simpleeval, rstr
+**Optional**: sqlite-utils (`sqlseed[sqlite-utils]`), faker (`sqlseed[faker]`), mimesis (`sqlseed[mimesis]`), tqdm (`sqlseed[tqdm]`)
 **Dev**: pytest, pytest-cov, pytest-asyncio, pytest-benchmark, ruff, mypy, pre-commit

GEMINI.md

@@ -23,9 +23,9 @@ Core features include:
 - **`src/sqlseed/plugins/`**: Plugin management and hook specification definitions based on `pluggy` (`hookspecs.py` and `manager.py`).
 - **`src/sqlseed/config/`**: Configuration management using `pydantic` models, YAML/JSON loader (`loader.py`, `models.py`), and runtime snapshots supporting CLI `replay` command (`snapshot.py`).
 - **`src/sqlseed/cli/`**: `click`-based command-line interface (`main.py` providing fill, preview, inspect, init, replay, ai-suggest).
-- **`src/sqlseed/_utils/`**: Internal utilities including SQL safety (`sql_safe.py`), shared schema helpers (`schema_helpers.py`), performance metrics collection (`metrics.py`), progress bar wrapper (`progress.py`, based on `rich`), and logging wrapper (`logger.py`, based on `structlog`).
+- **`src/sqlseed/_utils/`**: Internal utilities including SQL safety (`sql_safe.py`), shared schema helpers (`schema_helpers.py`), performance metrics collection (`metrics.py`), progress bar wrapper (`progress.py`, based on `rich`), logging wrapper (`logger.py`, based on `structlog`), and platform-aware cache directory path utilities (`paths.py`).
 - **`plugins/sqlseed-ai/`**: Standalone package providing OpenAI-compatible LLM-driven generation. Contains `analyzer.py` (LLM table-level analysis), `refiner.py` (self-correction loop), `errors.py` (error summary), `examples.py` (few-shot examples), `config.py` (AIConfig model), `_client.py` (API client), `_json_utils.py` (JSON parsing), and `_model_selector.py` (Gemma 4 model selection, multi-backend support).
-- **`plugins/mcp-server-sqlseed/`**: MCP server based on FastMCP providing one Resource (`sqlseed://schema/{db_path}/{table_name}`) and three core Tools (`sqlseed_inspect_schema`, `sqlseed_generate_yaml`, `sqlseed_execute_fill`) for seamless AI assistant integration (driven by `server.py` and `config.py`).
+- **`plugins/mcp-server-sqlseed/`**: MCP server based on FastMCP providing one Resource (`sqlseed://schema/{db_path}/{table_name}`) and six core Tools (`sqlseed_inspect_schema`, `sqlseed_generate_yaml`, `sqlseed_execute_fill`, `sqlseed_gemma4_analyze`, `sqlseed_gemma4_agent_fill`, `sqlseed_list_gemma_models`) for seamless AI assistant integration (driven by `server.py` and `config.py`).
 - **`examples/`**: Contains tutorial Jupyter notebooks (`notebooks/`) covering quickstart, column mapping, generators, DB association, expression/DAGs, AI configuration, MCP server, and testing patterns. Also includes demo DB builder script (`build_demo_db.py`).
 - **`docs/`**: Project documentation including architecture diagrams (`architecture.md`).
 

examples/notebooks/07-ai-plugin.ipynb

@@ -367,30 +367,23 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "偏好免费模型 (12 个):\n",
-      "  1. nvidia/nemotron-3-super-120b-a12b:free\n",
-      "  2. tencent/hy3-preview:free\n",
-      "  3. inclusionai/ling-2.6-1t:free\n",
-      "  4. inclusionai/ling-2.6-flash:free\n",
-      "  5. z-ai/glm-4.5-air:free\n",
-      "  6. minimax/minimax-m2.5:free\n",
-      "  7. openai/gpt-oss-120b:free\n",
-      "  8. nvidia/nemotron-3-nano-30b-a3b:free\n",
-      "  9. google/gemma-4-31b-it:free\n",
-      "  10. nvidia/nemotron-nano-9b-v2:free\n",
-      "  11. openai/gpt-oss-20b:free\n",
-      "  12. google/gemma-4-26b-a4b-it:free\n",
+      "Gemma 4 模型优先级 (5 个):\n",
+      "  1. gemma-4-31b-it (Gemma 4 31B Dense)\n",
+      "  2. gemma-4-26b-a4b-it (Gemma 4 26B A4B MoE (Recommended))\n",
+      "  3. gemma-4-12b-it (Gemma 4 12B Unified (Laptop))\n",
+      "  4. gemma-4-e4b-it (Gemma 4 E4B (4B Effective, Edge))\n",
+      "  5. gemma-4-e2b-it (Gemma 4 E2B (2B Effective, Edge))\n",
       "\n",
-      "select_best_free_model() 按优先级尝试, 自动回退\n"
+      "select_gemma_model() 按优先级尝试, 自动回退\n"
      ]
     }
    ],
    "source": [
-    "from sqlseed_ai._model_selector import PREFERRED_FREE_MODELS\n",
+    "from sqlseed_ai._model_selector import _GEMMA_MODEL_PRIORITY\n",
     "\n",
-    "print(f'偏好免费模型 ({len(PREFERRED_FREE_MODELS)} 个):')\n",
-    "for i, model in enumerate(PREFERRED_FREE_MODELS, 1):\n",
-    "    print(f'  {i}. {model}')\n",
+    "print(f'Gemma 4 模型优先级 ({len(_GEMMA_MODEL_PRIORITY)} 个):')\n",
+    "for i, model in enumerate(_GEMMA_MODEL_PRIORITY, 1):\n",
+    "    print(f'  {i}. {model.value} ({model.display_name})')\n",
     "\n",
     "print('\\nselect_gemma_model() 按优先级尝试, 自动回退')\n",
     "\n"

plugins/mcp-server-sqlseed/AGENTS.md

@@ -13,7 +13,7 @@ mcp-server-sqlseed/
     ├── __init__.py                   # main() entry point
     ├── __main__.py                   # python -m support
     ├── config.py                     # MCPServerConfig (Pydantic)
-    └── server.py                     # FastMCP server, 3 tools (190 lines)
+    └── server.py                     # FastMCP server, 6 tools (349 lines)
 ```
 
 ## WHERE TO LOOK

plugins/mcp-server-sqlseed/src/mcp_server_sqlseed/AGENTS.md

@@ -31,6 +31,9 @@ FastMCP 服务器实现。为 AI 助手提供 sqlseed 的数据生成工具。
 | `sqlseed_inspect_schema` | `db_path: str`, `table_name: str | None = None` | `dict[str, Any]` | 检查数据库 schema（含 schema_hash） |
 | `sqlseed_generate_yaml` | `db_path: str`, `table_name: str`, `max_retries: int = 3`, `api_key: str | None = None`, `base_url: str | None = None`, `model: str | None = None` | `str` (YAML 或错误文本) | AI 生成 YAML 配置 |
 | `sqlseed_execute_fill` | `db_path: str`, `table_name: str`, `count: int = 1000`, `yaml_config: str | None = None`, `enrich: bool = False` | `dict[str, Any]` | 执行数据填充 |
+| `sqlseed_gemma4_analyze` | `db_path: str`, `table_name: str`, `model: str | None = None`, `backend: str | None = None` | `dict[str, Any]` | Gemma 4 分析表结构并推荐配置 |
+| `sqlseed_gemma4_agent_fill` | `db_path: str`, `table_name: str`, `count: int = 1000`, `model: str | None = None`, `backend: str | None = None`, `max_retries: int = 3` | `dict[str, Any]` | Gemma 4 端到端：分析→生成→填充 |
+| `sqlseed_list_gemma_models` | (无参数) | `dict[str, Any]` | 列出 Gemma 4 模型变体和后端 |
 
 - `_validate_db_path()` 验证扩展名必须为 `.db`、`.sqlite` 或 `.sqlite3`
 - `_MAX_YAML_CONFIG_SIZE = 256 * 1024`（256KB）限制 YAML 配置大小

plugins/sqlseed-ai/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## OVERVIEW
 
-LLM-powered schema analysis and template generation. Separate package with own pyproject.toml.
+LLM-powered schema analysis and template generation. Separate package with own pyproject.toml. Supports 4 backends (Google AI Studio, LM Studio, Ollama, OpenAI-compatible) and 5 Gemma 4 model variants.
 
 ## STRUCTURE
 
@@ -11,24 +11,26 @@ sqlseed-ai/
 ├── pyproject.toml        # Separate package: sqlseed>=0.1.0, openai>=1.0
 └── src/sqlseed_ai/
     ├── __init__.py       # AISqlseedPlugin, plugin instance, hookimpl registration
-    ├── analyzer.py       # SchemaAnalyzer — LLM schema analysis
-    ├── refiner.py        # AiConfigRefiner — post-generation refinement and self-correction loop
-    ├── config.py         # AIConfig — env-based OpenAI config
-    ├── errors.py         # Custom exceptions
-    ├── _client.py        # OpenAI client wrapper
-    ├── _model_selector.py # Model selection logic
-    ├── _json_utils.py    # JSON parsing utilities
-    └── examples.py       # Usage examples
+    ├── analyzer.py       # SchemaAnalyzer — LLM schema analysis, streaming, tool calling
+    ├── refiner.py        # AiConfigRefiner — post-generation refinement, self-correction, streaming
+    ├── config.py         # AIConfig — env-based config, GemmaModel enum, AIBackend enum
+    ├── errors.py         # Error classification (7 processors)
+    ├── _client.py        # OpenAI client wrapper, httpx timeout config
+    ├── _model_selector.py # Gemma 4 model selection and fallback chain
+    ├── _json_utils.py    # JSON parsing utilities (3-strategy fallback)
+    └── examples.py       # Few-shot examples for prompts
 ```
 
 ## WHERE TO LOOK
 
 | Task | Location | Notes |
 |------|----------|-------|
 | Add hook | `__init__.py` | Decorate with `@hookimpl` |
-| Modify LLM calls | `_client.py` | OpenAI client wrapper |
-| Change model selection | `_model_selector.py` | Model picker logic |
-| Add config option | `config.py` | AIConfig.from_env() |
+| Modify LLM calls | `analyzer.py` | `call_llm()`, `call_llm_streaming()`, `_call_llm_once()` |
+| Change model selection | `_model_selector.py` | `select_gemma_model()`, `select_next_gemma_model()` |
+| Add config option | `config.py` | `AIConfig.from_env()`, `GemmaModel`, `AIBackend` |
+| Modify prompt templates | `analyzer.py` | `_SYSTEM_PROMPT`, `_COMPACT_SYSTEM_PROMPT`, `_ULTRA_COMPACT_SYSTEM_PROMPT` |
+| Change error handling | `errors.py` | `summarize_error()` with 7 processors |
 
 ## CONVENTIONS
 
@@ -44,3 +46,22 @@ sqlseed-ai/
 - **NEVER** raise from hook methods → return None on failure
 - **ALWAYS** use `AIConfig.from_env()` for configuration
 - **ALWAYS** cap template generation at 50 values (`min(count, 50)`)
+
+## Gemma 4 Model Variants
+
+| Enum | Model ID | Use Case |
+|------|----------|----------|
+| `GEMMA_4_E2B` | `gemma-4-e2b-it` | Ultra-light edge, Ollama/LM Studio |
+| `GEMMA_4_E4B` | `gemma-4-e4b-it` | Lightweight local, LM Studio |
+| `GEMMA_4_12B` | `gemma-4-12b-it` | Balanced, LM Studio/Ollama |
+| `GEMMA_4_26B_A4B` | `gemma-4-26b-a4b-it` | High quality, recommended |
+| `GEMMA_4_31B` | `gemma-4-31b-it` | Best quality, Google AI Studio |
+
+## Backend Configuration
+
+| Backend | Default Base URL | Notes |
+|---------|-----------------|-------|
+| `google_ai_studio` | `https://generativelanguage.googleapis.com/v1beta/openai/` | Cloud, supports tool calling |
+| `lm_studio` | `http://127.0.0.1:1234/v1` | Local, auto-detect models |
+| `ollama` | `http://localhost:11434/v1` | Local, offline |
+| `openai_compat` | (must set `SQLSEED_AI_BASE_URL`) | Generic OpenAI-compatible |

plugins/sqlseed-ai/src/sqlseed_ai/AGENTS.md

@@ -15,7 +15,7 @@ AI 数据生成插件的实现。通过 OpenAI 兼容 API 分析数据库模式
 | `refiner.py` | `AiConfigRefiner` 配置优化器，基于 AI 建议优化现有配置，支持自纠正 |
 | `config.py` | `AIConfig` AI 配置（API key, model, base_url 等），支持环境变量 |
 | `_client.py` | OpenAI 客户端工厂，支持自定义 base_url |
-| `_model_selector.py` | `select_next_free_model()` 免费模型自动选择与降级 |
+| `_model_selector.py` | `select_next_gemma_model()` Gemma 模型自动选择与降级 |
 | `_json_utils.py` | JSON 响应容错解析，`_sanitize_names()` 名称清洗 |
 | `errors.py` | 错误类型定义，`ErrorSummary`/`summarize_error()` 错误汇总 |
 | `examples.py` | Few-shot 示例，用于 AI 提示词 |
@@ -25,10 +25,11 @@ AI 数据生成插件的实现。通过 OpenAI 兼容 API 分析数据库模式
 
 | 环境变量 | 字段 | 回退 |
 |----------|------|------|
-| `SQLSEED_AI_API_KEY` | `api_key` | `OPENAI_API_KEY` |
-| `SQLSEED_AI_BASE_URL` | `base_url` | `OPENAI_BASE_URL` |
-| `SQLSEED_AI_MODEL` | `model` | 无 |
+| `SQLSEED_AI_API_KEY` | `api_key` | `GOOGLE_API_KEY` → `OPENAI_API_KEY` |
+| `SQLSEED_AI_BASE_URL` | `base_url` | `OPENAI_BASE_URL`（按后端自动设置） |
+| `SQLSEED_AI_MODEL` | `model` | 无（自动检测本地模型） |
 | `SQLSEED_AI_TIMEOUT` | `timeout` | 默认 60.0 |
+| `SQLSEED_AI_BACKEND` | `backend` | 自动检测（`google_ai_studio`, `lm_studio`, `ollama`, `openai_compat`） |
 
 ## LLM 调用与回退机制
 
@@ -65,13 +66,15 @@ AI 数据生成插件的实现。通过 OpenAI 兼容 API 分析数据库模式
 
 ### Working In This Directory
 
-- `AISqlseedPlugin` 实现 `hookimpl`：`sqlseed_ai_analyze_table`（分析整张表）和 `sqlseed_pre_generate_templates`（为非简单列生成模板值）
+- `AISqlseedPlugin` 实现 `hookimpl`：`sqlseed_ai_analyze_table`（分析整张表）和 `sqlseed_pre_generate_templates`（为非简单列生成模板值）。不实现 `sqlseed_register_providers` 或 `sqlseed_register_column_mappers`
 - 简单列（name, email, phone 等）通过 `_SIMPLE_COL_RE` 正则跳过 AI 调用，不要为简单列浪费 LLM token
-- `_model_selector.py` 维护免费模型列表，自动选择可用模型，支持降级，模型列表可能需要定期更新
-- JSON 解析必须使用 `_json_utils.py` 的容错逻辑，不要直接 `json.loads`，LLM 返回的 JSON 格式可能不规范
+- `_model_selector.py` 维护 Gemma 4 模型列表，`select_gemma_model()` 自动选择，`select_next_gemma_model()` 降级
+- JSON 解析必须使用 `_json_utils.py` 的容错逻辑（3 策略：直接解析 → 围栏清理 → raw_decode），不要直接 `json.loads`
 - 所有 AI 调用需处理 `APIConnectionError`/`APITimeoutError`/`APIError`
 - `refiner.py` 的自纠正流程：生成 → 验证 → 修正，最多重试若干次
-- `config.py` 的 `AIConfig` 支持环境变量（`SQLSEED_AI_API_KEY`, `SQLSEED_AI_MODEL`, `SQLSEED_AI_BASE_URL`）
+- `config.py` 的 `AIConfig` 支持多后端自动检测，关键方法：`resolve_model()`, `resolve_base_url()`, `resolve_api_key()`, `resolve_max_tokens()`, `should_use_streaming()`, `should_use_ultra_compact()`
+- 流式调用：`call_llm_streaming()` + `generate_and_refine_streaming()`，E2B/E4B 模型自动禁用流式
+- Prompt 降级：normal → compact → ultra-compact，小模型（E2B/E4B）自动启用 ultra-compact
 
 ### Testing Requirements