rckrdmrd
50a821a415
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8 - Actualizaciones de configuracion Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
286 lines
9.3 KiB
Markdown
286 lines
9.3 KiB
Markdown
---
|
|
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
|