sqlseed-ai 0.2.1__tar.gz → 0.2.3__tar.gz

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/.gitignore

@@ -33,6 +33,7 @@ ENV/
 .idea/
 .trae/
 .claude/
+.gemini/
 .sonarlint/
 *.swp
 *.swo
@@ -62,6 +63,9 @@ examples/notebooks/batch_config.yaml
 *.nbconvert.ipynb
 .ipynb_checkpoints/
 
+# AI-generated config outputs
+*_config.yaml
+
 # OS
 .DS_Store
 

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlseed-ai
-Version: 0.2.1
+Version: 0.2.3
 Summary: AI-powered data generation plugin for sqlseed
 Project-URL: Homepage, https://github.com/sunbos/sqlseed
 Project-URL: Repository, https://github.com/sunbos/sqlseed/tree/main/plugins/sqlseed-ai
@@ -14,7 +14,6 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
-Requires-Dist: google-generativeai>=0.8
 Requires-Dist: openai>=1.0
 Requires-Dist: sqlseed>=0.0.1
 Description-Content-Type: text/markdown
@@ -46,7 +45,7 @@ sqlseed ai-suggest app.db --table users --output users.yaml
 sqlseed ai-suggest app.db --table users --output users.yaml --verify
 
 # Specify model (defaults to Gemma 4 26B via Google AI Studio)
-sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-it
+sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-a4b-it
 
 # Use local LM Studio
 sqlseed ai-suggest app.db --table users -o users.yaml --backend lm_studio --model google/gemma-4-e4b
@@ -73,7 +72,7 @@ sqlseed ai-suggest app.db --table users -o users.yaml --no-cache
 
 When using the `google_ai_studio` backend (default), the `GemmaModel` enum provides pre-configured Gemma 4 variants. The model is selected based on the backend:
 
-1. **Google AI Studio**: Defaults to `gemma-4-26b-it` (recommended balance of quality and speed).
+1. **Google AI Studio**: Defaults to `gemma-4-26b-a4b-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** (OpenRouter, DeepSeek, etc.): User must specify both `--model` and `--base-url`.
 
@@ -90,10 +89,11 @@ When using the `google_ai_studio` backend, the `GemmaModel` enum provides pre-co
 
 | Enum Value | Model ID | Description |
 |:-----------|:---------|:------------|
-| `GemmaModel.GEMMA_4_2B` | `gemma-4-2b` | Lightweight, fast inference |
-| `GemmaModel.GEMMA_4_4B` | `gemma-4-4b` | Balanced speed and quality |
-| `GemmaModel.GEMMA_4_26B` | `gemma-4-26b` | High quality, recommended |
-| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b` | Best quality, largest model |
+| `GemmaModel.GEMMA_4_E2B` | `gemma-4-e2b-it` | 2B Effective, Edge — Ultra-light edge deployment |
+| `GemmaModel.GEMMA_4_E4B` | `gemma-4-e4b-it` | 4B Effective, Edge — Lightweight local inference |
+| `GemmaModel.GEMMA_4_12B` | `gemma-4-12b-it` | 12B Unified, Laptop — Balanced quality and speed |
+| `GemmaModel.GEMMA_4_26B_A4B` | `gemma-4-26b-a4b-it` | 26B A4B MoE — High quality, recommended |
+| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b-it` | 31B Dense — Best quality, largest model |
 
 The `AIBackend` enum selects the API backend:
 
@@ -102,6 +102,7 @@ The `AIBackend` enum selects the API backend:
 | `AIBackend.GOOGLE_AI_STUDIO` | Google AI Studio | `https://generativelanguage.googleapis.com/v1beta/openai/` |
 | `AIBackend.LM_STUDIO` | LM Studio | `http://localhost:1234/v1` |
 | `AIBackend.OLLAMA` | Ollama | `http://localhost:11434/v1` |
+| `AIBackend.OPENAI_COMPAT` | OpenAI-compatible | (must set `SQLSEED_AI_BASE_URL`) |
 
 ### Template Pool
 
@@ -119,7 +120,7 @@ AI configs cached in platform-specific cache directory (`~/Library/Caches/sqlsee
 |:---------|:---------|:--------|:------------|
 | `SQLSEED_AI_API_KEY` | `OPENAI_API_KEY` | — | API key (required) |
 | `SQLSEED_AI_BASE_URL` | `OPENAI_BASE_URL` | (auto by backend) | API endpoint |
-| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-it` | Model name |
+| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-a4b-it` | Model name |
 | `SQLSEED_AI_TIMEOUT` | — | `60` | API timeout (seconds) |
 | `SQLSEED_AI_BACKEND` | — | `google_ai_studio` | AI backend: `google_ai_studio`, `lm_studio`, `ollama`, `openai_compat` |
 | `GOOGLE_API_KEY` | — | — | Google AI Studio API key (required when backend is `google_ai_studio`) |
@@ -152,7 +153,6 @@ This plugin registers via `[project.entry-points."sqlseed"]` and implements:
 - Python >= 3.10
 - `sqlseed >= 0.1.0`
 - `openai >= 1.0`
-- `google-generativeai >= 0.8`
 - An OpenAI-compatible API key or Google AI Studio API key
 
 ## Gemma 4 Integration

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/README.md

@@ -25,7 +25,7 @@ sqlseed ai-suggest app.db --table users --output users.yaml
 sqlseed ai-suggest app.db --table users --output users.yaml --verify
 
 # Specify model (defaults to Gemma 4 26B via Google AI Studio)
-sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-it
+sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-a4b-it
 
 # Use local LM Studio
 sqlseed ai-suggest app.db --table users -o users.yaml --backend lm_studio --model google/gemma-4-e4b
@@ -52,7 +52,7 @@ sqlseed ai-suggest app.db --table users -o users.yaml --no-cache
 
 When using the `google_ai_studio` backend (default), the `GemmaModel` enum provides pre-configured Gemma 4 variants. The model is selected based on the backend:
 
-1. **Google AI Studio**: Defaults to `gemma-4-26b-it` (recommended balance of quality and speed).
+1. **Google AI Studio**: Defaults to `gemma-4-26b-a4b-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** (OpenRouter, DeepSeek, etc.): User must specify both `--model` and `--base-url`.
 
@@ -69,10 +69,11 @@ When using the `google_ai_studio` backend, the `GemmaModel` enum provides pre-co
 
 | Enum Value | Model ID | Description |
 |:-----------|:---------|:------------|
-| `GemmaModel.GEMMA_4_2B` | `gemma-4-2b` | Lightweight, fast inference |
-| `GemmaModel.GEMMA_4_4B` | `gemma-4-4b` | Balanced speed and quality |
-| `GemmaModel.GEMMA_4_26B` | `gemma-4-26b` | High quality, recommended |
-| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b` | Best quality, largest model |
+| `GemmaModel.GEMMA_4_E2B` | `gemma-4-e2b-it` | 2B Effective, Edge — Ultra-light edge deployment |
+| `GemmaModel.GEMMA_4_E4B` | `gemma-4-e4b-it` | 4B Effective, Edge — Lightweight local inference |
+| `GemmaModel.GEMMA_4_12B` | `gemma-4-12b-it` | 12B Unified, Laptop — Balanced quality and speed |
+| `GemmaModel.GEMMA_4_26B_A4B` | `gemma-4-26b-a4b-it` | 26B A4B MoE — High quality, recommended |
+| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b-it` | 31B Dense — Best quality, largest model |
 
 The `AIBackend` enum selects the API backend:
 
@@ -81,6 +82,7 @@ The `AIBackend` enum selects the API backend:
 | `AIBackend.GOOGLE_AI_STUDIO` | Google AI Studio | `https://generativelanguage.googleapis.com/v1beta/openai/` |
 | `AIBackend.LM_STUDIO` | LM Studio | `http://localhost:1234/v1` |
 | `AIBackend.OLLAMA` | Ollama | `http://localhost:11434/v1` |
+| `AIBackend.OPENAI_COMPAT` | OpenAI-compatible | (must set `SQLSEED_AI_BASE_URL`) |
 
 ### Template Pool
 
@@ -98,7 +100,7 @@ AI configs cached in platform-specific cache directory (`~/Library/Caches/sqlsee
 |:---------|:---------|:--------|:------------|
 | `SQLSEED_AI_API_KEY` | `OPENAI_API_KEY` | — | API key (required) |
 | `SQLSEED_AI_BASE_URL` | `OPENAI_BASE_URL` | (auto by backend) | API endpoint |
-| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-it` | Model name |
+| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-a4b-it` | Model name |
 | `SQLSEED_AI_TIMEOUT` | — | `60` | API timeout (seconds) |
 | `SQLSEED_AI_BACKEND` | — | `google_ai_studio` | AI backend: `google_ai_studio`, `lm_studio`, `ollama`, `openai_compat` |
 | `GOOGLE_API_KEY` | — | — | Google AI Studio API key (required when backend is `google_ai_studio`) |
@@ -131,7 +133,6 @@ This plugin registers via `[project.entry-points."sqlseed"]` and implements:
 - Python >= 3.10
 - `sqlseed >= 0.1.0`
 - `openai >= 1.0`
-- `google-generativeai >= 0.8`
 - An OpenAI-compatible API key or Google AI Studio API key
 
 ## Gemma 4 Integration

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/README.zh-CN.md

@@ -25,7 +25,7 @@ sqlseed ai-suggest app.db --table users --output users.yaml
 sqlseed ai-suggest app.db --table users --output users.yaml --verify
 
 # 指定模型（默认使用 Gemma 4 26B via Google AI Studio）
-sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-it
+sqlseed ai-suggest app.db --table users -o users.yaml --model gemma-4-26b-a4b-it
 
 # 使用本地 LM Studio
 sqlseed ai-suggest app.db --table users -o users.yaml --backend lm_studio --model google/gemma-4-e4b
@@ -52,7 +52,7 @@ sqlseed ai-suggest app.db --table users -o users.yaml --no-cache
 
 使用 `google_ai_studio` 后端（默认）时，`GemmaModel` 枚举提供预配置的 Gemma 4 变体。模型根据后端自动选择：
 
-1. **Google AI Studio**：默认使用 `gemma-4-26b-it`（推荐的质量与速度平衡）。
+1. **Google AI Studio**：默认使用 `gemma-4-26b-a4b-it`（推荐的质量与速度平衡）。
 2. **LM Studio / Ollama**：用户需通过 `--model` 或 `SQLSEED_AI_MODEL` 指定已加载的模型。
 3. **OpenAI-compatible**（OpenRouter、DeepSeek 等）：用户需同时指定 `--model` 和 `--base-url`。
 
@@ -69,10 +69,11 @@ export SQLSEED_AI_MODEL=<免费模型名>
 
 | 枚举值 | 模型 ID | 说明 |
 |:-------|:--------|:-----|
-| `GemmaModel.GEMMA_4_2B` | `gemma-4-2b` | 轻量级，推理速度快 |
-| `GemmaModel.GEMMA_4_4B` | `gemma-4-4b` | 速度与质量均衡 |
-| `GemmaModel.GEMMA_4_26B` | `gemma-4-26b` | 高质量，推荐使用 |
-| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b` | 最佳质量，最大模型 |
+| `GemmaModel.GEMMA_4_E2B` | `gemma-4-e2b-it` | 2B Effective, Edge — 超轻量边缘部署 |
+| `GemmaModel.GEMMA_4_E4B` | `gemma-4-e4b-it` | 4B Effective, Edge — 轻量本地推理 |
+| `GemmaModel.GEMMA_4_12B` | `gemma-4-12b-it` | 12B Unified, Laptop — 速度与质量均衡 |
+| `GemmaModel.GEMMA_4_26B_A4B` | `gemma-4-26b-a4b-it` | 26B A4B MoE — 高质量，推荐使用 |
+| `GemmaModel.GEMMA_4_31B` | `gemma-4-31b-it` | 31B Dense — 最佳质量，最大模型 |
 
 `AIBackend` 枚举用于选择 API 后端：
 
@@ -81,6 +82,7 @@ export SQLSEED_AI_MODEL=<免费模型名>
 | `AIBackend.GOOGLE_AI_STUDIO` | Google AI Studio | `https://generativelanguage.googleapis.com/v1beta/openai/` |
 | `AIBackend.LM_STUDIO` | LM Studio | `http://localhost:1234/v1` |
 | `AIBackend.OLLAMA` | Ollama | `http://localhost:11434/v1` |
+| `AIBackend.OPENAI_COMPAT` | OpenAI 兼容端点 | （需设置 `SQLSEED_AI_BASE_URL`） |
 
 ### 模板池
 
@@ -98,7 +100,7 @@ AI 配置缓存在平台标准缓存目录（macOS: `~/Library/Caches/sqlseed/ai
 |:-----|:-----|:-------|:-----|
 | `SQLSEED_AI_API_KEY` | `OPENAI_API_KEY` | — | API Key（必填） |
 | `SQLSEED_AI_BASE_URL` | `OPENAI_BASE_URL` | （按后端自动设置） | API 端点 |
-| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-it` | 模型名称 |
+| `SQLSEED_AI_MODEL` | — | `gemma-4-26b-a4b-it` | 模型名称 |
 | `SQLSEED_AI_TIMEOUT` | — | `60` | API 超时（秒） |
 | `SQLSEED_AI_BACKEND` | — | `google_ai_studio` | AI 后端：`google_ai_studio`、`lm_studio`、`ollama`、`openai_compat` |
 | `GOOGLE_API_KEY` | — | — | Google AI Studio API Key（后端为 `google_ai_studio` 时必填） |
@@ -131,7 +133,6 @@ AI 配置缓存在平台标准缓存目录（macOS: `~/Library/Caches/sqlseed/ai
 - Python >= 3.10
 - `sqlseed >= 0.1.0`
 - `openai >= 1.0`
-- `google-generativeai >= 0.8`
 - OpenAI 兼容 API Key 或 Google AI Studio API Key
 
 ## Gemma 4 集成

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/pyproject.toml

@@ -24,7 +24,6 @@ classifiers = [
 dependencies = [
     "sqlseed>=0.0.1",
     "openai>=1.0",
-    "google-generativeai>=0.8",
 ]
 
 [project.urls]

{sqlseed_ai-0.2.1 → sqlseed_ai-0.2.3}/src/sqlseed_ai/__init__.py

@@ -65,13 +65,5 @@ class AISqlseedPlugin:
         except (ValueError, RuntimeError, OSError):
             return None
 
-    @hookimpl
-    def sqlseed_register_providers(self, registry: Any) -> None:
-        _ = registry
-
-    @hookimpl
-    def sqlseed_register_column_mappers(self, mapper: Any) -> None:
-        _ = mapper
-
 
 plugin = AISqlseedPlugin()

sqlseed_ai-0.2.3/src/sqlseed_ai/_client.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from openai import OpenAI
+from sqlseed_ai.config import AIBackend, AIConfig
+
+from sqlseed._utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def get_openai_client(config: AIConfig | None = None) -> Any:
+    if config is None:
+        config = AIConfig.from_env()
+
+    kwargs = config.to_openai_kwargs()
+    # For local backends, use a shorter connection timeout but longer read timeout.
+    # This prevents hanging on connection while allowing slow inference.
+    if config.backend in (AIBackend.LM_STUDIO, AIBackend.OLLAMA):
+        kwargs["timeout"] = httpx_timeout(config.resolve_timeout())
+    logger.info("Creating OpenAI client", **{"backend": config.backend.value, "base_url": kwargs["base_url"]})
+    return OpenAI(**kwargs)
+
+
+def httpx_timeout(total: float) -> Any:
+    """Build an httpx.Timeout with separate connect/read timeouts.
+
+    For local inference: fast connect (5s) but long read (total) to
+    accommodate slow GPU inference without hanging on dead connections.
+    """
+    return httpx.Timeout(connect=10.0, read=total, write=30.0, pool=10.0)

sqlseed_ai-0.2.3/src/sqlseed_ai/_json_utils.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+def parse_json_response(content: str) -> dict[str, Any]:
+    """Parse JSON from LLM response using 3-strategy fallback."""
+    cleaned = content.strip()
+
+    return _try_direct_parse(cleaned) or _try_markdown_fence_parse(cleaned) or _try_raw_decode(cleaned) or {}
+
+
+def _try_direct_parse(content: str) -> dict[str, Any] | None:
+    """Strategy 1: Direct parse (ideal case — model outputs raw JSON)."""
+    try:
+        result = json.loads(content)
+        if isinstance(result, dict):
+            _sanitize_names(result)
+            return result
+    except json.JSONDecodeError:
+        pass
+    return None
+
+
+def _try_markdown_fence_parse(content: str) -> dict[str, Any] | None:
+    """Strategy 2: Strip markdown code fences (```json\\n{...}\\n```)."""
+    open_idx = content.find("```")
+    if open_idx < 0:
+        return None
+    after_open = content[open_idx + 3 :]
+    nl_pos = after_open.find("\n")
+    if nl_pos < 0:
+        return None
+    content_start = nl_pos + 1
+    close_idx = after_open.find("```", content_start)
+    if close_idx < 0:
+        return None
+    fence_content = after_open[content_start:close_idx].strip()
+    try:
+        result = json.loads(fence_content)
+        if isinstance(result, dict):
+            _sanitize_names(result)
+            return result
+    except json.JSONDecodeError:
+        pass
+    return None
+
+
+def _try_raw_decode(content: str) -> dict[str, Any] | None:
+    """Strategy 3: Find first '{' and use json.JSONDecoder.raw_decode().
+
+    Handles explanatory text before/after JSON without code fences.
+    raw_decode() correctly handles braces inside JSON strings.
+    """
+    first_brace = content.find("{")
+    if first_brace < 0:
+        return None
+    try:
+        decoder = json.JSONDecoder()
+        result, _ = decoder.raw_decode(content, idx=first_brace)
+        if isinstance(result, dict):
+            _sanitize_names(result)
+            return result
+    except json.JSONDecodeError:
+        pass
+    return None
+
+
+def _sanitize_names(data: dict[str, Any]) -> None:
+    name = data.get("name")
+    if isinstance(name, str):
+        data["name"] = re.sub(r"^[:.]+", "", name)
+
+    for col in data.get("columns", []):
+        if isinstance(col, dict):
+            col_name = col.get("name")
+            if isinstance(col_name, str):
+                col["name"] = re.sub(r"^[:.]+", "", col_name)

sqlseed_ai-0.2.3/src/sqlseed_ai/_model_selector.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import re
+
+from sqlseed_ai.config import AIBackend, GemmaModel
+
+from sqlseed._utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def _normalize_model_id(model_id: str) -> str:
+    """Normalize a model ID for comparison.
+
+    Strips platform-specific formatting so that model IDs from
+    different sources can be compared:
+
+      "google/gemma-4-e4b"    → "gemma-4-e4b"   (LM Studio)
+      "gemma-4-e4b-it"        → "gemma-4-e4b"   (Google AI Studio)
+      "gemma4:e4b"            → "gemma-4-e4b"   (Ollama)
+      "google/gemma-4-e4b-it" → "gemma-4-e4b"   (OpenRouter)
+      "google/gemma-4-26b-a4b-it:free" → "gemma-4-26b-a4b" (OpenRouter free)
+    """
+    result = model_id.lower().strip()
+
+    # Strip OpenRouter free tier suffix (e.g., ":free")
+    result = re.sub(r":free$", "", result)
+
+    # Convert Ollama format: "gemma4:xxb" → "gemma-4-xxb"
+    # e.g., "gemma4:e4b" → "gemma-4-e4b", "gemma4:26b" → "gemma-4-26b"
+    ollama_match = re.match(r"^gemma4:(.+)$", result)
+    if ollama_match:
+        result = f"gemma-4-{ollama_match.group(1)}"
+
+    # Strip provider prefix (e.g., "google/" from LM Studio/OpenRouter IDs)
+    result = re.sub(r"^[a-z]+/", "", result)
+
+    # Strip "-it" suffix (instruction-tuned variant indicator)
+    return re.sub(r"-it$", "", result)
+
+
+# ── Gemma 4 model selection priority ────────────────────────────────
+# Ordered by capability: 26B A4B MoE (best balance) > 31B Dense > 12B Unified > E4B > E2B
+_GEMMA_MODEL_PRIORITY: tuple[GemmaModel, ...] = (
+    GemmaModel.GEMMA_4_26B_A4B,
+    GemmaModel.GEMMA_4_31B,
+    GemmaModel.GEMMA_4_12B,
+    GemmaModel.GEMMA_4_E4B,
+    GemmaModel.GEMMA_4_E2B,
+)
+
+# Map backend to preferred model size
+_BACKEND_DEFAULT_MODEL: dict[AIBackend, GemmaModel] = {
+    AIBackend.GOOGLE_AI_STUDIO: GemmaModel.GEMMA_4_26B_A4B,
+    AIBackend.LM_STUDIO: GemmaModel.GEMMA_4_E4B,  # local inference, prefer smaller
+    AIBackend.OLLAMA: GemmaModel.GEMMA_4_E4B,  # smaller for local inference
+    AIBackend.OPENAI_COMPAT: GemmaModel.GEMMA_4_26B_A4B,
+}
+
+
+def select_gemma_model(
+    backend: AIBackend = AIBackend.GOOGLE_AI_STUDIO,
+    prefer_small: bool = False,
+) -> str:
+    """Select the best Gemma 4 model for the given backend.
+
+    Returns the platform-specific model ID for the selected backend.
+
+    Args:
+        backend: The LLM backend provider.
+        prefer_small: If True, prefer smaller models (useful for Edge/local).
+
+    Returns:
+        The model identifier string in the backend's format.
+    """
+    if prefer_small or backend in (AIBackend.OLLAMA, AIBackend.LM_STUDIO):
+        # For local inference (Ollama/LM Studio), prefer smaller models
+        model = GemmaModel.GEMMA_4_E4B
+        logger.info("Selected compact Gemma 4 model for local inference", model=model.to_backend_id(backend))
+        return model.to_backend_id(backend)
+
+    model = _BACKEND_DEFAULT_MODEL.get(backend, GemmaModel.GEMMA_4_26B_A4B)
+    logger.info("Selected Gemma 4 model", model=model.to_backend_id(backend), backend=backend.value)
+    return model.to_backend_id(backend)
+
+
+def select_next_gemma_model(failed_model: str, backend: AIBackend | None = None) -> str | None:
+    """Select the next smaller Gemma 4 model as fallback.
+
+    Skips models that are not available on the given backend
+    (e.g., 12B is local-only and not available on Google AI Studio/OpenRouter).
+
+    Args:
+        failed_model: The model that failed.
+        backend: The current backend (used to skip unavailable models).
+            If None, all models are considered available.
+
+    Returns:
+        The next model in the priority list (in backend-specific format), or None if all exhausted.
+    """
+    failed_norm = _normalize_model_id(failed_model)
+    for i, m in enumerate(_GEMMA_MODEL_PRIORITY):
+        if _normalize_model_id(m.value) == failed_norm:
+            # Walk down the priority list to find the next available model
+            for j in range(i + 1, len(_GEMMA_MODEL_PRIORITY)):
+                next_model = _GEMMA_MODEL_PRIORITY[j]
+                # Skip local-only models for cloud backends
+                if next_model.is_local_only and backend not in (
+                    AIBackend.LM_STUDIO,
+                    AIBackend.OLLAMA,
+                    None,  # None means "don't filter"
+                ):
+                    continue
+                logger.info(
+                    "Falling back to smaller Gemma 4 model",
+                    from_model=failed_model,
+                    to_model=next_model.to_backend_id(backend) if backend else next_model.value,
+                )
+                return next_model.to_backend_id(backend) if backend else next_model.value
+
+    logger.warning("No more Gemma 4 models available for fallback", failed_model=failed_model)
+    return 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]