# 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