@tiledesk/tiledesk-server 2.29.0 → 3.0.0

package/pubmodules/aiGenerations/routes/aiGenerations.js

@@ -0,0 +1,426 @@
+/**
+ * Rotte del modulo aiGenerations, montate su `/:projectid/modules/ai-generations` (ruolo admin).
+ *
+ *  GET    /                                   stato del modulo
+ *  POST   /agents                             crea un agente con l'AI, in modo atomico, con la revisione 1
+ *  GET    /agents/:id_faq_kb/revisions        la storia (leggera), a pagine
+ *  POST   /agents/:id_faq_kb/revisions        checkpoint della bozza
+ *  POST   /agents/:id_faq_kb/revisions/release collega una release pubblicata
+ *  GET    /agents/:id_faq_kb/hash             impronta corrente e ultima revisione
+ *  POST   /agents/:id_faq_kb/restore          ripristina una revisione o una release, in place o come copia
+ *  POST   /agents/:id_faq_kb/edit             applica operazioni sui blocchi e registra la revisione ai_edit
+ *  DELETE /agents/:id_faq_kb/revisions        cancella la storia
+ *  GET    /revisions/:revision_id             una revisione completa (?snapshot=true aggiunge lo snapshot)
+ */
+const express = require('express');
+const mongoose = require('mongoose');
+const winston = require('../../../config/winston');
+const Faq_kb = require('../../../models/faq_kb');
+const revisionService = require('../services/revisionService');
+const agentWriter = require('../services/agentWriter');
+const atomic = require('../services/atomic');
+const snapshotUtil = require('../services/snapshot');
+const references = require('../services/references');
+
+const router = express.Router({ mergeParams: true });
+
+const MAX_INTENTS = Number(process.env.AI_GENERATIONS_MAX_INTENTS) || 1000;
+const MAX_LIMIT = 50;
+
+function isObjectId(id) {
+  return typeof id === 'string' && mongoose.Types.ObjectId.isValid(id) && /^[0-9a-fA-F]{24}$/.test(id);
+}
+
+function fail(res, err, context) {
+  const status = (err && err.status) || 500;
+  if (status >= 500) winston.error('(aiGenerations) ' + context + ': ' + (err && err.stack || err));
+  else winston.debug('(aiGenerations) ' + context + ': ' + (err && err.message));
+  return res.status(status).send({ success: false, message: (err && err.message) || 'Error', details: err && err.details });
+}
+
+function badRequest(message, details) {
+  const err = new Error(message);
+  err.status = 400;
+  err.details = details;
+  return err;
+}
+
+function conflict(message, details) {
+  const err = new Error(message);
+  err.status = 409;
+  err.details = details;
+  return err;
+}
+
+function notFound(message) {
+  const err = new Error(message);
+  err.status = 404;
+  return err;
+}
+
+/** Il blocco `ai` del body, ripulito: solo request e result, oggetti. */
+function aiBlock(body) {
+  if (!body.ai) return undefined;
+  if (typeof body.ai !== 'object') throw badRequest('ai must be an object');
+  const ai = {};
+  if (body.ai.request !== undefined) {
+    if (typeof body.ai.request !== 'object') throw badRequest('ai.request must be an object');
+    ai.request = body.ai.request;
+  }
+  if (body.ai.result !== undefined) {
+    if (typeof body.ai.result !== 'object') throw badRequest('ai.result must be an object');
+    ai.result = body.ai.result;
+  }
+  return ai;
+}
+
+function validateIntents(intents) {
+  if (!Array.isArray(intents) || !intents.length) throw badRequest('agent.intents must be a non-empty array');
+  if (intents.length > MAX_INTENTS) throw badRequest('too many blocks', { max: MAX_INTENTS });
+  const names = new Set();
+  const ids = new Set();
+  intents.forEach((intent, index) => {
+    if (!intent || typeof intent !== 'object') throw badRequest('agent.intents[' + index + '] must be an object');
+    if (!intent.intent_display_name) throw badRequest('agent.intents[' + index + '].intent_display_name is required');
+    if (names.has(intent.intent_display_name)) throw badRequest('duplicate intent_display_name', { intent_display_name: intent.intent_display_name });
+    names.add(intent.intent_display_name);
+    if (intent.intent_id) {
+      if (ids.has(intent.intent_id)) throw badRequest('duplicate intent_id', { intent_id: intent.intent_id });
+      ids.add(intent.intent_id);
+    }
+  });
+}
+
+/** L'agente del progetto, non cestinato; 404 o 409 altrimenti. */
+async function loadAgent(req) {
+  const id_faq_kb = req.params.id_faq_kb;
+  if (!isObjectId(id_faq_kb)) throw badRequest('invalid id_faq_kb');
+  const kb = await revisionService.getAgent(req.projectid, id_faq_kb);
+  if (!kb) throw notFound('Chatbot not found with id ' + id_faq_kb + ' for project ' + req.projectid);
+  if (kb.trashed === true) throw conflict('Chatbot ' + id_faq_kb + ' is trashed');
+  return kb;
+}
+
+/**
+ * Se i blocchi correnti sono diversi dall'ultima revisione con snapshot, salva una revisione `auto`
+ * della versione corrente. Restituisce la revisione creata, oppure null.
+ */
+async function backupIfChanged(req, state, reason, session) {
+  const last = await revisionService.lastRevision(req.projectid, String(state.kb._id), { contentHash: { $ne: null } }, session);
+  if (last && last.contentHash === state.contentHash) return null;
+  return revisionService.create({
+    id_project: req.projectid,
+    id_faq_kb: state.kb._id,
+    kind: 'auto',
+    reason: reason,
+    note: last ? 'Modifiche successive alla revisione ' + last.seq : 'Stato precedente',
+    parent_id: last ? last.revision_id : null,
+    snapshot: state.snapshot,
+    contentHash: state.contentHash,
+    createdBy: req.user.id
+  }, session);
+}
+
+function checkExpectedHash(body, state) {
+  if (body.expectedHash && body.expectedHash !== state.contentHash) {
+    throw conflict('The chatbot has been modified: expected hash does not match', { expectedHash: body.expectedHash, contentHash: state.contentHash });
+  }
+}
+
+// ---------------------------------------------------------------------------------------------
+
+router.get('/', async (req, res) => {
+  try {
+    res.json({ enabled: true, module: 'aiGenerations', transactions: await atomic.supportsTransactions(), max_intents: MAX_INTENTS });
+  } catch (err) {
+    fail(res, err, 'status');
+  }
+});
+
+/** Creazione atomica di un agente con l'AI. Body: { agent, ai, note }. */
+router.post('/agents', async (req, res) => {
+  try {
+    const agent = req.body.agent;
+    if (!agent || typeof agent !== 'object') throw badRequest('agent is required');
+    if (!agent.name || typeof agent.name !== 'string') throw badRequest('agent.name is required');
+    validateIntents(agent.intents);
+    const ai = aiBlock(req.body);
+
+    const created = await agentWriter.createAgent(req.projectid, req.user.id, agent);
+    const state = await revisionService.currentState(created.kb);
+    let revision;
+    try {
+      revision = await revisionService.create({
+        id_project: req.projectid,
+        id_faq_kb: created.kb._id,
+        kind: 'ai_create',
+        note: req.body.note || 'Creato con l\'AI',
+        ai: ai,
+        snapshot: state.snapshot,
+        contentHash: state.contentHash,
+        createdBy: req.user.id
+      });
+    } catch (err) {
+      winston.error('(aiGenerations) revision failed after creation, removing chatbot ' + created.kb._id + ': ' + err.message);
+      await mongoose.model('faq').deleteMany({ id_faq_kb: String(created.kb._id) }).exec().catch(() => null);
+      await Faq_kb.findByIdAndDelete(created.kb._id).exec().catch(() => null);
+      throw err;
+    }
+
+    agentWriter.emitEvents({ createdFaqs: created.faqs, createdBot: { req: req, chatbot: created.kb } });
+    res.status(201).send({ bot_id: String(created.kb._id), chatbot: created.kb, revision: revisionService.light(revision) });
+  } catch (err) {
+    fail(res, err, 'POST /agents');
+  }
+});
+
+router.get('/agents/:id_faq_kb/revisions', async (req, res) => {
+  try {
+    const kb = await revisionService.getAgent(req.projectid, req.params.id_faq_kb).catch(() => null);
+    if (!kb) throw notFound('Chatbot not found with id ' + req.params.id_faq_kb + ' for project ' + req.projectid);
+    const page = Math.max(0, parseInt(req.query.page, 10) || 0);
+    const limit = Math.min(MAX_LIMIT, Math.max(1, parseInt(req.query.limit, 10) || 20));
+    res.json(await revisionService.list(req.projectid, String(kb._id), page, limit));
+  } catch (err) {
+    fail(res, err, 'GET revisions');
+  }
+});
+
+/** Checkpoint della bozza. Body: { note }. */
+router.post('/agents/:id_faq_kb/revisions', async (req, res) => {
+  try {
+    const kb = await loadAgent(req);
+    const state = await revisionService.currentState(kb);
+    const last = await revisionService.lastRevision(req.projectid, String(kb._id));
+    const revision = await revisionService.create({
+      id_project: req.projectid,
+      id_faq_kb: kb._id,
+      kind: 'checkpoint',
+      note: req.body.note || 'Versione salvata',
+      parent_id: last ? last.revision_id : null,
+      snapshot: state.snapshot,
+      contentHash: state.contentHash,
+      createdBy: req.user.id
+    });
+    await revisionService.prune(req.projectid, String(kb._id));
+    res.status(201).send({ revision: revisionService.light(revision) });
+  } catch (err) {
+    fail(res, err, 'POST checkpoint');
+  }
+});
+
+/** Collega una release pubblicata. Body: { release_id }. */
+router.post('/agents/:id_faq_kb/revisions/release', async (req, res) => {
+  try {
+    const kb = await loadAgent(req);
+    const release_id = req.body.release_id;
+    if (!isObjectId(release_id)) throw badRequest('release_id is required');
+    const release = await Faq_kb.findOne({ _id: release_id, id_project: req.projectid, root_id: String(kb._id) }).exec();
+    if (!release) throw notFound('Release ' + release_id + ' not found for chatbot ' + kb._id);
+    const existing = await revisionService.lastRevision(req.projectid, String(kb._id), { kind: 'release', release_id: release_id });
+    if (existing) return res.status(200).send({ revision: revisionService.light(existing), already_linked: true });
+    const last = await revisionService.lastRevision(req.projectid, String(kb._id));
+    const revision = await revisionService.create({
+      id_project: req.projectid,
+      id_faq_kb: kb._id,
+      kind: 'release',
+      note: req.body.note || release.release_note || undefined,
+      parent_id: last ? last.revision_id : null,
+      contentHash: last ? last.contentHash : null,
+      release_id: release_id,
+      publishedAt: release.publishedAt || new Date(),
+      createdBy: req.user.id
+    });
+    res.status(201).send({ revision: revisionService.light(revision) });
+  } catch (err) {
+    fail(res, err, 'POST release');
+  }
+});
+
+router.get('/agents/:id_faq_kb/hash', async (req, res) => {
+  try {
+    const kb = await loadAgent(req);
+    const state = await revisionService.currentState(kb);
+    const last = await revisionService.lastRevision(req.projectid, String(kb._id), { contentHash: { $ne: null } });
+    res.json({
+      contentHash: state.contentHash,
+      intents: state.faqs.length,
+      revision_id: last ? last.revision_id : null,
+      revision_seq: last ? last.seq : null,
+      modified: last ? last.contentHash !== state.contentHash : null
+    });
+  } catch (err) {
+    fail(res, err, 'GET hash');
+  }
+});
+
+/** Lo snapshot da ripristinare: da una revisione o da una release. */
+async function loadSource(req, kb) {
+  const body = req.body || {};
+  if (body.revision_id) {
+    const revision = await revisionService.getRevision(req.projectid, body.revision_id);
+    if (!revision || revision.id_faq_kb !== String(kb._id)) throw notFound('Revision ' + body.revision_id + ' not found for chatbot ' + kb._id);
+    const snapshot = snapshotUtil.decompress(revision.snapshot);
+    if (!snapshot) throw conflict('Revision ' + body.revision_id + ' has no snapshot (kind ' + revision.kind + ')');
+    return { snapshot: snapshot, parent_id: revision.revision_id, label: 'revisione ' + revision.seq };
+  }
+  if (body.release_id) {
+    if (!isObjectId(body.release_id)) throw badRequest('invalid release_id');
+    const release = await Faq_kb.findOne({ _id: body.release_id, id_project: req.projectid, root_id: String(kb._id) }).exec();
+    if (!release) throw notFound('Release ' + body.release_id + ' not found for chatbot ' + kb._id);
+    const state = await revisionService.currentState(release);
+    const linked = await revisionService.lastRevision(req.projectid, String(kb._id), { kind: 'release', release_id: body.release_id });
+    return { snapshot: state.snapshot, parent_id: linked ? linked.revision_id : null, label: 'release ' + body.release_id };
+  }
+  throw badRequest('revision_id or release_id is required');
+}
+
+/**
+ * Ripristino. Body: { revision_id | release_id, as_copy, expectedHash, note, name, dry_run }.
+ * Con `dry_run: true` non scrive nulla: risponde con i riferimenti esterni dello snapshot che nel progetto
+ * non esistono più (dipartimenti, knowledge base, tabelle, agenti) e con l'impronta corrente.
+ */
+router.post('/agents/:id_faq_kb/restore', async (req, res) => {
+  try {
+    const kb = await loadAgent(req);
+    const source = await loadSource(req, kb);
+    validateIntents(source.snapshot.intents);
+
+    if (req.body.dry_run === true) {
+      const state = await revisionService.currentState(kb);
+      const missing = await references.missingReferences(source.snapshot, req.projectid);
+      return res.status(200).send({
+        dry_run: true,
+        source: source.label,
+        intents: source.snapshot.intents.length,
+        contentHash: state.contentHash,
+        changed: !!req.body.expectedHash && req.body.expectedHash !== state.contentHash,
+        missing: missing
+      });
+    }
+
+    if (req.body.as_copy === true) {
+      const copy = Object.assign({}, source.snapshot, { name: req.body.name || (source.snapshot.name + ' (copia)') });
+      const created = await agentWriter.createAgent(req.projectid, req.user.id, copy);
+      const state = await revisionService.currentState(created.kb);
+      const revision = await revisionService.create({
+        id_project: req.projectid,
+        id_faq_kb: created.kb._id,
+        kind: 'restore',
+        reason: 'as_copy',
+        note: req.body.note || ('Copia di ' + kb.name + ', ' + source.label),
+        parent_id: source.parent_id,
+        snapshot: state.snapshot,
+        contentHash: state.contentHash,
+        createdBy: req.user.id
+      });
+      agentWriter.emitEvents({ createdFaqs: created.faqs, createdBot: { req: req, chatbot: created.kb } });
+      return res.status(201).send({ bot_id: String(created.kb._id), chatbot: created.kb, revision: revisionService.light(revision), backup: null });
+    }
+
+    const state = await revisionService.currentState(kb);
+    checkExpectedHash(req.body, state);
+
+    const outcome = await atomic.run(async (session) => {
+      const backup = await backupIfChanged(req, state, 'before_restore', session);
+      const replaced = await agentWriter.replaceBlocks(kb, source.snapshot, req.projectid, req.user.id, session);
+      const updatedBot = await agentWriter.updateAgentFromSnapshot(kb, source.snapshot, session);
+      const after = await revisionService.currentState(updatedBot, session);
+      const revision = await revisionService.create({
+        id_project: req.projectid,
+        id_faq_kb: kb._id,
+        kind: 'restore',
+        reason: 'in_place',
+        note: req.body.note || ('Ripristino della ' + source.label),
+        parent_id: source.parent_id,
+        snapshot: after.snapshot,
+        contentHash: after.contentHash,
+        createdBy: req.user.id
+      }, session);
+      return { backup: backup, replaced: replaced, updatedBot: updatedBot, revision: revision };
+    });
+
+    agentWriter.emitEvents({ deletedFaqs: outcome.replaced.removed, createdFaqs: outcome.replaced.inserted, updatedBot: outcome.updatedBot });
+    await revisionService.prune(req.projectid, String(kb._id));
+    res.status(200).send({ bot_id: String(kb._id), revision: revisionService.light(outcome.revision), backup: revisionService.light(outcome.backup) });
+  } catch (err) {
+    fail(res, err, 'POST restore');
+  }
+});
+
+/** Modifica via prompt. Body: { operations, ai, expectedHash, note }. */
+router.post('/agents/:id_faq_kb/edit', async (req, res) => {
+  try {
+    const kb = await loadAgent(req);
+    const operations = req.body.operations;
+    if (!Array.isArray(operations) || !operations.length) throw badRequest('operations must be a non-empty array');
+    if (operations.length > MAX_INTENTS) throw badRequest('too many operations', { max: MAX_INTENTS });
+    const ai = aiBlock(req.body) || {};
+
+    const state = await revisionService.currentState(kb);
+    checkExpectedHash(req.body, state);
+
+    const outcome = await atomic.run(async (session) => {
+      const backup = await backupIfChanged(req, state, 'before_ai_edit', session);
+      let applied;
+      try {
+        applied = await agentWriter.applyOperations(kb, operations, req.projectid, req.user.id, session);
+      } catch (err) {
+        if (!session) {
+          // Senza transazione: si rimettono i blocchi di prima, poi si rilancia.
+          await agentWriter.replaceBlocks(kb, state.snapshot, req.projectid, req.user.id, null).catch(e => winston.error('(aiGenerations) edit recovery failed: ' + e.message));
+        }
+        throw err;
+      }
+      const updatedBot = await agentWriter.setModified(kb._id, session);
+      const after = await revisionService.currentState(updatedBot, session);
+      const last = await revisionService.lastRevision(req.projectid, String(kb._id), null, session);
+      const changes = {
+        added: applied.created.map(f => f.intent_id),
+        updated: applied.updated.map(f => f.intent_id),
+        removed: applied.deleted.map(f => f.intent_id)
+      };
+      const aiWithChanges = Object.assign({}, ai, { result: Object.assign({}, ai.result || {}, { changes: changes }) });
+      const revision = await revisionService.create({
+        id_project: req.projectid,
+        id_faq_kb: kb._id,
+        kind: 'ai_edit',
+        note: req.body.note || 'Modificato con l\'AI',
+        parent_id: last ? last.revision_id : null,
+        ai: aiWithChanges,
+        snapshot: after.snapshot,
+        contentHash: after.contentHash,
+        createdBy: req.user.id
+      }, session);
+      return { backup: backup, applied: applied, updatedBot: updatedBot, revision: revision, changes: changes };
+    });
+
+    agentWriter.emitEvents({ deletedFaqs: outcome.applied.deleted, createdFaqs: outcome.applied.created, updatedFaqs: outcome.applied.updated, updatedBot: outcome.updatedBot });
+    await revisionService.prune(req.projectid, String(kb._id));
+    res.status(200).send({ bot_id: String(kb._id), revision: revisionService.light(outcome.revision), backup: revisionService.light(outcome.backup), changes: outcome.changes });
+  } catch (err) {
+    fail(res, err, 'POST edit');
+  }
+});
+
+router.delete('/agents/:id_faq_kb/revisions', async (req, res) => {
+  try {
+    if (!isObjectId(req.params.id_faq_kb)) throw badRequest('invalid id_faq_kb');
+    const deleted = await revisionService.deleteAll(req.projectid, req.params.id_faq_kb);
+    res.json({ success: true, deleted: deleted });
+  } catch (err) {
+    fail(res, err, 'DELETE revisions');
+  }
+});
+
+router.get('/revisions/:revision_id', async (req, res) => {
+  try {
+    const revision = await revisionService.getRevision(req.projectid, req.params.revision_id);
+    if (!revision) throw notFound('Revision ' + req.params.revision_id + ' not found');
+    res.json(revisionService.full(revision, req.query.snapshot === 'true'));
+  } catch (err) {
+    fail(res, err, 'GET revision');
+  }
+});
+
+module.exports = router;