feat(ai): integrate Gemma 4 with Native Function Calling and multi-backend support

- Add Gemma 4 model registry (2B/4B/26B/31B) and AIBackend enum (Google AI Studio, LM Studio, Ollama, OpenAI-compatible)

- Implement Native Function Calling via GEMMA_TOOLS (analyze_schema, generate_column_values) with auto-fallback to JSON mode

- Add AIConfig.resolve_base_url()/resolve_api_key()/to_openai_kwargs() for unified client construction

- Add 3 Gemma 4 MCP tools: gemma4_analyze, gemma4_agent_fill, list_gemma_models

- Add cross-platform quickstart.py script with LM Studio/Ollama auto-detection

- Fix CLI api_key check for backends that don't require API keys

- Extract _resolve_backend(), _build_ai_config(), _extract_tool_call_result() to reduce complexity

- Update all markdown docs with Gemma 4 multi-backend documentation

- Add gemma4-integration.md (EN + zh-CN) showcase docs

Author: sunbos

AGENTS.md

@@ -6,7 +6,7 @@
 
 ## OVERVIEW
 
-Declarative SQLite test data generation toolkit. YAML/JSON config or Python API. Auto-infers schema, 9-level column mapping, 31 generators, plugin system (pluggy).
+Declarative SQLite test data generation toolkit. YAML/JSON config or Python API. Auto-infers schema, 9-level column mapping, 31 generators, plugin system (pluggy). Gemma 4 Native Function Calling for AI-powered schema analysis.
 
 **Stack**: Python 3.10+, hatchling build, ruff lint, mypy strict, pytest.
 
@@ -42,8 +42,8 @@ sqlseed/
 | Modify schema inference | `src/sqlseed/core/schema.py` | SchemaInferrer class |
 | Change batch insert | `src/sqlseed/database/` | Two adapters: raw, sqlite-utils |
 | Add test fixture | `tests/conftest.py` | tmp_db, tmp_db_with_data, unique_test_db |
-| Configure AI plugin | `plugins/sqlseed-ai/` | Separate pyproject.toml |
-| Add MCP tool | `plugins/mcp-server-sqlseed/` | FastMCP decorators |
+| Configure AI plugin | `plugins/sqlseed-ai/` | Separate pyproject.toml, Gemma 4 multi-backend (Google AI Studio, LM Studio, Ollama) |
+| Add MCP tool | `plugins/mcp-server-sqlseed/` | FastMCP decorators, 3 Gemma 4 tools: gemma4_analyze, gemma4_agent_fill, list_gemma_models |
 
 ## CONVENTIONS
 
@@ -65,6 +65,8 @@ sqlseed/
 ## UNIQUE STYLES
 
 - **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
 - **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

CHANGELOG.md

@@ -119,7 +119,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `ColumnMapper` exact match rules expanded from 68 to 74
 
 #### AI Plugin (sqlseed-ai)
-- Auto model selection: `_model_selector` picks the best free model from OpenRouter by priority
+- Auto model selection: `_model_selector` picks the best Gemma 4 model by priority (26B MoE → 31B Dense → 4B → 2B), with multi-backend support (Google AI Studio, LM Studio, Ollama)
 - Structured output: `response_format: json_object` forces LLM to return JSON
 - Few-shot example library: 4 typical scenarios (users, projects, orders, employees)
 - `AiConfigRefiner` self-correction loop: auto-detects and fixes invalid configs, up to 3 retries

CHANGELOG.zh-CN.md

@@ -119,7 +119,7 @@
 - `ColumnMapper` 精确匹配规则从 68 扩展到 74 条
 
 #### AI 插件（sqlseed-ai）
-- 自动模型选择：`_model_selector` 从 OpenRouter 免费模型列表中按优先级自动选择
+- 自动模型选择：`_model_selector` 按 Gemma 4 优先级自动选择（26B MoE → 31B Dense → 4B → 2B），支持多后端（Google AI Studio、LM Studio、Ollama）
 - 结构化输出：`response_format: json_object` 强制 LLM 返回 JSON
 - Few-shot 示例库：4 个典型场景（用户表、银行卡表、订单表、员工表）
 - `AiConfigRefiner` 自纠正闭环：自动检测并修复无效配置，最多 3 轮重试

CLAUDE.md

@@ -201,7 +201,7 @@ When preparing a new version release:
 
 ## Plugins (separate packages)
 
-- `plugins/sqlseed-ai/` — LLM-powered schema analysis via OpenRouter. Has its own `pyproject.toml`. Install: `pip install -e "./plugins/sqlseed-ai"`
+- `plugins/sqlseed-ai/` — LLM-powered schema analysis via Gemma 4 (Google AI Studio, LM Studio, Ollama). Has its own `pyproject.toml`. Install: `pip install -e "./plugins/sqlseed-ai"`
 - `plugins/mcp-server-sqlseed/` — MCP server for schema inspect, AI YAML gen, fill. Install: `pip install -e "./plugins/mcp-server-sqlseed"`
 
 ## Dependencies

GEMINI.md

@@ -24,7 +24,7 @@ Core features include:
 - **`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`).
-- **`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), `provider.py` (AI provider compatibility stub), `config.py` (AIConfig model), `_client.py` (API client), `_json_utils.py` (JSON parsing), and `_model_selector.py` (auto model selection from OpenRouter).
+- **`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), `provider.py` (AI provider compatibility stub), `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`).
 - **`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`).

README.md

@@ -180,6 +180,12 @@ mypy src/sqlseed/
 
 ## 🚀 Quick Start
 
+### Interactive Quickstart
+
+```bash
+python scripts/quickstart.py
+```
+
 ### Try with Demo Database
 
 Want to try sqlseed right away? Build the demo database:
@@ -652,17 +658,34 @@ pip install sqlseed-ai
 
 # Set API key
 export SQLSEED_AI_API_KEY="your-api-key"
-export SQLSEED_AI_BASE_URL="https://your-llm-api-endpoint"
 
 # AI analysis and config generation
 sqlseed ai-suggest app.db --table projects --output projects.yaml
 
 # AI suggestions with self-correction (3 rounds by default)
 sqlseed ai-suggest app.db --table projects --output projects.yaml --verify
 
-# Specify model (defaults to most popular free model)
-sqlseed ai-suggest app.db --table projects --output projects.yaml --model nvidia/nemotron-3-super-120b-a12b:free
+# Specify model (defaults to Gemma 4 26B via Google AI Studio)
+sqlseed ai-suggest app.db --table projects --output projects.yaml --model gemma-4-26b-it
+
+# Use local LM Studio / Ollama
+sqlseed ai-suggest app.db --table projects --output projects.yaml --backend lm_studio --model google/gemma-4-e4b
+```
 
+**Gemma 4 Native Function Calling (GEMMA_TOOLS)**:
+
+sqlseed-ai supports Gemma 4 model family (2B/4B/26B/31B) with Native Function Calling via GEMMA_TOOLS protocol. Supported backends:
+
+| Backend | Description | Configuration |
+| :------ | :---------- | :------------ |
+| **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 (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
 sqlseed ai-suggest app.db --table projects --output projects.yaml --no-cache
 ```
@@ -678,7 +701,7 @@ sqlseed ai-suggest app.db --table projects --output projects.yaml --no-cache
 6. Up to 3 self-correction rounds, outputs validated YAML config
 ```
 
-> **💡 Environment Variables**: Supports `SQLSEED_AI_API_KEY`, `SQLSEED_AI_BASE_URL`, `SQLSEED_AI_MODEL`. Also supports `OPENAI_API_KEY` / `OPENAI_BASE_URL` as fallback. Defaults to auto-selecting the most popular free model from OpenRouter (base_url `https://openrouter.ai/api/v1`). Set `--model` or `SQLSEED_AI_MODEL` to specify a model.
+> **💡 Environment Variables**: Supports `SQLSEED_AI_API_KEY`, `SQLSEED_AI_BASE_URL`, `SQLSEED_AI_MODEL`, `SQLSEED_AI_BACKEND`. Also supports `OPENAI_API_KEY` / `OPENAI_BASE_URL` as fallback. Defaults to Gemma 4 26B via Google AI Studio. Supported backends: `google_ai_studio`, `lm_studio`, `ollama`, `openai_compat`.
 
 ***
 
@@ -717,6 +740,9 @@ python -m mcp_server_sqlseed
 | 🔍 Tool | `sqlseed_inspect_schema` | Inspect schema (columns, FK, indexes, samples, schema_hash) |
 | 🤖 Tool | `sqlseed_generate_yaml` | AI-driven YAML config generation with self-correction. Supports `api_key`/`base_url`/`model` overrides |
 | ⚡ Tool | `sqlseed_execute_fill` | Execute data generation (supports YAML config string, includes `enrich` option) |
+| 🧠 Tool | `sqlseed_gemma4_analyze` | Analyze schema using Gemma 4 with Native Function Calling |
+| 🧠 Tool | `sqlseed_gemma4_agent_fill` | End-to-end Agent workflow (analyze -> config -> fill) |
+| 🧠 Tool | `sqlseed_list_gemma_models` | List available Gemma 4 models and backend status |
 
 This means you can tell your AI assistant:
 
@@ -993,7 +1019,7 @@ Tests cover all core modules, with path structure mirroring `src/`: `test_core/`
 | `sqlseed[faker]` | + faker>=30.0 | Faker data engine |
 | `sqlseed[mimesis]` | + mimesis>=18.0 | Mimesis data engine (recommended) |
 | `sqlseed[docs]` | + mkdocs-material, mkdocstrings | Documentation build |
-| `sqlseed-ai` | sqlseed, **openai>=1.0** | AI plugin, auto-registered via entry-point |
+| `sqlseed-ai` | sqlseed, **openai>=1.0**, **google-generativeai>=0.8** | AI plugin (Gemma 4 Native Function Calling), auto-registered via entry-point |
 | `mcp-server-sqlseed` | sqlseed, **mcp>=1.0** | MCP server, standalone CLI tool |
 | `mcp-server-sqlseed[ai]` | + sqlseed-ai | MCP server with AI support |
 

README.zh-CN.md

@@ -178,6 +178,14 @@ mypy src/sqlseed/
 
 ## 🚀 快速开始
 
+### 一键体验脚本
+
+```bash
+python scripts/quickstart.py
+```
+
+该脚本会自动创建示例数据库、填充数据并展示结果，适合首次体验。
+
 ### 使用示例数据库体验
 
 想立即体验 sqlseed？构建示例数据库：
@@ -553,22 +561,27 @@ sqlseed ai-suggest app.db --table projects --output projects.yaml
 # 带自纠正的 AI 建议（默认 3 轮修正）
 sqlseed ai-suggest app.db --table projects --output projects.yaml --verify
 
-# 指定模型
-sqlseed ai-suggest app.db --table projects -o projects.yaml --model deepseek/deepseek-chat
+# 指定模型（支持多后端：Google AI Studio、LM Studio、Ollama、OpenAI-compatible）
+sqlseed ai-suggest app.db --table projects -o projects.yaml --model gemma-4-26b-it --backend google_ai_studio
+sqlseed ai-suggest app.db --table projects -o projects.yaml --model gemma-4-31b-it --backend google_ai_studio
+sqlseed ai-suggest app.db --table projects -o projects.yaml --model google/gemma-4-e4b --backend lm_studio
+sqlseed ai-suggest app.db --table projects -o projects.yaml --model gemma-4-4b-it --backend ollama
 ```
 
-**AI 工作流程**：
+**Gemma 4 原生函数调用（GEMMA_TOOLS）**：
 
-```
-1. 提取 Schema 上下文（列信息、索引、样本数据、外键、数据分布）
-2. 构建带 Few-shot 示例的 LLM Prompt
-3. LLM 返回 JSON 格式的列配置建议
-4. AiConfigRefiner 自动验证配置的正确性
-5. 若发现错误，自动向 LLM 发送修正请求
-6. 最多 3 轮自纠正，输出经过验证的 YAML 配置
-```
+sqlseed-ai 支持 Gemma 4 系列模型（2B/4B/26B/31B）通过 GEMMA_TOOLS 协议实现原生函数调用，无需 JSON Mode 模拟。支持的后端：
+
+| 后端 | 说明 | 配置方式 |
+| :--- | :--- | :--- |
+| **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 兼容端点（如 OpenRouter、DeepSeek） | `--backend openai_compat` 或 `SQLSEED_AI_BACKEND=openai_compat` |
 
-> **💡 环境变量**：支持 `SQLSEED_AI_API_KEY`、`SQLSEED_AI_BASE_URL`、`SQLSEED_AI_MODEL`。也支持 `OPENAI_API_KEY` / `OPENAI_BASE_URL` 作为回退。
+> **💡 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` 作为回退。
 
 ***
 
@@ -598,6 +611,9 @@ pip install mcp-server-sqlseed[ai]
 | 🔍 Tool | `sqlseed_inspect_schema` | 检查 Schema（列、外键、索引、样本数据、schema_hash） |
 | 🤖 Tool | `sqlseed_generate_yaml` | AI 驱动的 YAML 配置生成（含自纠正） |
 | ⚡ Tool | `sqlseed_execute_fill` | 执行数据生成（支持 YAML 配置字符串，含 `enrich` 选项） |
+| 🤖 Tool | `sqlseed_gemma4_analyze` | Gemma 4 原生函数调用分析 Schema（GEMMA_TOOLS 协议） |
+| 🤖 Tool | `sqlseed_gemma4_agent_fill` | Gemma 4 Agent 模式端到端数据生成（分析→配置→填充） |
+| 📋 Tool | `sqlseed_list_gemma_models` | 列出可用的 Gemma 4 模型及后端支持情况 |
 
 ***
 
@@ -679,6 +695,12 @@ sqlseed ai-suggest app.db -t users -o users.yaml --verify
 sqlseed ai-suggest app.db -t users -o users.yaml --api-key sk-xxx --base-url https://api.openai.com/v1
 sqlseed ai-suggest app.db -t users -o users.yaml --max-retries 0
 sqlseed ai-suggest app.db -t users -o users.yaml --no-cache
+
+# ═══ AI 后端选择 ═══
+sqlseed ai-suggest app.db -t users -o users.yaml --backend google_ai_studio --model gemma-4-26b-it
+sqlseed ai-suggest app.db -t users -o users.yaml --backend ollama --model gemma-4-4b-it
+sqlseed ai-suggest app.db -t users -o users.yaml --backend lm_studio --model google/gemma-4-e4b
+sqlseed ai-suggest app.db -t users -o users.yaml --backend openai_compat --model your-model --base-url https://your-api-endpoint
 ```
 
 ***
@@ -805,7 +827,7 @@ mypy src/sqlseed/                   # 类型检查
 | `sqlseed[faker]` | + faker>=30.0 | Faker 数据引擎 |
 | `sqlseed[mimesis]` | + mimesis>=18.0 | Mimesis 数据引擎（推荐） |
 | `sqlseed[docs]` | + mkdocs-material, mkdocstrings | 文档构建 |
-| `sqlseed-ai` | sqlseed, **openai>=1.0** | AI 插件，通过 entry-point 自动注册 |
+| `sqlseed-ai` | sqlseed, **openai>=1.0**, **google-generativeai>=0.8** | AI 插件，通过 entry-point 自动注册，支持 Gemma 4 GEMMA_TOOLS |
 | `mcp-server-sqlseed` | sqlseed, **mcp>=1.0** | MCP 服务器，独立 CLI 工具 |
 | `mcp-server-sqlseed[ai]` | + sqlseed-ai | MCP 服务器含 AI 支持 |
 

docs/architecture.md

@@ -62,6 +62,9 @@ graph TB
         Refiner["AiConfigRefiner<br/>self-correction loop"]
         Examples["Few-shot<br/>example library"]
         Errors["ErrorSummary<br/>error classification"]
+        GemmaModel["GemmaModel<br/>Gemma 4 model adapter"]
+        AIBackend["AIBackend<br/>multi-backend router"]
+        GemmaTools["GEMMA_TOOLS<br/>Native Function Calling"]
     end
 
     subgraph Utils["🔧 Utilities (_utils/)"]
@@ -115,6 +118,9 @@ graph TB
     Analyzer --> Refiner
     Refiner --> Errors
     Analyzer --> Examples
+    AIBackend --> GemmaModel
+    AIBackend --> Analyzer
+    GemmaModel --> GemmaTools
 
     Orch --> Config
 
@@ -426,13 +432,15 @@ flowchart TB
         CLICmd["sqlseed ai-suggest"]
         HookCall["sqlseed_ai_analyze_table Hook"]
         MCPTool["MCP: sqlseed_generate_yaml"]
+        MCPGemma4Analyze["MCP: sqlseed_gemma4_analyze"]
+        MCPGemma4AgentFill["MCP: sqlseed_gemma4_agent_fill"]
     end
 
     subgraph Analyzer["SchemaAnalyzer"]
         Context["Build context<br/>columns + indexes + FK + samples + distribution"]
         FewShot["Inject few-shot examples<br/>(4 typical scenarios)"]
         SysPrompt["System Prompt<br/>generator list + output format"]
-        LLM["Call LLM<br/>OpenAI-compatible API<br/>response_format: json_object"]
+        LLM["Call LLM<br/>AIBackend multi-backend<br/>OpenAI API / Gemma 4 GEMMA_TOOLS<br/>response_format: json_object"]
     end
 
     subgraph Refiner["AiConfigRefiner Self-Correction Loop"]
@@ -474,6 +482,8 @@ flowchart TB
     CLICmd --> Analyzer
     HookCall --> Analyzer
     MCPTool --> Analyzer
+    MCPGemma4Analyze --> Analyzer
+    MCPGemma4AgentFill --> Analyzer
 
     Context --> FewShot --> SysPrompt --> LLM
     LLM --> Refiner
@@ -625,6 +635,9 @@ flowchart LR
         Tool1["🔍 sqlseed_inspect_schema<br/>Returns: columns + FK + indexes + samples + hash"]
         Tool2["🤖 sqlseed_generate_yaml<br/>AI analysis → self-correction → YAML"]
         Tool3["⚡ sqlseed_execute_fill<br/>Execute data generation"]
+        Tool4["💎 sqlseed_gemma4_analyze<br/>Gemma 4 native function calling analysis"]
+        Tool5["💎 sqlseed_gemma4_agent_fill<br/>Gemma 4 agent-driven data fill"]
+        Tool6["💎 sqlseed_gemma4_suggest<br/>Gemma 4 column mapping suggestions"]
     end
 
     subgraph SQLSeed["sqlseed Core"]
@@ -641,11 +654,77 @@ flowchart LR
     Request --> Tool1
     Request --> Tool2
     Request --> Tool3
+    Request --> Tool4
+    Request --> Tool5
+    Request --> Tool6
 
     Resource --> SchemaCtx
     Tool1 --> SchemaCtx
     Tool2 --> SA --> ACR
     Tool3 --> Orchestrator
+    Tool4 --> SA
+    Tool5 --> Orchestrator
+    Tool6 --> SA
 
     SchemaCtx --> Orchestrator
 ```
+
+---
+
+## 11. Gemma 4 Integration Architecture
+
+```mermaid
+flowchart TB
+    subgraph MCPEntry["MCP Tool Entry Points"]
+        G4Analyze["💎 sqlseed_gemma4_analyze<br/>Schema analysis via Gemma 4"]
+        G4AgentFill["💎 sqlseed_gemma4_agent_fill<br/>Agent-driven data fill"]
+        G4Suggest["💎 sqlseed_gemma4_suggest<br/>Column mapping suggestions"]
+    end
+
+    subgraph Backend["AIBackend Multi-Backend Router"]
+        Router["AIBackend<br/>backend selection"]
+        OpenAIBe["OpenAI Backend<br/>chat.completions API"]
+        GemmaBe["Gemma 4 Backend<br/>GEMMA_TOOLS Native FC"]
+    end
+
+    subgraph GemmaFC["GEMMA_TOOLS Native Function Calling"]
+        ToolReg["Tool Registration<br/>auto_register(sqlseed tools)"]
+        FCRequest["Function Call Request<br/>model generates tool_call"]
+        FCExec["Tool Execution<br/>sqlseed core executes"]
+        FCResult["Result Injection<br/>tool_result → conversation"]
+        FCIterate["Iterative Refinement<br/>multi-turn tool use"]
+    end
+
+    subgraph Core["sqlseed Core Integration"]
+        SchemaCtx["get_schema_context()"]
+        Orchestrator["DataOrchestrator"]
+        Mapper["ColumnMapper"]
+    end
+
+    G4Analyze --> Router
+    G4AgentFill --> Router
+    G4Suggest --> Router
+
+    Router --> OpenAIBe
+    Router --> GemmaBe
+
+    GemmaBe --> ToolReg
+    ToolReg --> FCRequest
+    FCRequest --> FCExec
+    FCExec --> FCResult
+    FCResult --> FCIterate
+    FCIterate --> FCRequest
+
+    FCExec --> SchemaCtx
+    FCExec --> Orchestrator
+    FCExec --> Mapper
+
+    SchemaCtx --> Orchestrator
+
+    style GemmaBe fill:#4285F4,color:#fff
+    style ToolReg fill:#34A853,color:#fff
+    style FCRequest fill:#34A853,color:#fff
+    style FCExec fill:#FBBC05,color:#000
+    style FCResult fill:#34A853,color:#fff
+    style FCIterate fill:#EA4335,color:#fff
+```