---
id: "SAAS-006"
title: "Integracion IA"
type: "Module"
status: "Published"
priority: "P1"
module: "ai-integration"
version: "1.0.0"
created_date: "2026-01-07"
updated_date: "2026-01-10"
---

# SAAS-006: Integracion IA

## Metadata
- **Codigo:** SAAS-006
- **Modulo:** AI Integration
- **Prioridad:** P1
- **Estado:** Implementado
- **Fase:** 5 - Integraciones
- **Fecha Implementacion:** 2026-01-07

## Descripcion

Wrapper agnostico para integracion con multiples proveedores de LLM (Claude, OpenAI, Gemini): configuracion por tenant, tracking de uso, rate limiting, y costo estimado.

## Objetivos

1. Abstraccion multi-proveedor
2. Configuracion por tenant
3. Tracking de tokens
4. Rate limiting
5. Estimacion de costos

## Alcance

### Incluido
- Soporte: Claude (Anthropic), GPT-4 (OpenAI), Gemini (Google)
- Via OpenRouter como gateway
- Configuracion de modelo por tenant
- Conteo de tokens input/output
- Rate limiting por minuto y por mes
- Logs de uso

### Excluido
- Embeddings - fase posterior
- Fine-tuning
- Vision/imagenes - fase posterior
- Streaming - fase posterior

## Proveedores Soportados

| Proveedor | Modelos | Via |
|-----------|---------|-----|
| Anthropic | claude-3-opus, claude-3-sonnet, claude-3-haiku | OpenRouter |
| OpenAI | gpt-4-turbo, gpt-4, gpt-3.5-turbo | OpenRouter |
| Google | gemini-pro, gemini-1.5-pro | OpenRouter |

## Arquitectura

```
┌─────────────────────────────────────────────────────────┐
│                     AI Service                          │
├─────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │   Config    │  │   Router    │  │   Tracker   │     │
│  │  per Tenant │  │  (Model)    │  │   (Usage)   │     │
│  └─────────────┘  └──────┬──────┘  └─────────────┘     │
│                          │                              │
│                   ┌──────▼──────┐                       │
│                   │ OpenRouter  │                       │
│                   │   Client    │                       │
│                   └──────┬──────┘                       │
│                          │                              │
└──────────────────────────┼──────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────▼────┐      ┌─────▼─────┐     ┌────▼────┐
    │ Claude  │      │   GPT-4   │     │ Gemini  │
    └─────────┘      └───────────┘     └─────────┘
```

## Modelo de Datos

### Schema: ai

**ai.configs** (Configuracion por tenant)
| Columna | Tipo | Descripcion |
|---------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants.tenants |
| provider | ai_provider | openrouter, openai, anthropic, google |
| default_model | VARCHAR(100) | Modelo por defecto |
| fallback_model | VARCHAR(100) | Modelo de respaldo |
| temperature | NUMERIC(3,2) | 0.0 - 2.0 |
| max_tokens | INTEGER | Max tokens por respuesta |
| system_prompt | TEXT | Prompt de sistema |
| is_enabled | BOOLEAN | Habilitar AI |
| allow_custom_prompts | BOOLEAN | Permitir prompts custom |
| log_conversations | BOOLEAN | Guardar historial |

**ai.usage** (Tracking de uso)
| Columna | Tipo | Descripcion |
|---------|------|-------------|
| id | UUID | PK |
| tenant_id | UUID | FK -> tenants.tenants |
| user_id | UUID | FK -> users.users |
| config_id | UUID | FK -> ai.configs (config usada) |
| provider | ai_provider | Proveedor usado |
| model | VARCHAR(100) | Modelo usado |
| model_type | ai_model_type | chat, completion, embedding, image |
| request_id | VARCHAR(100) | ID unico de request |
| endpoint | VARCHAR(100) | Endpoint llamado |
| input_tokens | INTEGER | Tokens de entrada |
| output_tokens | INTEGER | Tokens de salida |
| total_tokens | INTEGER | Total (computed) |
| cost_input | NUMERIC(12,6) | Costo entrada USD |
| cost_output | NUMERIC(12,6) | Costo salida USD |
| cost_total | NUMERIC(12,6) | Total (computed) |
| latency_ms | INTEGER | Latencia en ms |
| status | usage_status | pending, completed, failed, cancelled |
| error_message | TEXT | Mensaje de error (si fallo) |
| metadata | JSONB | Metadata adicional |
| created_at | TIMESTAMP | Fecha de uso |

**ai.monthly_usage** (Vista agregada)
- request_count, total_tokens, total_cost, avg_latency_ms

## Endpoints API

| Metodo | Endpoint | Descripcion | Estado |
|--------|----------|-------------|--------|
| POST | /ai/chat | Chat completion | Implementado |
| GET | /ai/models | Modelos disponibles | Implementado |
| GET | /ai/config | Config del tenant | Implementado |
| PATCH | /ai/config | Actualizar config | Implementado |
| GET | /ai/usage | Historial de uso | Implementado |
| GET | /ai/usage/current | Uso del mes actual | Implementado |
| GET | /ai/health | Estado del servicio | Implementado |

## Implementacion Backend

### Estructura de archivos
```
apps/backend/src/modules/ai/
├── ai.module.ts              # Modulo NestJS
├── ai.controller.ts          # Endpoints REST
├── index.ts                  # Exports
├── clients/
│   └── openrouter.client.ts  # Cliente OpenRouter API
├── services/
│   ├── ai.service.ts         # Logica de negocio
│   └── index.ts
├── entities/
│   ├── ai-config.entity.ts   # TypeORM entity
│   ├── ai-usage.entity.ts    # TypeORM entity
│   └── index.ts
└── dto/
    ├── chat.dto.ts           # Request/Response DTOs
    └── index.ts
```

### Configuracion requerida
```typescript
// .env
OPENROUTER_API_KEY=sk-or-...
AI_DEFAULT_MODEL=anthropic/claude-3-haiku
AI_FALLBACK_MODEL=openai/gpt-3.5-turbo
AI_TIMEOUT_MS=30000
```

## Implementacion Frontend

### Estructura de archivos
```
apps/frontend/src/
├── services/
│   └── api.ts                # aiApi client
├── hooks/
│   └── useAI.ts              # React Query hooks
├── components/ai/
│   ├── AIChat.tsx            # Chat interactivo
│   ├── AISettings.tsx        # Config UI
│   ├── ChatMessage.tsx       # Mensaje individual
│   └── index.ts
└── pages/dashboard/
    └── AIPage.tsx            # Pagina AI
```

### Hooks disponibles
```typescript
// Configuracion
useAIConfig()                 // GET config
useUpdateAIConfig()           // PATCH config

// Modelos
useAIModels()                 // GET modelos disponibles

// Chat
useAIChat()                   // POST chat completion

// Uso
useAIUsage(page, limit)       // GET historial
useCurrentAIUsage()           // GET uso mes actual

// Health
useAIHealth()                 // GET estado servicio
```

## Rate Limiting

### Por Plan
| Plan | Tokens/min | Tokens/mes |
|------|------------|------------|
| Pro | 10,000 | 50,000 |
| Enterprise | 50,000 | 200,000 |

### Implementacion
- In-memory rate limiter (Redis en produccion)
- Por tenant_id
- Tokens y requests

## Costos Estimados

| Modelo | Input/1K | Output/1K |
|--------|----------|-----------|
| claude-3-haiku | $0.00025 | $0.00125 |
| claude-3-sonnet | $0.003 | $0.015 |
| gpt-4-turbo | $0.01 | $0.03 |
| gemini-pro | $0.00025 | $0.0005 |

## Entregables

| Entregable | Estado | Archivo |
|------------|--------|---------|
| Database DDL | Completado | `ddl/schemas/ai/tables/` |
| ai.module.ts | Completado | `modules/ai/` |
| openrouter.client.ts | Completado | `clients/` |
| ai.service.ts | Completado | `services/` |
| ai.controller.ts | Completado | `ai.controller.ts` |
| Frontend hooks | Completado | `hooks/useAI.ts` |
| Chat component | Completado | `components/ai/` |
| Settings UI | Completado | `AISettings.tsx` |
| AI Page | Completado | `pages/dashboard/AIPage.tsx` |

## Dependencias

### Depende de
- SAAS-002 (Tenants) - tenant_id FK
- SAAS-003 (Users) - user_id FK
- SAAS-005 (Plans - feature flag)
- OpenRouter API key

### Bloquea a
- Features de IA en otros modulos

## Criterios de Aceptacion

- [x] Chat funciona con Claude
- [x] Chat funciona con GPT-4
- [x] Chat funciona con Gemini
- [x] Tokens se cuentan correctamente
- [x] Rate limiting funciona
- [x] Uso se registra
- [x] UI de chat funcional
- [x] Settings de AI por tenant

## Rutas Frontend

| Ruta | Componente | Descripcion |
|------|------------|-------------|
| /dashboard/ai | AIPage | Chat con AI |
| /dashboard/settings (tab AI) | AISettings | Configuracion |

## Navegacion

- Sidebar: "AI Assistant" con icono Bot
- Settings: Tab "AI" en pagina de configuracion

---

**Ultima actualizacion:** 2026-01-10
**Version:** 1.0.0
**Autor:** Claude Code