ADR — Modelos Gemini fijos por función

Contexto

El proyecto usa modelos Gemini para varios casos de uso con requisitos distintos:

1. Auto-Plan AI (blueprints/services/autoplan.py): análisis de planos de infraestructura por visión por computador. Envía JPEG (máx 2048px) al modelo con prompt estructurado, espera JSON con posiciones y tipos de elementos. Requiere modelo con capacidades vision-language y prompt cuidadosamente calibrado.

2. CNS Explain / Tutor / MIB Assistant / AI Operations / FinOps / Perf Review (8 call sites en CreaRack-Pro): análisis estructurado y extracción JSON con prompts calibrados (temp 0.1, max 16384 tokens). Coherencia con Auto-Plan en la categoría de modelo.

3. Archivo Maestro síntesis (functions/api/mcp/handlers/archivo-core.ts): RAG sobre texto. El modelo recibe chunks de documentación y la pregunta del usuario, sintetiza una respuesta con referencias.

4. Wiki traducción ES→EN (functions/api/wiki/translate.ts live + scripts/translate-wiki.mjs batch): traducción de prosa markdown manteniendo formato.

Hasta principios de 2026, el modelo de Auto-Plan era gemini-2.0-flash. Hacia marzo-abril 2026, Google deprecó esa versión y comenzó a migrar el alias latest hacia modelos experimentales de Gemini 3. Problema con latest en producción: cambios de comportamiento del modelo ocurren sin control del equipo. Un prompt calibrado para Flash 2.0 puede producir JSON mal estructurado o respuestas vacías cuando el alias apunta a modelo distinto, sin error explícito de la API.

Posteriormente (abril 2026), al implementar Archivo Maestro y wiki translate en el workspace, se eligió gemini-2.5-flash por ser modelo estable (no preview) y tener mejor latencia/coste para casos de síntesis y traducción de texto plano. Sin embargo, la Regla 8 original solo mencionaba “Auto-Plan AI: NO cambiar modelo — gemini-3-flash-preview fijo”, dejando ambigüedad sobre si aplicaba a TODO el código IA o solo a Auto-Plan. Esta ambigüedad fue detectada como deuda técnica en sesión 26 del Supercontexto y resuelta en sesión 30 (26-04-2026).

Opciones evaluadas

1. Modelo único gemini-3-flash-preview para todo el código IA Pro: máxima simplicidad, una sola regla. Contra: preview puede cambiar comportamiento sin aviso; síntesis y traducción no requieren capacidades de un preview; obliga a revalidar prompts de RAG y traducción ante cambios de Google.

2. Tabla canónica por caso de uso Pro: cada call site tiene modelo justificado, política autodocumentada, blinda contra drift futuro (cambiar un modelo obliga a tocar tabla + ADR + regla). Contra: más mantenimiento (la tabla hay que mantenerla sincronizada con la realidad del código).

3. Switch parcial a Claude (Anthropic) Stack ya incluye anthropic >= 0.52.0 usado en CNS/Edge Intelligence. Técnicamente viable. Contra: mayor coste/token, latencia diferente, necesidad de reescribir y calibrar prompts. Cambio justificado solo si Gemini deja de ofrecer los modelos elegidos.

Decisión

Opción 2 — Tabla canónica por caso de uso, con dos categorías:

Categoría A · Análisis estructurado / visión / extracción JSON crítica → gemini-3-flash-preview (FIJO)

Razón: prompt y parámetros (temp 0.1, JSON output, max tokens) están calibrados específicamente para este modelo. Cambiar el modelo invalida la calibración silenciosamente. Coherencia entre todos los call sites de análisis estructurado simplifica la operación y la facturación.

Call sites (CreaRack-Pro, 8):

Categoría B · Síntesis NL / traducción de texto → gemini-2.5-flash (estable, no preview)

Razón: estabilidad de comportamiento prima sobre features experimentales. RAG y traducción de prosa no requieren las capacidades de un preview. Reduce riesgo de drift de comportamiento en producción del workspace.

Call sites (workspace, 3):

Modelos prohibidos

• gemini-2.0-flash: deprecated por Google, devuelve 404 “no longer available”. Cualquier referencia es bug latente.
• gemini-latest u otros alias dinámicos: contraviene política de pin de versiones (Regla 9 patrones de despliegue).

Política de cambio

Cualquier modificación del modelo en cualquier call site requiere actualizar en el mismo commit:

1. La tabla de este ADR.
2. La nota expandida de la Regla 8 en CLAUDE.md (CreaRack-Pro y workspace).
3. El footgun onboarding/shared-memory/footguns_gemini_model.md.

Si aparece un nuevo caso de uso IA que no encaja en A ni B (ej: módulo con caso novedoso), abrir nueva sub-categoría en este ADR con justificación antes de implementar.

Consecuencias

• Cualquier agente o dev que intente cambiar un modelo encuentra 3 barreras coordinadas (tabla ADR + Regla 8 CLAUDE.md + footgun) más el comentario inline en código.
• La política multi-modelo es explícita: nadie puede asumir “todo es gemini-3-flash-preview” ni “todo es gemini-2.5-flash”. Cada call site sabe qué usar.
• Si Google depreca alguno de los modelos elegidos, el equipo recibirá errores API explícitos (modelo no disponible), preferible a degradación silenciosa por alias dinámico. El plan de migración debe respetar la categoría (A → preview equivalente; B → estable equivalente).
• Switch a Claude Haiku/Sonnet como alternativa de visión queda documentado como opción viable para Categoría A, sin afectar a Categoría B.
• Coste de mantenimiento: la tabla debe revisarse cuando se añade un nuevo call site IA. El reporte bib_report_change ayuda a detectar drift.

Status

Accepted — Abril 2026 (versión inicial 21-04-2026, ampliada a política multi-modelo 26-04-2026 sesión 30). Autores: Edu / Dani.

Véase también

• [[concept—blueprints—map-editor]]
• [[concept—biblioteca—archivo-maestro]]
• [[crearack-tech—guides—gemini-api-setup]] — setup, billing y gestión de claves de Gemini API