Feature: AutoPlan — Provider google_genai (Gemma 4 directo, Google AI Studio Paid)

Feature: AutoPlan — Provider `google_genai` (Gemma 4 directo, Google AI Studio Paid)

Resumen

PR#14 (edu/autoplan-google-genai, mergeado 2026-05-04, commit d111a07) añade un nuevo provider de IA al pipeline de Auto-Plan: google_genai. Permite digitalizar planos de sala de servidores enviando la imagen directamente a Google AI Studio Paid Tier vía el SDK oficial google-genai, usando el modelo Gemma 4 26B MoE (gemma-4-26b-a4b-it).

Esta integración es el resultado del experimento A/B s49 y complementa los providers ya existentes (openrouter, gemini, deepseek, ollama).

Motivación

Problema	Solución
`openrouter` (default) usa la capa BYOK de OpenRouter, con latencia adicional y ocasionales timeouts en modelos gratuitos	Acceso directo a Google AI Studio Paid elimina la capa intermediaria
El driver `gemini` legacy usa `google-generativeai` (SDK antiguo, deprecated)	El nuevo driver usa `google-genai` (SDK oficial actual)
Billing Google ya estaba activo para GEMINI_API_KEY	La misma key sirve para Gemma 4 cuando billing está vinculado — reutilización sin coste operativo adicional

Archivos cambiados

Archivo	Cambio
`blueprints/services/google_genai_driver.py`	Nuevo — 143 LOC. Driver completo con preprocesado de imagen, retry logic y parsing JSON.
`blueprints/services/autoplan.py`	Añade `elif provider == "google_genai": return cls._analyze_with_gemma4(...)` y método `_analyze_with_gemma4()` (thin wrapper al driver).
`blueprints/api/autoplan.py`	Añade rama `elif provider == "google_genai":` para validar `GEMINI_API_KEY` antes de llamar al servicio.
`config/settings/base.py`	Nuevas settings: `GEMMA4_GENAI_MODEL`, `GEMMA4_GENAI_SEED`, `GEMMA4_GENAI_MAX_IMAGE_DIMENSION`, `GEMMA4_GENAI_JPEG_QUALITY`.

Cómo activar

1. Configurar el provider

# .env
AUTOPLAN_PROVIDER=google_genai
GEMINI_API_KEY=<tu-google-ai-studio-api-key>

La key de Google AI Studio sirve tanto para el provider gemini (legacy) como para google_genai (nuevo). No se necesita una key separada.

2. Settings opcionales (con sus defaults)

GEMMA4_GENAI_MODEL=gemma-4-26b-a4b-it        # O "gemma-4-31b-it" (Dense, plan B s49)
GEMMA4_GENAI_SEED=                            # Vacío = no seed (no determinista)
GEMMA4_GENAI_MAX_IMAGE_DIMENSION=2048
GEMMA4_GENAI_JPEG_QUALITY=95

3. Verificar

Con AUTOPLAN_PROVIDER=google_genai, el endpoint POST /api/blueprints/autoplan/import usará el nuevo driver. Si GEMINI_API_KEY no está configurada, devuelve 400 con mensaje:

{"message": "Google AI Studio API key not configured. Set GEMINI_API_KEY in environment."}

Diagrama de flujo del provider

POST /api/blueprints/autoplan/import
  └─ magic_import_blueprint() [blueprints/api/autoplan.py]
       ├─ provider = settings.AUTOPLAN_PROVIDER  → "google_genai"
       ├─ api_key  = settings.GEMINI_API_KEY
       └─ AutoPlanService.analyze_blueprint_image(api_key, file_path, prompt, provider="google_genai")
            └─ _analyze_with_gemma4(api_key, file_path, prompt)
                 └─ google_genai_driver.analyze_blueprint(api_key, file_path, prompt)
                      ├─ PIL: resize + normalize → JPEG in memory
                      ├─ genai.Client(api_key)
                      ├─ client.models.generate_content(model, [prompt, image_part], config)
                      ├─ _clean_llm_json() + json.loads()
                      └─ → dict {racks, connections, walls, texts, symbols}

Tabla comparativa de providers AutoPlan

Provider key	Driver	Modelo	SDK	Tier
`openrouter` (default)	`openrouter_driver.py`	gemma-2-27b-it:free	requests	BYOK free
`google_genai` ✨ nuevo	`google_genai_driver.py`	gemma-4-26b-a4b-it	google-genai	AI Studio Paid
`gemini`	`autoplan.py._analyze_with_gemini`	gemini-pro-vision	google-generativeai (legacy)	AI Studio
`deepseek`	`autoplan.py._analyze_with_deepseek`	DeepSeek-V3	requests	Paid
`ollama`	`autoplan.py._analyze_with_openrouter`	configurable	requests local	Self-hosted

Detalles técnicos destacados

Sin safety_settings: Gemma open-weights no las acepta. El driver google_genai omite este parámetro explícitamente para evitar errores 400.
Retry con backoff lineal: hasta 3 intentos en errores 503/504/timeout, con esperas de 10s y 20s. El buffer de imagen se hace .seek(0) antes de cada reintento.
response_mime_type: "application/json": fuerza respuesta estructurada, reduciendo fallos de parse frente al driver legacy.
Logging unificado: todos los logs usan el prefijo [AutoPlan] compatible con el panel de monitoring existente.

Véase también

[[entity—blueprints—service—google-genai-driver]]
[[entity—blueprints—service—autoplan]]
[[entity—blueprints—endpoint—autoplan-import]]
[[entity—blueprints—model—aiprompt]]
[[entity—blueprints—model—blueprint]]