template-saas/docs/architecture/adr/ADR-006-ai-integration-multi-provider.md

id	title	type	status	priority	supersedes	superseded_by	version	created_date	updated_date
ADR-006	AI Integration Multi-Provider	ADR	Accepted	P0	N/A	N/A	1.0.0	2026-01-10	2026-01-10

ADR-006: AI Integration Multi-Provider

Metadata

Campo	Valor
ID	ADR-006
Estado	Accepted
Fecha	2026-01-10
Supersede	N/A

Contexto

El sistema requiere integracion con multiples proveedores de IA (Claude, GPT-4, Gemini) para:

• Ofrecer flexibilidad a los usuarios en la eleccion de modelo
• Evitar vendor lock-in
• Permitir fallback automatico si un proveedor no esta disponible
• Optimizar costos segun el caso de uso

Requisitos

• Soporte para Claude (Anthropic), GPT-4 (OpenAI), Gemini (Google)
• Cambio de proveedor sin modificar codigo de aplicacion
• Token counting y cost tracking por tenant
• Rate limiting por tenant y plan

Opciones Consideradas

Opcion 1: APIs Directas por Proveedor

Descripcion: Implementar SDK de cada proveedor directamente.

Pros:

• Sin intermediarios
• Acceso a todas las features de cada proveedor
• Sin costos adicionales

Contras:

• Mayor complejidad de codigo
• Mantenimiento de multiples SDKs
• Sin fallback automatico

Opcion 2: OpenRouter como Gateway

Descripcion: Usar OpenRouter como gateway unificado para todos los providers.

Pros:

• API unificada para todos los modelos
• Fallback automatico entre providers
• Billing consolidado
• Menor codigo a mantener

Contras:

• Latencia adicional (~50ms)
• Costo de gateway (2-5%)
• Dependencia de servicio externo

Opcion 3: LangChain Abstraction

Descripcion: Usar LangChain como capa de abstraccion.

Pros:

• Abstraccion completa
• Chains y agents pre-construidos
• Comunidad activa

Contras:

• Overhead significativo
• Curva de aprendizaje
• Dificil debugging

Decision

Elegimos OpenRouter como gateway unificado con fallback a APIs directas para casos criticos.

Justificacion

1. Simplicidad: Una sola API para todos los modelos
2. Flexibilidad: Cambio de modelo sin cambios de codigo
3. Fallback: Automatico entre providers
4. Costos: Optimizacion automatica por costo/performance

Implementacion

Configuracion

// config/ai.config.ts
export const aiConfig = {
  provider: 'openrouter',
  defaultModel: 'anthropic/claude-3.5-sonnet',
  fallbackModel: 'openai/gpt-4-turbo',
  maxTokens: 4096,
  temperature: 0.7
};

Service Layer

@Injectable()
export class AIService {
  async complete(prompt: string, options?: AIOptions) {
    return this.openRouterClient.complete({
      model: options?.model || this.config.defaultModel,
      messages: [{ role: 'user', content: prompt }],
      max_tokens: options?.maxTokens || this.config.maxTokens
    });
  }
}

Rate Limiting por Tenant

• Free: 100 requests/dia
• Basic: 1000 requests/dia
• Pro: 10000 requests/dia
• Enterprise: Ilimitado

Consecuencias

Positivas

• Cambio de provider sin modificar codigo de aplicacion
• Fallback automatico entre providers
• Billing unificado y facil de trackear
• Menor codigo a mantener

Negativas

• Latencia adicional (~50ms por request)
• Costo de gateway (2-5% adicional)
• Dependencia de OpenRouter como servicio

Mitigaciones

• Cache de respuestas comunes (Redis)
• Fallback directo a APIs en caso de OpenRouter caido
• Monitoreo de latencia y costos

Referencias

• OpenRouter Documentation
• Anthropic API
• OpenAI API
• Modulo relacionado: SAAS-006-ai-integration.md

---

Fecha decision: 2026-01-10 Autores: Claude Code (Arquitectura)