Skip to content

Módulo AI ​

El módulo AI permite interactuar con múltiples proveedores de inteligencia artificial de forma desacoplada. El resto del sistema no necesita saber si está usando Anthropic, OpenAI o Google — solo habla con AIService.

Gobernanza ​

POST /ai/generate es una pasarela gobernada:

  1. Resuelve credenciales con (BYOK del tenant → built-in de plataforma con entitlement provider_platform_ai → error accionable).
  2. Rate limit anti-abuso (plan ≤ global) aplica a BYOK y plataforma antes de resolver/ejecutar. Ventana fija de 60s por companyId, persistida en ai_rate_limit_counters para compartir el límite entre réplicas y mantenerlo tras reinicios. Rechazo: AI_RATE_LIMIT_EXCEEDED (HTTP 429). Los umbrales numéricos no se publican.
  3. Uso BYOK no consume cuotas del plan ni saldo de overage.
  4. Uso plataforma aplica allowlist de modelos, techo de maxTokens y cuotas incluidas (tokens + peticiones) del ciclo de facturación vigente — leídas en vivo en cada request (cambio de plan a mitad de ciclo aplica al instante).
  5. Tras un generate exitoso de plataforma:
    • si hay margen incluido → clasifica incluido y suma contadores incluidos;
    • si la cuota incluida está agotada → clasifica overage, suma contadores overage y descuenta saldo según platform_ai_overage_tariff (minor units / 1k tokens).
  6. Si la cuota incluida está agotada y el switch de overage está off → AI_OVERAGE_SWITCH_OFF. Si el switch está on pero el saldo es ≤ 0 → AI_OVERAGE_SALDO_INSUFFICIENT.
  7. Los fallos no cobran (ni cuota ni saldo). El reset de ciclo reinicia contadores incluidos/overage; no reinicia switch ni saldo.

Consumo, overage y saldo (OWNER/ADMIN) ​

MétodoRutaDescripción
GET/ai/consumptionConsumo del ciclo: topes incluidos, usado incluido/overage, restante, switch, saldo, fechas/id de ciclo, hint de resolución BYOK vs plataforma (sin secretos ni umbrales de rate limit)
GET/ai/overageEstado del switch + saldo prepago actual
PATCH/ai/overage/switchBody { "enabled": true|false } — activa/desactiva overage (default off)
POST/ai/overage/saldo/creditsDeshabilitado para cualquier caller humano, incluido Super Admin: responde 403. Solo el hook interno AiOverageService.applyConfirmedPaymentCredit acredita saldo tras pago confirmado; idempotente por paymentReference

OWNER/ADMIN pueden leer switch/saldo y cambiar el switch. MEMBER/VIEWER reciben 403 en /ai/overage* y /ai/consumption. Cualquier persona usuaria, incluidos OWNER/ADMIN y Super Admin, recibe 403 si intenta acreditar saldo por POST .../saldo/credits. La recarga no está expuesta en el SDK browser/node; el SDK cubre consulta y switch, no el crédito de saldo. El checkout Stripe completo sigue fuera de este endpoint.

Assistants / widget público (entitlements) ​

Los assistants de tenant y el widget público son capacidades de plan distintas de la pasarela gobernada. Tener provider_platform_ai (u otras claves de cuotas IA) no habilita assistants ni widget.

ClaveTipoEfecto
ai_assistantsflagCrear/usar assistants de tenant (canales autenticados)
ai_public_widgetflagPublicar y servir el widget público anónimo
ai_max_assistantslimitTope opcional al crear assistants (si el plan no lo define → sin tope de producto)
ai_max_skillslimitTope opcional al crear skills de tenant

Enforcement vía AssistantsEntitlementGate (exportado por AIModule). Sin FLAG → AI_ASSISTANTS_NOT_ENTITLED / AI_PUBLIC_WIDGET_NOT_ENTITLED (422). Con LIMIT y cupo agotado → AI_ASSISTANTS_LIMIT_EXCEEDED / AI_SKILLS_LIMIT_EXCEEDED (422).

Catálogo de skills y assistants de plataforma ​

Módulo AssistantsModule. Recursos globales (super admin). Seed de arranque: assistant Config Nimobase + skills de plataforma (algunas shareable, otras no).

Para la administración de conexiones de NimoApps, el catálogo incluye las skills app-projects.connections.get y app-projects.connections.update. Se ejecutan solo desde Nimo autenticado con rol OWNER/ADMIN; la actualización exige confirmación explícita. Devuelven referencias UUID y diagnósticos, nunca credenciales. El handler las marca como no elegibles para el widget público; el control-plane no se publica en SDK público ni MCP externo.

El catálogo interno también incluye app-projects.environments.promote. Requiere confirmación explícita y revalida en el servidor la sesión OWNER/ADMIN, las revisiones esperadas y el release Preview desplegado antes de actualizar atómicamente la asignación activa de Production. No inicia un nuevo despliegue del proveedor y no está disponible para el widget público, el SDK público ni MCP externo.

MétodoRutaAuthDescripción
GET/ai/catalog/skillsOWNER, ADMINSolo skills de catálogo compartibles
GET/ai/platform/skillsSuper adminCatálogo completo
POST/PATCH/DELETE/ai/platform/skillsSuper adminCRUD + flag shareable
GET/POST/PATCH/DELETE/ai/platform/assistantsSuper adminAssistants de plataforma
PUT/ai/platform/assistants/:id/skillsSuper adminAllowlist de skills
POST/ai/platform/assistants/:id/skills/:skillId/invokeSuper adminInvocación allowlisted; escrituras piden confirmed; tras confirm ejecuta mutaciones reales (settings/maintenance)

Assistants y skills de tenant ​

CRUD de empresa (origin=tenant, companyId del JWT). Requiere entitlement ai_assistants (y opcionalmente límites ai_max_assistants / ai_max_skills) en create. MEMBER/VIEWER → 403 en todas estas rutas.

MétodoRutaAuthDescripción
GET/POST/PATCH/DELETE/ai/skillsOWNER, ADMINSkills de tenant; serviceKey solo allowlist Nimobase; riskClass obligatorio
GET/POST/PATCH/DELETE/ai/assistantsOWNER, ADMINAssistants de tenant; create/update aceptan presentationName / presentationAvatarUrl
PUT/ai/assistants/:id/skillsOWNER, ADMINAllowlist: skills compartibles del catálogo y/o propias; rechaza no compartibles / de otra empresa

Las skills de tenant no admiten settings.get ni settings.put: la tabla de ajustes es global y no pertenece a una empresa. La skill de lectura del catálogo también es solo de plataforma; el acceso autenticado a GET /settings conserva el contrato de lectura.

El contrato publicado de /ai/skills (CreateTenantSkillDto.serviceKey.enum en packages/openapi/openapi.json y el SDK público) enumera solo la superficie tenant pública. Las operaciones de administración interna (app-projects.*, app-domains.*, app-dns-connections.*, app-repository-bindings.*, app-repository-export.*, app-migrations.*, git-integrations.webhooks.*) se declaran con internalAdmin en el catálogo de capacidades y nunca se publican; el marcador no cambia qué puede ejecutar Nimo interno.

El seed del catálogo incluye application-dsl.generate-draft como skill compartible para assistants tenant. La generación de borradores exige OWNER/ADMIN dentro del handler DSL y usa AIService con resolución y gobernanza del proveedor existentes. Aunque la skill se clasifica como read, su resultado es un candidato editable pendiente de revisión (valid=false, publishable=false). El servidor vacía las colecciones de políticas/rules, roles de acceso de forms/views/triggers y asignaciones; elimina condiciones actor_has_role y marca los campos pendientes para la persona en el editor. Si el validador rechaza los roles vacíos, conserva el documento candidato y adjunta los errores para que se complete manualmente.

Catálogo de capacidades del tenant (FE-AI-001) ​

GET /ai/capabilities devuelve el catálogo filtrado para la sesión JWT y empresa activa: requiere membresía y el entitlement ai_assistants. Comprueba el rol de membresía vigente; un cambio de rol exige renovar la sesión. No acepta IDs de usuario o rol en ruta, query o body y no enumera objetos de Object Storage.

La respuesta omite capacidades planeadas y de plataforma, filtra operaciones OWNER/ADMIN según el rol actual e incluye requisitos, límites y confirmación explícita por operación. Object Storage solo aparece con object_storage_enabled y el permiso/grant vigente. App Data queda disponible a nivel de empresa con ai_assistants, pero cada operación resuelve la aplicación publicada, el rol asignado y su contrato al ejecutarse. Facturación comercial mantiene sus lecturas tenant y reserva escrituras para OWNER/ADMIN. Push solo aparece para OWNER/ADMIN y comunica el tope vigente de 100 destinatarios.

El catálogo describe el acceso actual; no concede permisos ni garantiza el resultado de una operación posterior. Cada tool vuelve a validar tenant, membresía, entitlement, grants y confirmación antes de operar.

Puente de facturación comercial (/ AI-BILLING-001) ​

El catálogo compartible para assistants tenant expone lectura de clientes, tipos, productos y documentos; prepara una propuesta de borrador y permite emitir un borrador existente tras una revisión separada. No usa billing.invoices.list, que consulta las facturas de suscripción de Nimobase.

El handler vuelve a comprobar en cada llamada la empresa y el usuario del contexto autenticado, la membresía y rol vigentes, y ai_assistants. OWNER/ADMIN pueden crear borradores y emitir; cada escritura requiere la confirmación del chat. El precio y los impuestos salen del producto y catálogo fiscal actuales. Las series y correlativos se resuelven desde el tipo de documento; el modelo no puede enviar importes, tasas ni series propios. La emisión compara de nuevo la propuesta con el documento y catálogo vigentes, y exige que el documento siga en borrador.

El puente cubre facturas empresa→cliente preparadas con productos existentes. La creación asistida de notas de crédito/rectificativas y la facturación de plataforma a empresa no se ofrece; tampoco hay operación para enviar facturas por email en el módulo actual.

Puente de archivos y Object Storage (/ AI-FILES-001) ​

El asistente tenant puede listar metadatos y organizar rutas del espacio de la empresa activa: crear carpetas, mover, borrar y crear o revocar enlaces temporales. La confirmación humana es obligatoria para estas mutaciones; el borrado de carpetas es recursivo. El handler fija space=tenant, exige el contexto autenticado y vuelve a validar ai_assistants; ObjectStorageService revalida object_storage_enabled, grants/permisos y el acceso al objeto en cada llamada.

No se exponen la subida binaria, la descarga binaria, el espacio de plataforma ni la gestión de grants. Para compartir una descarga se crea un enlace público acotado a un objeto, por defecto de 48 horas, con confirmación explícita. Las rutas backups/ y las rutas fuera del espacio activo siguen bloqueadas por ; los errores de recurso no incluyen nombres ni metadatos de otros

tenants.

Puente de notificaciones push (/ AI-PUSH-001) ​

El catálogo compartible expone notifications.push.recipients.list y notifications.push.send. Ambas operaciones vuelven a comprobar en cada llamada la empresa activa, la sesión humana autenticada, la membresía y rol OWNER/ADMIN vigentes y el entitlement ai_assistants. La consulta de destinatarios devuelve solo id y nombre, paginados hasta 100 por página.

El envío acepta una lista cerrada de 1 a 100 miembros actuales, título, cuerpo, una ruta interna opcional y canales web_push/native_push explícitos. No admite broadcast, email, webhook, in-app, tenant seleccionado por el modelo, credenciales ni tokens de dispositivo. La llamada de escritura queda en el flujo de confirmación del chat; el servidor compara cada id y nombre con la membresía actual antes de delegar a NotificationsService.sendComposed, que registra tenant, actor y operación en el outbox.

La aceptación es best-effort, no un recibo de entrega: preferencias, falta de suscripción/dispositivo, ausencia de app nativa vinculada o provider NoOp pueden omitir la entrega. La skill de push no está disponible en el widget anónimo ni permite registrar dispositivos o cambiar credenciales.

En ejecución autenticada y en el widget, el catálogo vuelve a comprobar la visibilidad actual: un skill de plataforma ya asignado deja de estar disponible para assistants de tenant cuando shareable pasa a false. Los skills propios de tenant no dependen de ese flag.

Identidad de presentación: cada respuesta de assistant incluye presentationName y presentationAvatarUrl resueltos:

OrigenpresentationNamepresentationAvatarUrl
platformsiempre Nimologo Nimobase (FRONTEND_URL + /brand/icon.svg, o ruta relativa si no hay FRONTEND_URL)
tenantvalor configurado por OWNER/ADMIN, o name si no hayURL configurada, o null → el cliente debe mostrar el avatar robot por defecto

No hay subida de ficheros en esta entrega: el avatar de tenant es una URL HTTP(S). PATCH con presentationAvatarUrl: null limpia el avatar. Límites de entrada (400 si se exceden): presentationName ≤ 255 caracteres; presentationAvatarUrl ≤ 2048 (alineado con las columnas persistidas).

Chat autenticado (+) ​

OWNER/ADMIN/MEMBER/VIEWER chatean por UUID de assistant. Si origin=tenant, sigue haciendo falta ai_assistants y que el assistant sea de la empresa activa. Si origin=platform (Config Nimobase / Nimo del dashboard), no se exige el add-on de assistants: es superficie de producto. El hilo sigue aislado por empresa+usuario y el consumo se imputa al tenant del actor.

Skills read compartibles asignadas a Nimo pueden ejecutarse si el actor está autorizado. Las skills globales de Settings (settings.get y settings.put) son solo de plataforma y requieren un super admin; otras mutaciones de catálogo no compartibles (maintenance.set) también solo las ejecuta un super admin de plataforma (mismo espíritu que POST /ai/platform/assistants/:id/skills/:skillId/invoke): un OWNER/ADMIN/MEMBER normal las ve rechazadas; el SA confirma y ejecuta.

GET /ai/assistants no lista assistants de plataforma; el GET de administración (GET /ai/assistants/:id, OWNER/ADMIN) sobre un UUID de plataforma sigue respondiendo 404. El launcher autenticado no usa ese GET ni el seed: pide GET /ai/assistants/:assistantId/presentation, que sí resuelve Nimo de plataforma.

La generación pasa por el runtime gobernado (AIService.generate). Solo skills de la allowlist del assistant. Skills read se ejecutan sin confirmación extra; write/destructive de tenant devuelven status: awaiting_confirmation con un pendingId hasta confirm o reject. Historial en ai_conversations. La confirmación se reclama de forma atómica antes de ejecutar la skill: si llegan dos confirmaciones a la vez, solo una puede aplicar la escritura. Los reintentos después de una ejecución completada son idempotentes. Para reconectar un turno después de perder la respuesta, el cliente reenvía el mismo requestId UUID y el mismo contenido: la API recupera la respuesta almacenada sin generar otro mensaje ni volver a procesar skills. Reutilizar el ID con contenido, proveedor o modelo distintos responde 409. La reserva se limita a empresa, assistant y usuario autenticado; un turno en curso no se ejecuta en paralelo. El listado GET /ai/conversations?limit=&offset= devuelve únicamente conversaciones autenticadas del usuario actual, en páginas de hasta 100 filas. Es una ruta interna de Nimo y no se exporta al SDK/OpenAPI público. Los operationId de trabajos largos apuntan al registro durable existente: GET /app-operations/:id consulta el progreso dentro de la empresa activa. Cada hilo pertenece a un assistant concreto: si reutilizas un conversationId de otro assistant en el POST …/:assistantId/chat, la API responde 404 opaco (mismo criterio que un id ajeno al tenant/usuario) y no mezcla historial con el prompt ni las skills del assistant de la ruta.

Las respuestas de Nimo autenticado incluyen schemaVersion: 1, messageId y blocks, además del campo de compatibilidad assistantMessage. El historial persiste los bloques para que sobrevivan a una recarga; los mensajes antiguos o con bloques desconocidos se presentan como texto. El registro admite únicamente text, choice, review, progress, dsl_preview y los widgets de revisión y decisión form, table, chart, diff y confirm. El modelo solo puede proponer text, choice o dsl_preview; el resto lo emite el servidor y su payload se valida antes de persistirse. Los bloques no ejecutan código.

Los widgets de revisión tienen límites cerrados: formularios de hasta 8 campos y tablas de hasta 6 columnas con paginación. Un gráfico debe incluir su tabla equivalente, además de fuente, período, unidades y filtros; sin ella el bloque se rechaza. confirm exige un interactionId emitido por el servidor y no autoriza nada por sí mismo: la única ruta que ejecuta una skill de escritura sigue siendo la confirmación de pendings. Descartar un widget (por ejemplo con Escape) es local del cliente y no cancela el trabajo. Un renderizador público puede limitar qué tipos acepta; lo que quede fuera de su alcance se muestra como texto.

Una opción choice lleva IDs y etiquetas generados desde una lista cerrada. La API acepta solo choiceId de esa lista por el endpoint de interacción; guarda el uso de forma atómica y lo vence a los 15 minutos. La etiqueta validada se envía como un mensaje ordinario al chat y no autoriza ninguna skill. Las confirmaciones review siguen usando exclusivamente el flujo existente de pendings de skills, también con expiración a los 15 minutos. Estos bloques y la ruta de elección pertenecen al chat autenticado, no al widget público.

Un solo protocolo para todas las superficies Nimo: el widget público y el launcher responden con el mismo sobre (schemaVersion, messageId, blocks) más assistantMessage, leído del mismo mensaje persistido. El alcance de un host embebible es cerrado — text, progress, dsl_preview, table, chart y diff —, así que review, form, confirm y choice nunca llegan a un integrador: si el mensaje guardado conserva un bloque con autoridad, el turno se degrada a un bloque de texto con el mensaje del assistant. La administración de la plataforma (proyectos, entornos, releases, hosting, dominios, DNS y Git) sigue fuera de estos bloques, del SDK público y de MCP externo. La petición de chat solo lleva campos explícitos (message, conversationId, visitorId y las pistas de routing existentes): el tenant lo resuelve el servidor y nunca se aceptan capturas de pantalla, valores de formulario ni secretos.

Resultado de una skill: hecho confirmado, no prosa ​

Cada elemento de skillResults informa outcome (completed, partial o failed) y effects, la lista de pasos que el servidor puede probar con state: applied | not_applied | unknown y un reason opcional. ok se mantiene solo como alias de compatibilidad de outcome !== "failed".

Esto evita dos engaños frecuentes:

  • Un envío push aceptado cuyos canales el proveedor omitió no es un éxito binario: se informa partial con el canal que sí salió y el que no, con su motivo (no_recipient_devices, no_app_client_linked).
  • Una operación de archivos que responde status: not_found, conflict o invalid dentro del payload no se muestra como ejecutada: se informa como failed, porque nada se aplicó.

El texto del assistant es solo texto: el chat nunca deduce que algo se ejecutó a partir de la prosa del modelo. La etiqueta de ejecución, el resumen, la lista de efectos y el estado de los trabajos largos se construyen únicamente con skillResults y con el registro durable de operaciones. Si el servidor es anterior a este contrato, el cliente cae al ok heredado.

El contrato no amplía permisos. Ningún parámetro de skill permite fijar la empresa ni elegir credenciales: la empresa sale de la sesión, el resultado devuelve siempre la empresa del servidor y cada handler valida una lista cerrada de claves. El canal interno de Nimo recibe el mismo outcome/effects con su scope propio, sin privilegios adicionales.

MétodoRutaAuthDescripción
GET/ai/assistants/:assistantId/presentationOWNER, ADMIN, MEMBER, VIEWERPresentación mínima (id, origin, presentationName, presentationAvatarUrl). Sin systemPrompt ni skills. Tenant: empresa activa + ai_assistants. Platform: 200 sin ese add-on. 404 opaco si no es accesible (mismo criterio que el POST de chat)
POST/ai/assistants/:assistantId/chatOWNER, ADMIN, MEMBER, VIEWERMensaje de chat (message, opcional conversationId del mismo assistant y requestId UUID). Repetir el mismo ID + contenido devuelve la respuesta persistida sin repetir el turno; un ID reutilizado con otro contenido devuelve 409. provider no cambia el vendor que resuelve; model puede ser override sujeto a la allowlist del plan para vendors que no son OpenRouter. La respuesta no incluye provider ni model; confirmaciones pendientes y resultados de skills incluyen serviceKey para identificar la operación. 404 si el hilo es de otro assistant
GET/ai/conversations?limit=&offset=OWNER, ADMIN, MEMBER, VIEWERListado paginado interno de conversaciones del usuario autenticado (1–100 filas, offset hasta 1 000 000). No aparece en el SDK/OpenAPI público
GET/ai/conversations/:conversationIdOWNER, ADMIN, MEMBER, VIEWERHistorial + pendings abiertos
POST/ai/conversations/:conversationId/messages/:messageId/interactions/:interactionIdidemEnvía choiceId de una opción persistida; un solo uso y 15 minutos. Continúa el chat sin autorizar skills; 400 si la opción no pertenece al bloque, 409 si caducó o ya se usó
POST/ai/conversations/:conversationId/pending-skills/:pendingId/confirmidemConfirma y ejecuta skill de escritura
POST/ai/conversations/:conversationId/pending-skills/:pendingId/rejectidemRechaza sin ejecutar

Para tests con proveedor noop, un mensaje [[skill:<toolName>]]{…json} hace que el NoOp emita tool_calls (toolName = skill.code o skill.id).

Widget público ​

OWNER/ADMIN publican un assistant como widget sin login de Nimobase. Requiere entitlement ai_public_widget para publicar y para servir peticiones anónimas. Al asignar skills, publicSafeSkillIds marca cuáles son aptas para el widget; en v1 solo riskClass=read.

El chat anónimo imputa uso al tenant propietario vía y aplica límites anti-abuso compartidos de 20 turnos/minuto por IP+assistant, 60 por assistant+tenant y 120 por tenant además del @Throttle de Nest. Despublicar rechaza anónimos. El launcher anónimo lee GET /ai/public/widget/:assistantId para saber si mostrar la bolita : 200 solo si está publicado y, en origin=tenant,

el plan sigue teniendo ai_public_widget. 404 no distingue existencia. OWNER/ADMIN listan y consultan el historial (channel=public).

Un assistant origin=platform publicado puede servirse en este endpoint sin ai_public_widget si hay tenant de petición; si companyId del assistant es null y no hay tenant en el request → 422 AI_PUBLIC_WIDGET_TENANT_REQUIRED. Config Nimobase no se publica en el seed: el launcher anónimo de landing queda como follow-up (el widget público no admite pk_ en la matriz actual y el interceptor de tenant no inventa empresa).

MétodoRutaAuthDescripción
PUT/ai/assistants/:assistantId/public-widgetOWNER, ADMIN{ published: true|false }
GET/ai/assistants/:assistantId/public-widget/conversationsOWNER, ADMINListado de hilos del widget
GET/ai/assistants/:assistantId/public-widget/conversations/:conversationIdOWNER, ADMINDetalle + mensajes
GET/ai/public/widget/:assistantIdPúblicoPresencia publicada (id, origin, presentationName, presentationAvatarUrl, publicWidgetEnabled). 404 opaco si falta, no está publicado o el tenant no tiene ai_public_widget. Sin systemPrompt ni skills. Platform publicado no exige tenant.
POST/ai/public/widget/:assistantId/chatPúblicoChat anónimo (message, opcional conversationId / visitorId). Los campos heredados provider/model se ignoran: el servidor gobierna la selección y reutiliza el modelo resuelto de la conversación; header X-Widget-Visitor-Id opcional. Límites compartidos: 20/min por IP+assistant, 60/min por assistant+tenant y 120/min por tenant; visitorId solo identifica la conversación. La respuesta no incluye provider ni model

Proveedores disponibles ​

ProveedorVariable de entorno / vaultEstado
Anthropic (Claude)ANTHROPIC_API_KEY o secreto vault apiKeyDisponible si hay key
OpenAI (GPT)OPENAI_API_KEY o secreto vault apiKeyDisponible si hay key
Google (Gemini)GOOGLE_API_KEY o secreto vault apiKeyDisponible si hay key
NoOp— (vendor noop en catálogo de providers)Stub determinista para tests

La generación gobernada usa las credenciales resueltas del vault, no solo las variables de entorno.

Cómo se usa desde el código ​

Otros módulos pueden importar AIModule e inyectar AIService:

typescript
import { AIModule } from '../ai/ai.module';

@Module({ imports: [AIModule] })
export class MyModule {}

@Injectable()
export class MyService {
  constructor(private readonly aiService: AIService) {}

  async summarize(text: string): Promise<string> {
    const response = await this.aiService.generate({
      provider: AIProvider.ANTHROPIC,
      model: 'claude-sonnet-4-6',
      messages: [{ role: 'user', content: `Resumir: ${text}` }],
      maxTokens: 500,
    });
    return response.content;
  }
}

Modelos disponibles ​

Anthropic ​

ModeloContextoCapacidades
claude-opus-5200k tokensTexto, visión, tools, structured output, streaming
claude-sonnet-5200k tokensTexto, visión, tools, structured output, streaming
claude-sonnet-4-6200k tokensTexto, visión, tools, structured output, streaming
claude-haiku-4-5-20251001200k tokensTexto, visión, tools, structured output, streaming

OpenAI ​

ModeloContextoCapacidades
gpt-4o128k tokensTexto, visión, tools, structured output, streaming
gpt-4o-mini128k tokensTexto, visión, tools, structured output, streaming
o3200k tokensTexto, tools, streaming
o4-mini128k tokensTexto, visión, tools, streaming

Google ​

ModeloContextoCapacidades
gemini-2.5-pro1M tokensTexto, visión, tools, structured output, streaming
gemini-2.5-flash1M tokensTexto, visión, tools, structured output, streaming
gemini-2.0-flash1M tokensTexto, visión, tools, structured output, streaming

API HTTP ​

Todos los endpoints requieren autenticación (Authorization: Bearer <token>).

GET /ai/providers ​

Devuelve los proveedores disponibles (con credenciales configuradas).

json
{
  "available": ["anthropic", "openai"]
}

GET /ai/models ​

Devuelve todos los modelos registrados. Filtra por proveedor con ?provider=anthropic. ?provider=openrouter devuelve únicamente el Auto Router (openrouter/auto); no hay catálogo vivo de modelos de OpenRouter.

json
{
  "models": [
    {
      "id": "claude-sonnet-4-6",
      "displayName": "Claude Sonnet 4.6",
      "provider": "anthropic",
      "capabilities": [
        "text_generation",
        "vision",
        "tool_calling",
        "structured_output",
        "streaming"
      ],
      "contextWindow": 200000,
      "maxOutputTokens": 8096
    }
  ]
}

POST /ai/generate ​

Generación de texto sincrónica. provider admite anthropic | openai | google | openrouter | noop. Con openrouter el campo model sigue siendo obligatorio en el body, pero el backend lo ignora y usa Auto Router (openrouter/auto).

Body:

json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "messages": [
    { "role": "user", "content": "¿Cuál es la capital de Francia?" }
  ],
  "systemPrompt": "Eres un asistente útil que responde en español.",
  "temperature": 0.7,
  "maxTokens": 500
}

Response:

json
{
  "content": "La capital de Francia es París.",
  "model": "claude-sonnet-4-6",
  "provider": "anthropic",
  "finishReason": "stop",
  "usage": {
    "inputTokens": 28,
    "outputTokens": 12,
    "totalTokens": 40
  }
}

Errores posibles ​

ErrorCausa
404Proveedor no registrado o sin credenciales
400Petición inválida o rechazada por content policy
429 + AI_PROVIDER_RATE_LIMITEDRate limit del proveedor/OpenRouter (distinto de gobernanza)
429 + AI_RATE_LIMIT_EXCEEDEDRate limit anti-abuso de gobernanza
500Error interno del proveedor o fallo de autenticación

Llamadas asíncronas (Jobs) ​

Si no quieres bloquear la respuesta HTTP, usa RunAIRequestJob:

typescript
await this.jobDispatcher.dispatch(
  new RunAIRequestJob({
    provider: AIProvider.ANTHROPIC,
    model: 'claude-sonnet-4-6',
    messages: [{ role: 'user', content: '...' }],
  }),
);

El job se ejecuta en background. Los errores son manejados por el sistema de reintentos.

Eventos del sistema ​

El módulo publica dos eventos automáticamente:

EventoCuándo se emitePayload
ai.request-completedGeneración exitosaprovider, model, inputTokens, outputTokens, durationMs
ai.governed-usage-recordedTras generate gobernado exitosometadatos de uso (classification, saldoImpact, …) — sin prompts
ai.overage-saldo-creditedTras recarga de saldoamountMinorUnits, saldoMinorUnitsAfter, paymentReference
ai.request-failedError en la generaciónprovider, model, errorType, durationMs

Nota de seguridad: los prompts y respuestas completas NO se incluyen en eventos. Solo se registran metadatos de uso.

Configuración ​

Añade las variables de entorno correspondientes a los proveedores que quieras usar:

env
# Uno o más de estos:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GOOGLE_API_KEY=AIza...

Sin credenciales configuradas, el sistema funciona con el proveedor noop (respuestas de placeholder) — útil en desarrollo.

Añadir un nuevo proveedor ​

  1. Añadir el identificador al enum AIProvider en src/api/ai/constants/ai-provider.enum.ts
  2. Crear src/api/ai/providers/<nombre>/<nombre>.provider.ts implementando IAIProvider
  3. Documentar la variable de entorno del API key
  4. Registrar el proveedor en src/api/ai/ai.module.ts dentro del factory de AIProviderRegistry
  5. Añadir definiciones de modelos en src/api/ai/models/<nombre>.models.ts
  6. Añadir tests en src/api/ai/providers/<nombre>/<nombre>.provider.spec.ts

Ningún código consumidor necesita cambios.

Lo que NO hace (todavía) ​

  • Streaming de tokens en tiempo real
  • Embeddings, generación de imágenes, audio
  • Agentes autónomos / RAG
  • Fallback automático entre proveedores
  • Checkout Stripe embebido para recarga (el crédito interno es el hook post-pago)

Inventario de formularios y capacidades NimoApps ​

El formulario administrativo actual vive en frontend/src/app/features/app-projects/app-projects.page.ts y app-projects.page.html. La SPA usa ApplicationEnvironmentsInternalService como transporte interno. Nimo tenant usa ApplicationProjectsAssistantSkillHandler, registrado en AssistantSkillServiceRegistry; el handler invoca servicios backend con el contexto autenticado, no el SDK público. En cada ejecución el servidor vuelve a exigir sesión de usuario, empresa activa y membresía OWNER/ADMIN vigente. El entitlement de Nimo tenant es ai_assistants (assistant-feature). El widget público es independiente y este handler devuelve isWidgetEligible: false. Los owners de pruebas abreviados como “handler” y “catálogo” en la tabla son backend-api/src/api/assistants/application-projects-assistant-skill.handler.spec.ts y backend-api/src/api/assistants/chat/assistant-capability.registry.spec.ts.

Formulario/acciónAPI interna → cliente SPANimo interno: serviceKey → handlerRiesgo, alcance, permiso efectivo, entitlement y confirmaciónTests dueños
Listar y seleccionar proyectoGET /app-projects → listProjectsapp-projects.list → ApplicationEnvironmentsService.listProjectsRead, tenant; OWNER/ADMIN; ai_assistants; sin confirmaciónNimo: application-projects-assistant-skill.handler.spec.ts; catálogo: assistant-capability.registry.spec.ts; API y SPA: tests de servicio y página
Crear proyecto y entornos inicialesPOST /app-projects → createProjectapp-projects.create → ApplicationEnvironmentsService.createProjectWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaNimo: application-projects-assistant-skill.handler.spec.ts; catálogo: assistant-capability.registry.spec.ts; API/SPA: tests de servicio y página
Consultar entornosGET /app-projects/:id/environments → listEnvironmentsapp-projects.environments.list → ApplicationEnvironmentsService.listEnvironmentsRead, tenant; OWNER/ADMIN efectivo; ai_assistants; sin confirmaciónHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts
Crear release inmutablePOST /app-projects/:id/releases → createReleaseapp-projects.releases.create → ApplicationEnvironmentsService.createReleaseWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícita. Crear release no construye ni despliegaHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts
Construir artifact de release (sin formulario separado)POST /app-projects/:projectId/releases/:releaseId/artifact → buildReleaseArtifactapp-projects.artifacts.build → handler interno de proyectosWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaapplication-projects-assistant-skill.handler.spec.ts; servicio de deployments
Leer artifact de release (sin formulario separado)GET /app-projects/:projectId/releases/:releaseId/artifact → getReleaseArtifactapp-projects.artifacts.get → handler interno de proyectosRead, tenant; OWNER/ADMIN efectivo; ai_assistants; sin confirmaciónHandler y catálogo; pruebas del servicio de deployments
Consultar conexiones por entornoGET /app-projects/:projectId/environments/:environmentId/connections → getConnectionsapp-projects.connections.get → ApplicationEnvironmentsService.getConnectionsRead, tenant; OWNER/ADMIN efectivo; ai_assistants; sin confirmación. Solo devuelve referencias/diagnósticos, nunca credencialesHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts
Guardar conexiones del entornoPUT /app-projects/:projectId/environments/:environmentId/connections → updateConnectionsapp-projects.connections.update → ApplicationEnvironmentsService.updateConnectionsWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícita. Preview no acepta referencias productivasHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts
Iniciar despliegue durablePOST /app-operations → createOperationapp-projects.operations.create → AppOperationsService.createWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícita. Aceptación no equivale a éxito del despliegueHandler, catálogo y tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts
Consultar estado de operaciónGET /app-operations/:id → getOperationapp-projects.operations.get → AppOperationsService.getRead, tenant; OWNER/ADMIN efectivo; ai_assistants; sin confirmaciónHandler y catálogo; app-operations.service.spec.ts; app-projects.page.spec.ts
Cancelar despliegue pendientePOST /app-operations/:id/cancel → cancelOperationapp-projects.operations.cancel → AppOperationsService.cancelDestructive, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaHandler, catálogo y tenant-assistant-chat.service.spec.ts; app-operations.service.spec.ts; app-projects.page.spec.ts
Listar orígenes runtimeGET /app-projects/:projectId/environments/:environmentId/runtime-origins → listRuntimeOriginsapp-projects.runtime-origins.list → handler interno de proyectosRead, tenant; OWNER/ADMIN efectivo; ai_assistants; sin confirmaciónHandler y catálogo; runtime-origin.spec.ts; página SPA
Registrar origen runtimePOST /app-projects/:projectId/environments/:environmentId/runtime-origins → createRuntimeOriginapp-projects.runtime-origins.register → handler interno de proyectosWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaHandler y catálogo; runtime-origin.spec.ts; app-projects.page.spec.ts
Retirar origen runtimeDELETE /app-projects/:projectId/environments/:environmentId/runtime-origins/:originId → retireRuntimeOriginapp-projects.runtime-origins.retire → handler interno de proyectosDestructive, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaHandler y catálogo; runtime-origin.spec.ts; app-projects.page.spec.ts
Emitir sesión runtime limitadaPOST /app-projects/:projectId/environments/:environmentId/runtime-sessions → createRuntimeSessionapp-projects.runtime-sessions.issue → handler interno de proyectosWrite, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts
Revocar sesión runtime propiaDELETE /app-projects/runtime-sessions/:id → revokeRuntimeSessionapp-projects.runtime-sessions.revoke → handler interno de proyectosDestructive, tenant; OWNER/ADMIN; ai_assistants; confirmación explícitaHandler y catálogo; application-environments.service.spec.ts; app-projects.page.spec.ts

Los permisos mostrados reflejan la revalidación efectiva del servidor. Toda lectura de app-projects declara OWNER or ADMIN, que es lo que exige ApplicationEnvironmentsService.requireAdmin en cada llamada; antes el metadato genérico decía “authenticated tenant session” y describía menos de lo que el servidor validaba. El catálogo no concede autoridad: la incorporación de app-projects.list alineó el permiso declarativo de las lecturas existentes sin ampliar ningún guard.

Superficies públicas y operaciones globales ​

  • SDK público: packages/sdk-typescript/src/index.ts reexporta paths desde generated/openapi.ts. El contrato contiene 12 rutas internas de /app-projects y /app-operations; además, los schemas de /ai/skills y /ai/assistants incluyen literales app-projects.* en serviceKey. No hay helpers de alto nivel para administrar NimoApps, pero rutas y tipos ya exponen esos detalles a integradores. Esto es una exposición del contrato; no salta los guards del backend. Las pruebas de contrato cubren rutas, schemas y la frontera interna/pública.
  • Otros paths: el contrato exportado no contiene rutas /app-deployments, dominios ni Git. /application-dsl conserva la autoría de definiciones, publicación, roles y APIs de runtime preexistentes; es una capacidad previa separada y se preserva fuera del control-plane nuevo de proyectos/hosting. El follow-up auditará el contrato externo completo antes de cerrar la frontera.
  • MCP externo: packages/mcp-server/src/tool-registry.ts mantiene NIMOBASE_TOOL_REGISTRY manual. No hay tools administrativas de proyectos, entornos, releases, conexiones, despliegues, dominios o Git. Las herramientas de runtime y datos ya existentes conservan su alcance actual.
  • Chat embebible: el registro del widget es independiente y las operaciones del handler de proyectos no son elegibles. El control-plane no se añade al widget.
  • Runtime público: los endpoints de ejecución de artifacts, datos y APIs runtime limitadas permanecen separados de estas rutas administrativas; aquí no se eliminan ni amplían.

Las operaciones globales no son formularios tenant de NimoApps. settings.get es read/platform, sin entitlement ni confirmación; settings.put y maintenance.set son write/platform, requieren Super Admin y confirmación. El executor solo las permite desde el assistant de plataforma y revalida Super Admin; el tenant assistant se deniega incluso si recibe una skill compartible. Test: backend-api/src/api/assistants/chat/assistant-skill-executor.spec.ts. No se cambian reglas globales.

La frontera arquitectónica ya está documentada: Nimo interno y transporte interno de plataforma; sin administración nueva por SDK público, MCP externo ni chat embebible; runtime público limitado preservado. El gap del OpenAPI generado queda como seguimiento y no cambia la autoridad definida por el catálogo.