Auto-Plan: proveedor google_genai (Gemma 4 directo via Google AI Studio)

Resumen

PR#14 (s49) añade provider=google_genai al dispatcher de Auto-Plan como alternativa directa a OpenRouter. En lugar de pasar por OpenRouter BYOK, llama a Google AI Studio Paid Tier via el SDK oficial google-genai, usando GEMINI_API_KEY (la misma key sirve para Gemini y Gemma 4 cuando el billing Paid Tier está vinculado a la cuenta).

Estado: draft — A/B test en curso (s49). El default sigue siendo openrouter. Esta feature solo se activa con AUTOPLAN_PROVIDER=google_genai en el entorno Dokploy. No se ha mergeado como default aún (pendiente validación contra baseline s48).

Motivación

Dimensión	OpenRouter (s48 baseline)	google_genai (s49 candidate)
Ruta	OpenRouter → Google	Directo → Google AI Studio
Latencia adicional	+hop OpenRouter	Sin intermediario
Coste	$0 (Gemma :free BYOK)	Por evaluar (Paid Tier)
Sampling	Config OpenRouter	Oficial Gemma 4 (temp 1.0 / top-p 0.95 / top-k 64)
`response_mime_type`	No nativo	`application/json` nativo SDK
Safety settings	Configurable	No enviar (Gemma open-weights las rechaza)

Archivos afectados

Archivo	Cambio
`blueprints/services/google_genai_driver.py`	Nuevo — driver completo (143 LOC)
`blueprints/services/autoplan.py`	Nuevo branch `google_genai` en dispatcher + método `_analyze_with_gemma4`
`blueprints/api/autoplan.py`	Branch resolución `GEMINI_API_KEY` para provider `google_genai`
`config/settings/base.py`	4 nuevas vars: `GEMMA4_GENAI_MODEL`, `GEMMA4_GENAI_SEED`, `GEMMA4_GENAI_MAX_IMAGE_DIMENSION`, `GEMMA4_GENAI_JPEG_QUALITY`

Flujo de llamada

POST /api/blueprints/autoplan/import
  └─ blueprints/api/autoplan.py
       └─ provider == "google_genai" → api_key = GEMINI_API_KEY
            └─ AutoPlanService.analyze_blueprint_image(..., provider="google_genai")
                 └─ cls._analyze_with_gemma4(api_key, file_path, prompt)
                      └─ google_genai_driver.analyze_blueprint(api_key, file_path, prompt)
                           └─ genai.Client → models.generate_content(model, contents, config)

Activación (feature flag)

# .env / Dokploy — PROD + STAGE
AUTOPLAN_PROVIDER=google_genai
GEMINI_API_KEY=<google-ai-studio-key>

# Opcional: reproducibilidad
GEMMA4_GENAI_SEED=43

# Opcional: modelo plan B
GEMMA4_GENAI_MODEL=gemma-4-31b-it

Para revertir al default OpenRouter, eliminar o cambiar AUTOPLAN_PROVIDER a openrouter.

Test plan (s49)

CI verde (ruff, biome, pytest)
Dokploy auto-despliega PROD + STAGE tras merge
docker ps PROD confirma contenedores recreados
Test Auto-Plan PROD con AUTOPLAN_PROVIDER=google_genai + GEMMA4_GENAI_SEED=43
Comparar contra baseline s48: 100% calidad, 68/68 detecciones, 2:09 min, $0
Si convence → commit final: cambio default + Regla 8 CLAUDE.md + ADR + RELEASE_NOTES + WORKLOG
Si no convence → plan B: GEMMA4_GENAI_MODEL=gemma-4-31b-it

Decisión pendiente

Esta feature está en validación. Cuando se confirme la decisión de hacer google_genai el nuevo default, se debe:

Cambiar AUTOPLAN_PROVIDER default en config/settings/base.py.
Actualizar Regla 8 de CLAUDE.md.
Crear una decision_page documentando el cambio arquitectónico.
Actualizar Documentation/backend/AUTO_PLAN_TECHNICAL_REFERENCE.md.
Marcar esta página como active.

Véase también

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