erp-mecanicas-diesel-backend-v2/src/modules/ai/README.md

AI Module

Descripcion

Modulo de integracion con modelos de Inteligencia Artificial. Proporciona capacidades de chat conversacional, completions, embeddings y gestion de bases de conocimiento. Soporta multiples proveedores (OpenAI, Anthropic, Google, Azure) a traves de OpenRouter, con control de acceso basado en roles y gestion de cuotas por tenant.

Entidades

Entidad	Schema	Descripcion
AIModel	ai.models	Catalogo de modelos de IA disponibles (GPT-4, Claude, etc.) con configuracion de costos y capacidades
AIPrompt	ai.prompts	Templates de prompts versionados con variables y configuracion de modelo
AIConversation	ai.conversations	Conversaciones de chat con historial, contexto y estadisticas
AIMessage	ai.messages	Mensajes individuales dentro de una conversacion
AICompletion	ai.completions	Registros de completions individuales (no conversacionales)
AIEmbedding	ai.embeddings	Vectores de embeddings para busqueda semantica
AIKnowledgeBase	ai.knowledge_base	Articulos de conocimiento con embeddings para RAG
AIUsageLog	ai.usage_logs	Registro detallado de uso por request
AITenantQuota	ai.tenant_quotas	Cuotas mensuales de tokens, requests y costos por tenant

Servicios

Servicio	Responsabilidades
AIService	Servicio base: CRUD de modelos, prompts, conversaciones, mensajes; registro de uso; gestion de cuotas
RoleBasedAIService	Extension con control de acceso basado en roles ERP; integracion con OpenRouter; ejecucion de tools

Endpoints

Method	Path	Descripcion
GET	/models	Lista todos los modelos activos
GET	/models/:id	Obtiene modelo por ID
GET	/models/code/:code	Obtiene modelo por codigo
GET	/models/provider/:provider	Lista modelos por proveedor
GET	/models/type/:type	Lista modelos por tipo (chat/embedding/etc)
GET	/prompts	Lista prompts del tenant
GET	/prompts/:id	Obtiene prompt por ID
GET	/prompts/code/:code	Obtiene prompt por codigo
POST	/prompts	Crea nuevo prompt
PATCH	/prompts/:id	Actualiza prompt existente
GET	/conversations	Lista conversaciones del tenant
GET	/conversations/:id	Obtiene conversacion con mensajes
GET	/conversations/user/:userId	Lista conversaciones de usuario
POST	/conversations	Crea nueva conversacion
PATCH	/conversations/:id	Actualiza conversacion
POST	/conversations/:id/archive	Archiva conversacion
GET	/conversations/:conversationId/messages	Lista mensajes de conversacion
POST	/conversations/:conversationId/messages	Agrega mensaje a conversacion
GET	/conversations/:conversationId/tokens	Obtiene conteo de tokens
POST	/usage	Registra uso de IA
GET	/usage/stats	Obtiene estadisticas de uso
GET	/quotas	Obtiene cuota del tenant
PATCH	/quotas	Actualiza cuota del tenant
GET	/quotas/check	Verifica disponibilidad de cuota

Dependencias

• common - Utilidades compartidas
• auth - Autenticacion y tenant context
• OpenRouter API (proveedor externo)

Configuracion

Variable	Descripcion	Requerida
OPENROUTER_API_KEY	API key para OpenRouter	Si
APP_URL	URL de la aplicacion (para HTTP-Referer)	No

Roles ERP Soportados

El RoleBasedAIService soporta prompts y accesos diferenciados por rol:

• admin - Acceso completo
• supervisor - Acceso a reportes y analisis
• operator - Acceso a operaciones basicas
• customer - Acceso limitado a consultas