Quickstart: configurar un caso de cero

Vamos a configurar un caso completo sobre Mentat y operarlo de punta a punta. Como ejemplo usamos el piloto de referencia “Operaciones de Soporte” (gestión de tickets), que ya vive versionado en el repo y está probado en producción.

Al terminar vas a tener: una Ontología (Cliente, Agente, Ticket), Actions (cerrar / reasignar / escalar), una fuente CSV con upsert, y un operador resolviendo un caso.

Dos caminos para cargar la config. Recomendamos el template + loader (reproducible, versionable en git, ejerce las callables reales). La UI sirve para explorar o ajustar puntualmente. Acá mostramos el primero; las pantallas de la UI están en cada guía (Ontología, Actions, DataSources).

Prerrequisitos

Una organización sembrada con vos como admin (el onboarding se cubre en su guía; en local, pnpm seed:emulator).
El repo clonado con dependencias instaladas (pnpm install).

El caso, como template

La config de un caso es un JSON versionado. El del piloto vive en scripts/pilot/reference-pilot.json y declara los tres tipos, las tres acciones y la fuente CSV. Su forma (recortada):

{
  "ontologyTypes": [
    { "id": "Cliente", "category": "core", "properties": [ /* nombre, email, plan(enum) */ ], "links": [] },
    { "id": "Agente",  "category": "core", "properties": [ /* nombre, activo(bool) */ ], "links": [] },
    {
      "id": "Ticket", "category": "use_case",
      "properties": [
        { "name": "estado", "type": "enum", "enumValues": ["abierto","en_progreso","resuelto","cerrado"], "required": true },
        { "name": "asignadoA", "type": "reference", "referenceType": "Agente" }
        /* + titulo, prioridad, canal, externalRef */
      ],
      "links": [ { "name": "solicitadoPor", "targetType": "Cliente", "cardinality": "one_to_one" } ]
    }
  ],
  "actionTypes": [ /* cerrarTicket, reasignarTicket, escalarPrioridad */ ],
  "dataSources": [ /* ticketsCsv: upsert por externalRef */ ]
}

El orden de ontologyTypes es de dependencia: los tipos referenciados (Cliente, Agente) van antes de Ticket, que los usa.

Pasos

Cargar la config

El loader firma como el admin de la org e invoca las callables reales (createOntologyType, createActionType, createDataSource), idempotente:

pnpm emulators                       # build functions + suite
pnpm seed:emulator                   # admin@demo.test + org-demo
node scripts/pilot/load-config.mjs   # carga Ontología + Actions + DataSources

Deberías ver ✓ Cliente, ✓ Agente, ✓ Ticket, las tres actions y ✓ ticketsCsv.

Poblar datos

Manualmente (creás objetos por la UI en /objects) o por ingesta: subís un CSV y la fuente lo materializa, haciendo upsert por la clave natural (externalRef). Re-ingestar el mismo archivo actualiza, no duplica.

# (ejemplo del piloto, contra emulador)
node scripts/pilot/e2e-pilot.mjs    # crea muestras + ingesta CSV + valida

Operar el caso

Un operator entra a /inbox, filtra su cola (ej. tickets abierto), abre un ticket y ejecuta la acción que corresponde — cerrarTicket. El motor:

valida el rol (permission),
chequea la precondición (stateCheck: no se puede cerrar uno ya cerrado),
aplica el cambio en una transacción atómica (estado → cerrado, version++),
escribe el ActionExecution inmutable + el AuditEvent.

Verificar

En /dashboard ves los conteos por tipo y el feed de actividad (la ejecución que acabás de correr aparece ahí). El cambio quedó auditado y es inmutable.

Qué acabás de lograr

Configuraste un caso real sin escribir código de plataforma: solo datos de configuración (el template) cargados por las callables. Ese mismo template, con los tipos/acciones/fuentes del cliente real, es lo que se carga a producción.

Siguientes pasos

Modelar la Ontología en detalle (properties, links, integridad, versionado).
Definir Actions (rules, stateCheck, side effects y sus límites).
Configurar DataSources (CSV / REST / webhook, mappings, scheduler).
Onboarding y usuarios para dar de alta al equipo del cliente.

Conceptos Modelar la Ontología