From 63ad2fc97082f43b75cc28caf3c3d1e768a48140 Mon Sep 17 00:00:00 2001
From: Christian Beeznest <christian.fasanando@beeznest.com>
Date: Thu, 15 Jan 2026 02:08:43 -0500
Subject: [PATCH 1/3] Chat: Add global chat AI tutor: exam lock, prompt, and
 history - refs #7306

---
 assets/vue/components/chat/DockedChat.vue     | 790 ++++++++++++------
 public/main/inc/lib/chat.lib.php              | 308 +++++--
 public/main/inc/lib/exercise.lib.php          |  45 +-
 .../AiChatCompletionClientInterface.php       |  24 +
 .../AiProvider/AiChatCompletionResult.php     |  18 +
 .../AiProvider/AiTutorChatService.php         | 456 ++++++++++
 .../DefaultAiChatCompletionClient.php         | 205 +++++
 .../AiProvider/GrokDocumentProvider.php       | 154 ----
 .../AiProvider/GrokImageProvider.php          | 150 ----
 src/CoreBundle/AiProvider/OpenAiProvider.php  | 335 ++++++++
 src/CoreBundle/Controller/ChatController.php  | 659 +++++++++++++--
 src/CoreBundle/Entity/AiTutorConversation.php |   3 +-
 src/CoreBundle/Entity/AiTutorMessage.php      |   3 +-
 src/CoreBundle/Entity/Chat.php                |   7 +-
 src/CoreBundle/Helpers/AiHelper.php           | 242 ++++++
 src/CoreBundle/Helpers/LanguageHelper.php     | 103 ++-
 .../AiTutorConversationRepository.php         |  77 ++
 src/CoreBundle/Repository/ChatRepository.php  |  73 ++
 .../Repository/LanguageRepository.php         |   2 +-
 src/CoreBundle/Resources/config/services.yml  |   4 +
 .../Resources/views/Chat/chat.html.twig       |  79 +-
 21 files changed, 3016 insertions(+), 721 deletions(-)
 create mode 100644 src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
 create mode 100644 src/CoreBundle/AiProvider/AiChatCompletionResult.php
 create mode 100644 src/CoreBundle/AiProvider/AiTutorChatService.php
 create mode 100644 src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
 delete mode 100644 src/CoreBundle/AiProvider/GrokDocumentProvider.php
 delete mode 100644 src/CoreBundle/AiProvider/GrokImageProvider.php
 create mode 100644 src/CoreBundle/Helpers/AiHelper.php
 create mode 100644 src/CoreBundle/Repository/AiTutorConversationRepository.php
 create mode 100644 src/CoreBundle/Repository/ChatRepository.php

diff --git a/assets/vue/components/chat/DockedChat.vue b/assets/vue/components/chat/DockedChat.vue
index 8ef55a3c5db..3b0d3417c63 100644
--- a/assets/vue/components/chat/DockedChat.vue
+++ b/assets/vue/components/chat/DockedChat.vue
@@ -1,6 +1,9 @@
 <template>
   <Teleport to="body">
-    <div class="chd">
+    <div
+      v-if="canRenderDock"
+      class="chd"
+    >
       <!-- FAB -->
       <button
         class="chd-fab"
@@ -59,6 +62,34 @@
               </button>
             </div>
 
+            <!-- AI Tutor quick entry (only when course context is available) -->
+            <div
+              v-if="tutorCtx.enabled && !contactsHasAiTutor"
+              class="chd-ai"
+            >
+              <button
+                class="chd-ai__btn"
+                :class="{ 'is-active': Number(activePeer?.id || 0) === AI_PEER_ID }"
+                @click="openConversation({ id: AI_PEER_ID, name: t('AI Tutor'), image: '' })"
+                :disabled="tutorCtx.inTest"
+                :title="tutorCtx.inTest ? t('AI tutor is disabled during tests') : t('AI Tutor')"
+              >
+                <i class="mdi mdi-robot-outline" />
+                <span class="chd-truncate">{{ t("AI Tutor") }}</span>
+                <span
+                  class="chd-presence on"
+                  aria-hidden="true"
+                />
+              </button>
+
+              <p
+                v-if="tutorCtx.inTest"
+                class="chd-text--muted chd-ai__hint"
+              >
+                {{ t("AI tutor is disabled during tests") }}
+              </p>
+            </div>
+
             <div
               class="chd-contacts"
               @scroll.passive="onContactsScroll"
@@ -164,7 +195,7 @@
               <textarea
                 v-model.trim="draft"
                 class="chd-input"
-                :placeholder="t('Write a message')"
+                :placeholder="composerPlaceholder"
                 rows="2"
                 @keydown="onComposerKeydown"
                 @keydown.enter.prevent.exact="send"
@@ -183,7 +214,7 @@
                 <button
                   class="chd-btn chd-btn--primary"
                   @click="send"
-                  :disabled="!draft || sending || userStatus !== 1"
+                  :disabled="sendDisabled"
                 >
                   <i class="mdi mdi-send" /> {{ t("Send") }}
                 </button>
@@ -199,8 +230,150 @@
 <script setup>
 import { ref, reactive, computed, onBeforeUnmount, watch, onMounted } from "vue"
 import { useI18n } from "vue-i18n"
+import { useCidReq } from "../../composables/cidReq"
 
 const { t } = useI18n({ useScope: "global" })
+
+/**
+ * cidreq context (course/session/group).
+ * DockedChat may be mounted in pages without vue-router.
+ * In those cases, useCidReq() can throw and would prevent the whole dock from rendering.
+ * We bind it defensively and fallback to reading window.location.
+ */
+const cid = ref(0)
+const sid = ref(0)
+const gid = ref(0)
+
+function toInt(v) {
+  const n = Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+function extractCourseIdFromPath(pathname) {
+  const p = String(pathname || "")
+
+  // Examples:
+  // /course/1/home
+  // /course/1/...
+  // /courses/1/...
+  let m = p.match(/\/course\/(\d+)(?:\/|$)/i)
+  if (m) return toInt(m[1]) || 0
+
+  m = p.match(/\/courses\/(\d+)(?:\/|$)/i)
+  if (m) return toInt(m[1]) || 0
+
+  return 0
+}
+
+function readCidReqFromLocation() {
+  // URL parsing (supports cid/sid/gid and cidReq when numeric).
+  const sp = new URLSearchParams(window.location.search || "")
+  const cidFromQuery = toInt(sp.get("cid")) || toInt(sp.get("cidReq")) || toInt(sp.get("cidreq")) || 0
+  const cidFromPath = extractCourseIdFromPath(window.location.pathname)
+
+  cid.value = cidFromQuery || cidFromPath || 0
+  sid.value = toInt(sp.get("sid") ?? "0") || 0
+  gid.value = toInt(sp.get("gid") ?? "0") || 0
+}
+
+function bindMaybeRef(target, source) {
+  if (source && typeof source === "object" && "value" in source) {
+    target.value = toInt(source.value) || 0
+    watch(
+      source,
+      (v) => {
+        target.value = toInt(v) || 0
+      },
+      { immediate: false },
+    )
+    return
+  }
+  target.value = toInt(source) || 0
+}
+
+function safeBindCidReq() {
+  let bound = false
+
+  try {
+    const r = useCidReq()
+    bindMaybeRef(cid, r?.cid)
+    bindMaybeRef(sid, r?.sid)
+    bindMaybeRef(gid, r?.gid)
+    bound = true
+  } catch (e) {
+    // No router / injection context: fallback to URL parsing.
+  }
+
+  // Even if useCidReq() exists, it might return 0 on URLs like /course/1/home (no cidReq in query).
+  // Fallback to location parsing when cid is still missing.
+  if (!bound || toInt(cid.value) <= 0) {
+    readCidReqFromLocation()
+  }
+}
+
+safeBindCidReq()
+
+function installUrlChangeHooks() {
+  const notify = () => readCidReqFromLocation()
+
+  window.addEventListener("popstate", notify)
+  window.addEventListener("hashchange", notify)
+
+  const wrap =
+    (fn) =>
+    (...args) => {
+      const ret = fn.apply(history, args)
+      queueMicrotask(notify)
+      return ret
+    }
+
+  history.pushState = wrap(history.pushState)
+  history.replaceState = wrap(history.replaceState)
+}
+
+installUrlChangeHooks()
+
+/**
+ * Runtime cid detection (authoritative at request time).
+ * This ensures that if we are in /course/{id}/... pages, we still propagate cid even without cidReq in the query.
+ */
+function getRuntimeCidReq() {
+  const sp = new URLSearchParams(window.location.search || "")
+
+  let c = toInt(sp.get("cid")) || toInt(sp.get("cidReq")) || toInt(sp.get("cidreq")) || 0
+
+  let s = toInt(sp.get("sid") ?? "0") || 0
+  let g = toInt(sp.get("gid") ?? "0") || 0
+
+  if (c <= 0) {
+    c = extractCourseIdFromPath(window.location.pathname)
+  }
+
+  return { cid: c || 0, sid: s, gid: g }
+}
+
+function runtimeCidReqParams() {
+  const { cid: c, sid: s, gid: g } = getRuntimeCidReq()
+  if (c <= 0) return {}
+
+  // Send all 3 keys for maximum compatibility with legacy Chamilo code.
+  return {
+    cid: c,
+    cidReq: c,
+    cidreq: c,
+    sid: s || 0,
+    gid: g || 0,
+  }
+}
+
+// Keep cid in sync on browser navigation.
+let popstateHandler = null
+popstateHandler = () => readCidReqFromLocation()
+window.addEventListener("popstate", popstateHandler)
+
+/** AI peer id used across backend/services */
+const AI_PEER_ID = -1
+
 const openedOnce = ref(false)
 const AUTO_OPEN_LAST_PEER = false
 const queuedBadgePids = new Set()
@@ -208,22 +381,94 @@ const queuedBadgePids = new Set()
 /** Active peer must exist before we watch it (avoid ReferenceError). */
 const activePeer = ref(null) // { id, name, online, image }
 
+/** Avatar helper (template uses it). */
+const activePeerAvatar = computed(() => {
+  const img = activePeer.value?.image || ""
+  return typeof img === "string" ? img : ""
+})
+
 /** Persist last opened peer locally (nice UX). */
 const LAST_PEER_KEY = "chd:lastPeerId"
 watch(activePeer, (v) => {
   if (v?.id) localStorage.setItem(LAST_PEER_KEY, String(v.id))
 })
 
+/**
+ * Gate: render dock only when enabled and not in pages where it must be hidden.
+ * NOTE: Global chat should be visible outside courses too. Course context only affects tutor + cidReq propagation.
+ */
+function isAssignmentsPage() {
+  const p = String(window.location.pathname || "")
+  const q = String(window.location.search || "")
+  return (
+    p.includes("/work/") ||
+    p.includes("/student_publication/") ||
+    p.endsWith("/work.php") ||
+    q.includes("work.php") ||
+    q.includes("student_publication")
+  )
+}
+
+function isExercisePage() {
+  const p = String(window.location.pathname || "")
+  const q = String(window.location.search || "")
+  return (
+    p.includes("/exercise/") ||
+    p.endsWith("/exercise.php") ||
+    q.includes("exercise.php") ||
+    (q.includes("cidReq") && (q.includes("exercise") || q.includes("lp_id")))
+  )
+}
+
+const cidNum = computed(() => toInt(cid.value || 0))
+const sidNum = computed(() => toInt(sid.value || 0))
+const gidNum = computed(() => toInt(gid.value || 0))
+
+const inCourse = computed(() => {
+  // Use runtime to avoid stale refs when cid is only in the path.
+  return getRuntimeCidReq().cid > 0
+})
+
+/**
+ * Optional runtime flag set by backend. If missing, default to enabled.
+ * Supported sources:
+ * - window.CHAMILO_CHAT_DOCK_ENABLED
+ * - window.CHAT_DOCK_ENABLED
+ * - <body data-chat-dock-enabled="1|true|0|false">
+ */
+const dockEnabled = computed(() => {
+  const bodyVal = document?.body?.dataset?.chatDockEnabled
+  const v = window?.CHAMILO_CHAT_DOCK_ENABLED ?? window?.CHAT_DOCK_ENABLED ?? window?.CHAT_DOCKED_ENABLED ?? bodyVal
+
+  if (v === undefined || v === null || v === "") {
+    // If the component is mounted, assume it's enabled unless explicitly disabled.
+    return true
+  }
+
+  if (typeof v === "string") return /^(1|true|on|yes)$/i.test(v)
+  return !!v
+})
+
+const canRenderDock = computed(() => {
+  if (!dockEnabled.value) return false
+  if (isAssignmentsPage()) return false
+  if (isExercisePage()) return false
+  return true
+})
+
 /** ===== Endpoints ===== */
 function RG(candidates, fallback) {
   for (const name of candidates) {
     try {
       const u = window.Routing?.generate(name)
       if (u) return u
-    } catch {}
+    } catch {
+      // ignore
+    }
   }
   return fallback
 }
+
 const API = {
   start: RG(["chat_api_start", "chamilo_core_chat_api_start"], "/account/chat/api/start"),
   contacts: RG(["chat_api_contacts", "chamilo_core_chat_api_contacts"], "/account/chat/api/contacts"),
@@ -238,6 +483,12 @@ const API = {
   preview: RG(["chat_api_preview", "chamilo_core_chat_api_preview"], "/account/chat/api/preview"),
   presence: RG(["chat_api_presence", "chamilo_core_chat_api_presence"], "/account/chat/api/presence"),
   ack: RG(["chat_api_ack", "chamilo_core_chat_api_ack"], "/account/chat/api/ack"),
+
+  // New: tutor context endpoint (course-aware, test-aware)
+  tutor_context: RG(
+    ["chat_api_tutor_context", "chamilo_core_chat_api_tutor_context"],
+    "/account/chat/api/tutor_context",
+  ),
 }
 
 /** ===== State ===== */
@@ -257,6 +508,14 @@ const clearing = ref(false)
 
 const scrollBox = ref(null)
 
+/** Tutor context (backend-authoritative) */
+const tutorCtx = reactive({
+  loaded: false,
+  enabled: false,
+  inTest: false,
+  course: null, // { id, title, language }
+})
+
 /** Unread tracking (client-side only) */
 const unreadByPeer = reactive(new Map()) // peerId -> count
 const clearedAtByPeer = reactive(new Map()) // peerId -> epoch seconds
@@ -264,21 +523,75 @@ const lastSeenMsgIdByPeer = reactive(new Map()) // peerId -> last msg id seen
 
 /** FAB global unread from /heartbeat?mode=min */
 const fabUnread = ref(0)
-const fabHasUnread = computed(() => unreadTotal.value > 0 || fabUnread.value > 0)
 const unreadTotal = computed(() => {
-  let t = 0
-  unreadByPeer.forEach((v) => (t += Number(v || 0)))
-  return t
+  let s = 0
+  unreadByPeer.forEach((v) => (s += Number(v || 0)))
+  return s
 })
+const fabHasUnread = computed(() => unreadTotal.value > 0 || fabUnread.value > 0)
 
 let hbTimer = null
-let hbLegacyLoop = false
 let contactsTimer = null
 
 /** ===== Utils ===== */
 function qs(obj) {
   return new URLSearchParams(obj).toString()
 }
+
+function cidReqParams() {
+  return runtimeCidReqParams()
+}
+
+/**
+ * More robust AI Tutor detection to prevent duplicate entry:
+ * - Detect explicit -1 in legacy onclick or data attrs
+ * - Fallback to "AI Tutor" label + -1 hints (value=-1, uid=-1, etc.)
+ */
+const contactsHasAiTutor = computed(() => {
+  const html = String(contactsHtml.value || "")
+  if (!html) return false
+
+  // Strong signals
+  if (
+    /chatWith\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
+    /openChat\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
+    /startChat\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
+    /data-(?:user|id|uid|peer|contact-id)\s*=\s*["']-1["']/i.test(html) ||
+    /\b(peer_id|user_id|uid)\s*=\s*-1\b/i.test(html) ||
+    /\bvalue\s*=\s*["']-1["']\b/i.test(html)
+  ) {
+    // If -1 appears anywhere, it's very likely the AI Tutor contact exists in legacy list.
+    return true
+  }
+
+  // Fallback: label + -1 close to it
+  if (/(AI\s*Tutor)/i.test(html) && /["'\s]-1["'\s]/.test(html)) return true
+
+  return false
+})
+
+function mergeParams(a, b) {
+  return { ...(a || {}), ...(b || {}) }
+}
+
+function withCidReq(params) {
+  // Always attach cidReq when context exists (even outside classic cidReq pages).
+  const extra = cidReqParams()
+  if (!Object.keys(extra).length) return params || {}
+  return mergeParams(params, extra)
+}
+
+function addCidReqToUrl(url) {
+  try {
+    const u = new URL(url, window.location.origin)
+    const p = cidReqParams()
+    Object.entries(p).forEach(([k, v]) => u.searchParams.set(k, String(v)))
+    return u.toString()
+  } catch {
+    return url
+  }
+}
+
 function linkify(str) {
   return (str || "").replace(/(https?:\/\/[^\s<]+)/g, '<a href="$1" target="_blank" rel="noopener">$1</a>')
 }
@@ -328,19 +641,21 @@ function ackTitle(msg) {
 
 /** API helpers */
 async function getJSON(url, params) {
-  const full = params ? `${url}?${qs(params)}` : url
+  const full = params ? `${url}?${qs(withCidReq(params))}` : addCidReqToUrl(url)
   const r = await fetch(full, { credentials: "same-origin" })
-  if (!r.ok) throw new Error("net")
+  if (!r.ok) throw new Error("Network error")
   return r.json()
 }
+
 async function post(url, params, expectJson = true) {
-  const r = await fetch(url, {
+  const fullUrl = addCidReqToUrl(url)
+  const r = await fetch(fullUrl, {
     method: "POST",
     credentials: "same-origin",
     headers: { "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8" },
-    body: new URLSearchParams(params || {}),
+    body: new URLSearchParams(withCidReq(params || {})),
   })
-  if (!r.ok) throw new Error("net")
+  if (!r.ok) throw new Error("Network error")
   return expectJson ? r.json() : r.text()
 }
 
@@ -384,7 +699,6 @@ function textToPlain(s) {
   el.innerHTML = String(s ?? "")
   return (el.textContent || "").trim()
 }
-
 function sameContent(a, b) {
   const textA = textToPlain(a?.message ?? a?.m ?? "")
   const textB = textToPlain(b?.message ?? b?.m ?? "")
@@ -438,19 +752,31 @@ function isAtBottom(el, tolerance = 24) {
   if (!el) return false
   return el.scrollHeight - el.scrollTop - el.clientHeight <= tolerance
 }
+
 async function markActiveAsRead() {
   if (!activePeer.value) return
-  const pid = activePeer.value.id
+
+  const pid = Number(activePeer.value.id || 0)
   const arr = messagesByPeer.get(pid) || []
   if (!arr.length) return
-  const last = arr[arr.length - 1].id
+
+  const last = Number(arr[arr.length - 1]?.id || 0)
   const lastSeenPrev = Number(lastSeenMsgIdByPeer.get(pid) || 0)
-  if (last <= lastSeenPrev) return
+
+  if (last <= 0 || last <= lastSeenPrev) return
+
+  // Update local state (best effort).
   lastSeenMsgIdByPeer.set(pid, last)
   resetUnread(pid)
+
+  // AI tutor (-1) (and any non-positive peer) is not part of classic chat ack.
+  if (pid <= 0) return
+
   try {
     await post(API.ack, { peer_id: pid, last_seen_id: last })
-  } catch {}
+  } catch {
+    // Best effort: ignore ack failures.
+  }
 }
 
 function extractPeerIdFromNode(node) {
@@ -472,7 +798,9 @@ function extractPeerIdFromNode(node) {
           0,
       )
       if (p) return p
-    } catch {}
+    } catch {
+      // ignore
+    }
   }
 
   const oc = node.getAttribute?.("onclick") || ""
@@ -487,6 +815,7 @@ function extractPeerIdFromNode(node) {
     const m2 = idAttr.match(/(?:friend|user|contact|person|peer)[_-]?(\d+)/i)
     if (m2) return Number(m2[1])
   }
+
   return 0
 }
 
@@ -520,6 +849,7 @@ function setRowUnreadDot(row, hasUnread) {
     if (dot) dot.remove()
   }
 }
+
 function updateContactUnreadBadge(pid) {
   const root = document.querySelector(".chd .chd-contacts .chd-contacts-html")
   if (!root) {
@@ -560,20 +890,26 @@ function resolveOnlineFromInfo(ui) {
   }
   return false
 }
+
 function collectVisibleContactIds() {
   const root = document.querySelector(".chd .chd-contacts .chd-contacts-html")
-  if (!root) return []
   const ids = new Set()
-  root.querySelectorAll("[data-user],[data-id],[data-user-id],[data-id-user],a[href],[onclick],[id]").forEach((el) => {
-    const id = extractPeerIdFromNode(el)
-    if (id) ids.add(id)
-  })
+
+  // Include AI Tutor when enabled so presence map always has it.
+  if (tutorCtx.enabled) ids.add(AI_PEER_ID)
+
+  if (root) {
+    root
+      .querySelectorAll("[data-user],[data-id],[data-user-id],[data-id-user],a[href],[onclick],[id]")
+      .forEach((el) => {
+        const id = extractPeerIdFromNode(el)
+        if (id) ids.add(id)
+      })
+  }
+
   if (activePeer.value?.id) ids.add(activePeer.value.id)
   return Array.from(ids)
 }
-async function refreshPresence() {
-  // Presence is now piggy-backed on heartbeat responses (see heartbeatMinTick).
-}
 
 /** Paint presence icons on contact list */
 function paintPresenceOnContacts(map) {
@@ -583,7 +919,6 @@ function paintPresenceOnContacts(map) {
     const pid = Number(sid)
     const rows = findContactNodesByPeerId(root, pid)
     rows.forEach((row) => {
-      row.querySelectorAll(":scope > .chd-presence-dot").forEach((n) => n.remove())
       const icon =
         row.querySelector("i.mdi-account-check") ||
         row.querySelector("i.mdi-account-outline") ||
@@ -598,6 +933,29 @@ function paintPresenceOnContacts(map) {
   })
 }
 
+async function loadTutorContext() {
+  tutorCtx.loaded = false
+  tutorCtx.enabled = false
+  tutorCtx.inTest = false
+  tutorCtx.course = null
+
+  try {
+    // Backend decides if it's "course" or "global".
+    const r = await getJSON(API.tutor_context)
+
+    tutorCtx.enabled = !!r?.enabled
+    tutorCtx.inTest = !!r?.in_test
+    tutorCtx.course = r?.course || null
+  } catch {
+    // Best effort: keep it disabled if request fails.
+    tutorCtx.enabled = false
+    tutorCtx.inTest = false
+    tutorCtx.course = null
+  } finally {
+    tutorCtx.loaded = true
+  }
+}
+
 /** Flows */
 async function startSession() {
   const data = await getJSON(API.start)
@@ -605,7 +963,7 @@ async function startSession() {
   me.name = data.me || ""
   me.id = Number(data.user_id || 0)
   userStatus.value = Number(data.user_status || 0)
-  me.secToken = data.sec_token || ""
+  me.secToken = data.sec_token || data.chat_sec_token || ""
 
   if (data.items) {
     Object.entries(data.items).forEach(([peerId, userItems]) => {
@@ -627,12 +985,12 @@ async function loadContacts() {
     contactsHtml.value = String(html || "")
     requestAnimationFrame(() => {
       repaintAllContactBadges()
-      refreshPresence()
     })
   } finally {
     loadingContacts.value = false
   }
 }
+
 /** Contacts click handler */
 function onContactsClick(e) {
   const a = e.target.closest("a[href]")
@@ -671,7 +1029,9 @@ function onContactsClick(e) {
         const name = a.getAttribute("data-name") || a.textContent?.trim() || "User"
         return openConversation({ id, name })
       }
-    } catch {}
+    } catch {
+      // ignore
+    }
   }
 
   el = e.target.closest("[id]")
@@ -684,6 +1044,7 @@ function onContactsClick(e) {
     }
   }
 }
+
 function pickOnline() {
   return undefined
 }
@@ -693,19 +1054,19 @@ async function openConversation(peer) {
     id: Number(peer.id),
     name: peer.name || "User",
     image: peer.image || "",
-    online: pickOnline(peer.id) ?? false,
+    online: Number(peer.id) === AI_PEER_ID ? true : (pickOnline(peer.id) ?? false),
   }
 
   if (!messagesByPeer.get(activePeer.value.id)) {
     await getPreviousMessages()
   }
+
   requestAnimationFrame(() => {
     const el = scrollBox.value
     if (el) el.scrollTop = el.scrollHeight
     maybeMarkAsReadOnView()
   })
 
-  // Kick fast phase when opening a conversation: reset backoff
   lastIdByPeer.set(activePeer.value.id, lastKnownIdForPeer(activePeer.value.id))
   maybeResetScheduler()
 }
@@ -720,11 +1081,8 @@ function isActuallyViewingActivePeer() {
   const el = scrollBox.value
   return open.value && document.hasFocus() && !!activePeer.value && !!el && el.clientHeight > 0 && isAtBottom(el, 24)
 }
-
 function maybeMarkAsReadOnView() {
-  if (isActuallyViewingActivePeer()) {
-    debounceMarkAsRead()
-  }
+  if (isActuallyViewingActivePeer()) debounceMarkAsRead()
 }
 
 function onScrollUpLoadMore(e) {
@@ -736,6 +1094,7 @@ function onBodyScrollForRead() {
   if (!activePeer.value) return
   maybeMarkAsReadOnView()
 }
+
 async function getPreviousMessages() {
   if (!activePeer.value) return
   const pid = activePeer.value.id
@@ -758,84 +1117,6 @@ async function getPreviousMessages() {
   }
 }
 
-let lastPresenceAt = 0
-// Heartbeat that does not rely on server-provided unread_by_peer.
-// It merges new items, handles acks, updates presence throttled,
-// and finally recomputes unread counts locally for FAB + contact dots.
-async function heartbeat() {
-  try {
-    const data = await getJSON(API.heartbeat)
-
-    if (data?.items) {
-      for (const [peerId, userItems] of Object.entries(data.items)) {
-        const pid = Number(peerId)
-        const prev = messagesByPeer.get(pid) || []
-        const pruned = filterAfterClear(pid, normalizeItems(userItems?.items ?? []))
-
-        // Adopt optimistic bubbles that the server just acknowledged
-        const adopted = adoptPendingFromServer(pid, pruned, prev)
-
-        // Dedupe vs existing and pending
-        let newOnes = pruned.filter((x) => !prev.find((p) => p.id === x.id && !adopted.has(Number(x.id))))
-        newOnes = dedupeNewWithPending(pid, newOnes)
-
-        if (newOnes.length) {
-          const merged = [...prev, ...newOnes].sort(byChronoId)
-          messagesByPeer.set(pid, merged)
-
-          // Handle incoming messages (not mine)
-          const incoming = newOnes.filter((m) => !isMine(m))
-          if (incoming.length) {
-            const isActivePeer = activePeer.value?.id === pid
-            const viewing = false
-            if (!isActivePeer) {
-              // Let the UI react immediately (blink/title), exact counts will be reconciled below
-              incUnread(pid, incoming.length)
-            } else {
-              // If the user is seeing the bottom of the active conversation, mark as read and ack
-              const lastId = merged[merged.length - 1].id
-              lastSeenMsgIdByPeer.set(pid, lastId)
-              resetUnread(pid)
-              try {
-                await post(API.ack, { peer_id: pid, last_seen_id: lastId })
-              } catch {
-                /* best effort */
-              }
-            }
-          }
-
-          maybeMarkAsReadOnView()
-          // Auto-scroll if this peer is the active one
-          if (activePeer.value?.id === pid) {
-            requestAnimationFrame(() => {
-              const el = scrollBox.value
-              if (el) el.scrollTop = el.scrollHeight
-            })
-          }
-        }
-
-        // Optional presence hint from server
-        if (userItems.window_user_info && activePeer.value?.id === pid) {
-          activePeer.value.online = resolveOnlineFromInfo(userItems.window_user_info)
-        }
-      }
-    }
-
-    // Throttled presence refresh
-    const now = Date.now()
-    if (now - lastPresenceAt > 5000) {
-      lastPresenceAt = now
-      refreshPresence()
-    }
-
-    recomputeUnreadFromLocal()
-  } finally {
-    if (hbLegacyLoop && !hbTimer) {
-      hbTimer = setTimeout(heartbeat, 30000)
-    }
-  }
-}
-
 /** per-peer last id cache and incremental fetch */
 const lastIdByPeer = reactive(new Map())
 function lastKnownIdForPeer(pid) {
@@ -846,19 +1127,24 @@ function lastKnownIdForPeer(pid) {
   }
   return Number(lastIdByPeer.get(pid) || 0) || 0
 }
+
 async function fetchNewForActivePeer(pid) {
   const since = lastKnownIdForPeer(pid)
   const items = await getJSON(API.history_since, { user_id: pid, since_id: since })
   const list = normalizeItems(items)
   if (!list.length) return
+
   const prev = messagesByPeer.get(pid) || []
   const adopted = adoptPendingFromServer(pid, list, prev)
+
   let newOnes = list.filter((x) => !prev.find((p) => p.id === x.id && !adopted.has(Number(x.id))))
   newOnes = dedupeNewWithPending(pid, newOnes)
   if (!newOnes.length) return
+
   const merged = [...prev, ...newOnes].sort(byChronoId)
   messagesByPeer.set(pid, merged)
   lastIdByPeer.set(pid, Number(merged[merged.length - 1].id) || since)
+
   const viewing = open.value && activePeer.value?.id === pid && isAtBottom(scrollBox.value) && document.hasFocus()
   if (!viewing) {
     incUnread(pid, newOnes.filter((m) => !isMine(m)).length || 0)
@@ -891,16 +1177,20 @@ function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
     const override = getOverrideDelayMs?.(base)
     return Number.isFinite(override) && override > 0 ? override : base
   }
+
   function scheduleNext() {
     if (aborted) return
     timer = setTimeout(async () => {
       try {
         await onTick?.()
-      } catch {}
+      } catch {
+        // ignore
+      }
       advancePhase()
       scheduleNext()
     }, phaseMs())
   }
+
   function advancePhase() {
     const p = phases[idx]
     ticks++
@@ -915,9 +1205,9 @@ function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
       idx++
       ticks = 0
       started = performance.now()
-      return
     }
   }
+
   function start() {
     aborted = false
     idx = 0
@@ -925,11 +1215,13 @@ function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
     started = performance.now()
     scheduleNext()
   }
+
   function reset() {
     stop()
     onReset?.()
     start()
   }
+
   function stop() {
     aborted = true
     if (timer) {
@@ -937,12 +1229,13 @@ function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
       timer = null
     }
   }
+
   return { start, stop, reset }
 }
 
-/** Minimal heartbeat tick (fast path + safety net) */
+/** Minimal heartbeat tick */
 const lastHeartbeatId = ref(0)
-let noChangeTicks = 0 // counts consecutive min ticks without server-reported changes
+let noChangeTicks = 0
 
 function computeGlobalLastId() {
   let maxId = 0
@@ -951,25 +1244,17 @@ function computeGlobalLastId() {
   })
   return maxId
 }
+
 function shouldPoll() {
   // Only poll when the user is marked as online.
   return userStatus.value === 1
 }
 
-/** Gate resets so we don't restart fast phase when it does not make sense */
 let lastSchedulerResetAt = 0
-
 function maybeResetScheduler() {
-  if (!open.value || !document.hasFocus()) {
-    return
-  }
-
+  if (!open.value || !document.hasFocus()) return
   const now = Date.now()
-  // Avoid resetting the backoff too often
-  if (now - lastSchedulerResetAt < 5000) {
-    return
-  }
-
+  if (now - lastSchedulerResetAt < 5000) return
   lastSchedulerResetAt = now
   scheduler.reset()
 }
@@ -994,13 +1279,7 @@ async function heartbeatMinTick() {
   if (pid) {
     try {
       const since = lastKnownIdForPeer(pid)
-      const params = {
-        mode: "tiny",
-        peer_id: pid,
-        since_id: since,
-        ...presenceParam,
-      }
-
+      const params = { mode: "tiny", peer_id: pid, since_id: since, ...presenceParam }
       const r = await getJSON(API.heartbeat, params)
 
       const latest = Number(r?.last_id || 0)
@@ -1012,38 +1291,26 @@ async function heartbeatMinTick() {
         noChangeTicks++
       }
 
-      // update presence from heartbeat payload
       if (r?.presence) {
         paintPresenceOnContacts(r.presence)
         if (activePeer.value?.id && r.presence[activePeer.value.id] !== undefined) {
           activePeer.value.online = !!r.presence[activePeer.value.id]
         }
       }
-
-      const now = Date.now()
-      if (now - lastPresenceAt > 5000) {
-        lastPresenceAt = now
-      }
-    } catch {}
+    } catch {
+      // ignore
+    }
     return
   }
 
   // No active peer: ultra-light global (for FAB + unread)
   try {
     const since = lastHeartbeatId.value || computeGlobalLastId()
-    const params = {
-      mode: "min",
-      since_id: since,
-      ...presenceParam,
-    }
-
+    const params = { mode: "min", since_id: since, ...presenceParam }
     const r = await getJSON(API.heartbeat, params)
 
     syncUnreadFromServer(r)
-
-    if (r?.presence) {
-      paintPresenceOnContacts(r.presence)
-    }
+    if (r?.presence) paintPresenceOnContacts(r.presence)
 
     const srvLast = Number(r?.last_id ?? 0)
     const hasNew = !!r?.has_new || srvLast > since
@@ -1058,7 +1325,9 @@ async function heartbeatMinTick() {
     } else {
       noChangeTicks++
     }
-  } catch {}
+  } catch {
+    // ignore
+  }
 }
 
 // Shared backoff scheduler for both dock states (open/closed).
@@ -1066,21 +1335,15 @@ const scheduler = createBackoffScheduler({
   onTick: heartbeatMinTick,
   onReset: () => {},
   getOverrideDelayMs: (baseMs) => {
-    // When the dock is closed we still use the same scheduler,
-    // but we clamp to a slower range to avoid aggressive polling.
+    // When the dock is closed, clamp polling to slower intervals.
     if (!open.value) {
-      // Between 10s and 30s when closed.
-      return Math.min(Math.max(baseMs, 10000), 30000)
+      return Math.min(Math.max(baseMs, 10000), 30000) // 10s..30s
     }
-    // When the dock is open we respect the configured phases:
-    // 1s (x5) -> 5s (30s) -> 10s (120s) -> 30s.
     return baseMs
   },
 })
 
-/** Start/stop heartbeat (single scheduler) */
 function startHeartbeat() {
-  // Always restart the backoff sequence when requested.
   scheduler.stop()
   scheduler.start()
 }
@@ -1099,16 +1362,36 @@ async function toggleStatus() {
   const newStatus = userStatus.value === 1 ? 0 : 1
   await post(API.status, { status: newStatus })
   userStatus.value = newStatus
-  if (newStatus === 1) {
-    startHeartbeat()
-  } else {
-    stopHeartbeat()
-  }
+  if (newStatus === 1) startHeartbeat()
+  else stopHeartbeat()
 }
+
+const isAiThread = computed(() => Number(activePeer.value?.id || 0) === AI_PEER_ID)
+
+const composerPlaceholder = computed(() => {
+  if (isAiThread.value && tutorCtx.inTest) return t("AI tutor is disabled during tests")
+  return t("Write a message")
+})
+
+const sendDisabled = computed(() => {
+  if (!draft.value) return true
+  if (sending.value) return true
+  if (userStatus.value !== 1) return true
+  if (isAiThread.value && tutorCtx.inTest) return true
+  return false
+})
+
 async function send() {
   if (!activePeer.value || !draft.value) return
-  const pid = activePeer.value.id
+
+  const pid = Number(activePeer.value.id)
   const raw = draft.value
+
+  // Prevent sending to AI tutor when tests are running (client-side guard).
+  if (pid === AI_PEER_ID && tutorCtx.inTest) {
+    return
+  }
+
   const msgEscaped = escapeForHtml(raw)
   const nowSec = Math.floor(Date.now() / 1000)
 
@@ -1124,9 +1407,11 @@ async function send() {
     recd: 0,
     pending: true,
   }
+
   const arr = messagesByPeer.get(pid) || []
   messagesByPeer.set(pid, [...arr, optimistic])
   addPending(pid, tempId, raw, nowSec)
+
   requestAnimationFrame(() => {
     const el = scrollBox.value
     if (el) el.scrollTop = el.scrollHeight
@@ -1137,11 +1422,21 @@ async function send() {
 
   try {
     const res = await post(API.send, { to: pid, message: raw, chat_sec_token: me.secToken })
+    if (res?.assistant?.id) {
+      const arr2 = messagesByPeer.get(pid) || []
+      // Avoid duplicate if it already exists
+      if (!arr2.find((m) => Number(m.id) === Number(res.assistant.id))) {
+        messagesByPeer.set(pid, [...arr2, res.assistant].sort(byChronoId))
+      }
+      requestAnimationFrame(() => {
+        const el = scrollBox.value
+        if (el) el.scrollTop = el.scrollHeight
+      })
+    }
     if (res && typeof res === "object" && Number(res.id) > 0) {
       if (res.sec_token) me.secToken = res.sec_token
       replaceTempId(pid, tempId, { id: Number(res.id), recd: 0, date: nowSec })
       removePending(pid, tempId)
-      //maybeResetScheduler()
       return
     }
   } catch {
@@ -1150,11 +1445,12 @@ async function send() {
     sending.value = false
   }
 }
+
 function onComposerKeydown() {
-  //maybeResetScheduler()
+  // Intentionally left blank.
 }
 function newline() {
-  /* Shift+Enter */
+  // Shift+Enter: let browser insert newline naturally.
 }
 
 async function clearConversation() {
@@ -1182,10 +1478,11 @@ const activeMessages = computed(() => {
   return messagesByPeer.get(activePeer.value.id) || []
 })
 
-/** Title blink for unread  */
+/** Title blink for unread */
 const originalTitle = document.title
 let blinkTimer = null
 let blinkState = false
+
 function applyBlinkFrame() {
   const total = unreadTotal.value
   if (!total || !document.hidden) {
@@ -1212,26 +1509,20 @@ function stopBlinkNow() {
   document.title = originalTitle
   blinkState = false
 }
+
 document.addEventListener("visibilitychange", () => {
-  if (document.hidden) {
-    maybeStartBlink()
-  } else {
+  if (document.hidden) maybeStartBlink()
+  else {
     maybeStopBlink()
-    //maybeResetScheduler()
     maybeMarkAsReadOnView()
   }
 })
 window.addEventListener("focus", () => {
   maybeStopBlink()
-  //maybeResetScheduler()
   maybeMarkAsReadOnView()
 })
 window.addEventListener("online", () => {
-  // Network came back: if user is online, restart scheduler and backoff.
-  if (userStatus.value === 1) {
-    startHeartbeat()
-    //maybeResetScheduler()
-  }
+  if (userStatus.value === 1) startHeartbeat()
 })
 window.addEventListener("offline", () => scheduler.stop())
 
@@ -1239,41 +1530,21 @@ window.addEventListener("offline", () => scheduler.stop())
 function registerLegacyChatGlobals() {
   const handler = (id, name) => {
     try {
-      // Only open the dock if it's closed; do not re-trigger init paths
       if (!open.value) toggleDock(true)
       openConversation({ id: Number(id), name: name || "User" })
-    } catch (e) {}
+    } catch {
+      // ignore
+    }
     return false
   }
   if (!("chatWith" in window)) window.chatWith = handler
   if (!("openChat" in window)) window.openChat = handler
   if (!("startChat" in window)) window.startChat = handler
 }
-async function passiveTick() {
-  try {
-    const since = lastHeartbeatId.value || computeGlobalLastId()
-    const r = await getJSON(API.heartbeat, { mode: "min", since_id: since })
-
-    syncUnreadFromServer(r)
-    if (typeof r?.unread === "number") fabUnread.value = r.unread
-
-    const srvLast = Number(r?.last_id ?? 0)
-    const hasNew = !!r?.has_new || srvLast > since
-    if (hasNew) {
-      lastHeartbeatId.value = Math.max(srvLast || 0, since)
-      await heartbeat()
-
-      if (!r?.unread_by_peer) {
-        recomputeUnreadFromLocal()
-      }
-    }
-  } catch {}
-}
 
-// Recompute per-peer unread counts from local state and repaint badges + FAB.
+/** Local unread reconciliation */
 function recomputeUnreadFromLocal() {
   let total = 0
-  // Consider peers that have messages or a lastSeen stored
   const pids = new Set([...Array.from(messagesByPeer.keys()), ...Array.from(lastSeenMsgIdByPeer.keys())])
 
   pids.forEach((pid0) => {
@@ -1285,57 +1556,51 @@ function recomputeUnreadFromLocal() {
     let c = 0
     for (const m of arr) {
       const mid = Number(m?.id) || 0
-      if (mid <= 0) continue // ignore temp (optimistic) bubbles
+      if (mid <= 0) continue // ignore optimistic bubbles
       if (cut && Number(m?.date) <= cut) continue
       if (isMine(m)) continue
       if (mid > lastSeen) c++
     }
+
     unreadByPeer.set(pid, c)
     total += c
   })
 
   fabUnread.value = total
-  // Paint red dots on the contact list when available
   requestAnimationFrame(() => repaintAllContactBadges())
 }
 
-function stopPassiveHeartbeat() {
-  if (hbTimer) {
-    clearInterval(hbTimer)
-    hbTimer = null
-  }
-}
-
 /** Lifecycle */
 async function toggleDock(v) {
   if (v === open.value) return
 
+  // Defensive: do not open when gate says we should not render here.
+  if (v && !canRenderDock.value) return
+
   const wasOpen = open.value
   open.value = v
 
   if (v) {
-    // OPEN: use the same scheduler, but reset the backoff so we go through
-    // 1s→5s→10s→30s again when the user explicitly opens the dock.
+    // Ensure tutor context is loaded as soon as the dock opens.
+    await loadTutorContext()
+
+    // OPEN: reset backoff phases when user explicitly opens.
     if (!openedOnce.value) {
       await startSession()
 
       if (userStatus.value !== 1) {
         try {
           await goOnline()
-        } catch {}
+        } catch {
+          // ignore
+        }
         userStatus.value = 1
       }
 
       // First open: ask heartbeat for contacts + presence in one go
       const presenceIds = collectVisibleContactIds()
-      const params = {
-        mode: "min",
-        since_id: lastHeartbeatId.value || 0,
-        include_contacts: 1,
-      }
-      if (presenceIds.length > 0) {
-        params.presence_ids = JSON.stringify(presenceIds)
-      }
+      const params = { mode: "min", since_id: lastHeartbeatId.value || 0, include_contacts: 1 }
+      if (presenceIds.length > 0) params.presence_ids = JSON.stringify(presenceIds)
 
       const r = await getJSON(API.heartbeat, params)
 
@@ -1343,14 +1608,9 @@ async function toggleDock(v) {
         contactsHtml.value = r.contacts_html
         requestAnimationFrame(() => repaintAllContactBadges())
       }
+      if (r?.presence) paintPresenceOnContacts(r.presence)
 
-      if (r?.presence) {
-        paintPresenceOnContacts(r.presence)
-      }
-
-      // Sync unread from server if available
       syncUnreadFromServer(r)
-
       openedOnce.value = true
     } else {
       await loadContacts()
@@ -1361,11 +1621,12 @@ async function toggleDock(v) {
     clearInterval(contactsTimer)
     contactsTimer = setInterval(loadContacts, 15000)
 
-    // Restart backoff phases when the dock is opened.
     startHeartbeat()
     try {
       await heartbeatMinTick()
-    } catch {}
+    } catch {
+      // ignore
+    }
 
     if (!wasOpen) {
       if (AUTO_OPEN_LAST_PEER) {
@@ -1382,8 +1643,7 @@ async function toggleDock(v) {
     activePeer.value = null
     clearInterval(contactsTimer)
     contactsTimer = null
-    // Do not stop scheduler here: keep the same backoff-driven heartbeat
-    // running in "closed" mode (slower intervals via getOverrideDelayMs).
+    // Keep scheduler running in "closed" mode (slower intervals via override).
     recomputeUnreadFromLocal()
   }
 }
@@ -1402,16 +1662,24 @@ function byChronoId(a, b) {
 
 onMounted(async () => {
   registerLegacyChatGlobals()
+
+  // If dock is not allowed here, do not boot any network calls.
+  if (!canRenderDock.value) return
+
+  // Load tutor context early (only effective in courses).
+  await loadTutorContext()
+
+  // Boot minimal session state so unread can be computed even when dock is closed.
   await startSession()
 
   // If user already online at mount time, start scheduler immediately.
-  if (userStatus.value === 1) {
-    startHeartbeat()
-  }
+  if (userStatus.value === 1) startHeartbeat()
 
   try {
     await heartbeatMinTick()
-  } catch {}
+  } catch {
+    // ignore
+  }
 })
 
 onBeforeUnmount(() => {
@@ -1419,11 +1687,20 @@ onBeforeUnmount(() => {
   clearInterval(contactsTimer)
   contactsTimer = null
   stopBlinkNow()
+
+  if (popstateHandler) {
+    window.removeEventListener("popstate", popstateHandler)
+    popstateHandler = null
+  }
 })
+
 watch(open, (v) => {
   if (!v) activePeer.value = null
 })
-function onContactsScroll() {}
+
+function onContactsScroll() {
+  // Intentionally left blank (no pagination yet).
+}
 </script>
 
 <style scoped>
@@ -1472,4 +1749,31 @@ html[dir="rtl"] .chd .chd-contacts .chd-contact-dot {
   align-items: center;
   justify-content: center;
 }
+/* AI contact styles (minimal and non-breaking) */
+.chd-ai {
+  padding: 8px 10px;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.06);
+}
+.chd-ai__btn {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-radius: 10px;
+  border: 1px solid rgba(0, 0, 0, 0.08);
+  background: #fff;
+  cursor: pointer;
+}
+.chd-ai__btn.is-active {
+  border-color: rgba(0, 0, 0, 0.18);
+}
+.chd-ai__btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+.chd-ai__hint {
+  margin: 6px 2px 0;
+  font-size: 12px;
+}
 </style>
diff --git a/public/main/inc/lib/chat.lib.php b/public/main/inc/lib/chat.lib.php
index 5daa65fe945..bf23d2523c5 100644
--- a/public/main/inc/lib/chat.lib.php
+++ b/public/main/inc/lib/chat.lib.php
@@ -7,7 +7,12 @@
 /**
  * Class Chat.
  *
- * @todo ChamiloSession instead of $_SESSION
+ * Notes:
+ * - This is a legacy chat library used by the social network chat.
+ * - Some methods historically echo JSON/text directly. Keep that behavior for backward compatibility.
+ * - Symfony controllers should call methods with $printResult = false to avoid exit().
+ *
+ * @todo Use ChamiloSession instead of $_SESSION everywhere.
  */
 class Chat extends Model
 {
@@ -20,9 +25,10 @@ class Chat extends Model
         'recd',
     ];
     public $window_list = [];
+    public const USER_AI_TUTOR = -1;
 
     /**
-     * The contructor sets the chat table name and the window_list attribute.
+     * The constructor sets the chat table name and the window_list attribute.
      */
     public function __construct()
     {
@@ -46,7 +52,7 @@ public function getUserStatus()
             true
         );
 
-        return $status['user_chat_status'];
+        return (int) ($status['user_chat_status'] ?? 0);
     }
 
     /**
@@ -59,7 +65,7 @@ public function setUserStatus($status)
         UserManager::update_extra_field_value(
             api_get_user_id(),
             'user_chat_status',
-            $status
+            (int) $status
         );
     }
 
@@ -87,7 +93,23 @@ public function getLatestChat($currentUserId, $userId, $latestMessages)
      */
     public function getContacts(): string
     {
-        return (string) SocialManager::listMyFriendsBlock(api_get_user_id(), '', true);
+        $html = (string) SocialManager::listMyFriendsBlock(api_get_user_id(), '', true);
+
+        // Add AI Tutor contact when enabled (global chat).
+        if ('true' === api_get_setting('ai_helpers.tutor_chatbot')) {
+            // Hide AI when user is in an exam (best effort).
+            if (empty($_SESSION['is_in_a_test'])) {
+                $ai = ''
+                    .'<div class="chd-ai-contact" data-user="'.self::USER_AI_TUTOR.'" data-name="AI Tutor" style="cursor:pointer; padding:10px; border-bottom:1px solid #eee;">'
+                    .'<span style="margin-right:8px;">🤖</span>'
+                    .'<strong>AI Tutor</strong>'
+                    .'<span style="float:right; color:#2e7d32;">●</span>'
+                    .'</div>';
+                $html = $ai.$html;
+            }
+        }
+
+        return (string) $html;
     }
 
     /**
@@ -113,32 +135,38 @@ public function getAllLatestChats($chatHistory, $latestMessages = 5)
             }
             $items = $this->getMessages($userId, $currentUserId, $start, $latestMessages);
             $chats[$userId]['items'] = $items;
-            $chats[$userId]['window_user_info'] = api_get_user_info($userId);
+            $chats[$userId]['window_user_info'] = $this->getUserInfoSafe((int) $userId);
         }
 
         return $chats;
     }
 
     /**
-     * Starts a chat session and returns JSON array of status and chat history.
-     *
-     * @return bool (prints output in JSON format)
+     * Build the start session payload (no echo/exit).
+     * Symfony controllers should use this method.
      */
-    public function startSession()
+    public function startSessionData(): array
     {
-        // ofaj
-        // $chat = new Chat();
-        // $chat->setUserStatus(1);
-
         $chatList = Session::read('openChatBoxes');
         $chats = $this->getAllLatestChats($chatList);
-        $return = [
+
+        return [
             'user_status' => $this->getUserStatus(),
             'me' => get_lang('Me'),
-            'user_id' => api_get_user_id(),
+            'user_id' => (int) api_get_user_id(),
             'items' => $chats,
         ];
-        echo json_encode($return);
+    }
+
+    /**
+     * Starts a chat session and prints JSON (legacy behavior).
+     *
+     * @return bool (prints output in JSON format)
+     */
+    public function startSession()
+    {
+        // Legacy behavior: echo JSON for old AJAX entry points.
+        echo json_encode($this->startSessionData());
 
         return true;
     }
@@ -157,17 +185,17 @@ public function getCountMessagesExchangeBetweenUsers($fromUserId, $toUserId)
             [
                 'where' => [
                     '(from_user = ? AND to_user = ?) OR (from_user = ? AND to_user = ?) ' => [
-                        $fromUserId,
-                        $toUserId,
-                        $toUserId,
-                        $fromUserId,
+                        (int) $fromUserId,
+                        (int) $toUserId,
+                        (int) $toUserId,
+                        (int) $fromUserId,
                     ],
                 ],
             ],
             'first'
         );
 
-        return (int) $row['count'];
+        return (int) ($row['count'] ?? 0);
     }
 
     /**
@@ -246,45 +274,50 @@ public function getMessages($fromUserId, $toUserId, $start, $end, $orderBy = '')
                 ";
         $result = Database::query($sql);
         $rows = Database::store_result($result);
-        $fromUserInfo = api_get_user_info($fromUserId, true);
-        $toUserInfo = api_get_user_info($toUserId, true);
+
+        $fromUserInfo = $this->getUserInfoSafe((int) $fromUserId);
+        $toUserInfo   = $this->getUserInfoSafe((int) $toUserId);
+
         $users = [
             $fromUserId => $fromUserInfo,
             $toUserId => $toUserInfo,
         ];
+
         $items = [];
         $rows = array_reverse($rows);
+
         foreach ($rows as $chat) {
-            $fromUserId = $chat['from_user'];
-            $userInfo = $users[$fromUserId];
-            $toUserInfo = $users[$toUserId];
+            $rowFrom = (int) $chat['from_user'];
+            $userInfo = $users[$rowFrom] ?? api_get_user_info($rowFrom, true);
+            $toUserInfo = $users[$toUserId] ?? api_get_user_info($toUserId, true);
 
-            $items[$chat['id']] = [
-                'id' => $chat['id'],
+            $items[(int) $chat['id']] = [
+                'id' => (int) $chat['id'],
                 'message' => Security::remove_XSS($chat['message']),
                 'date' => api_strtotime($chat['sent'], 'UTC'),
-                'recd' => $chat['recd'],
+                'recd' => (int) $chat['recd'],
                 'from_user_info' => $userInfo,
                 'to_user_info' => $toUserInfo,
             ];
-            $_SESSION['openChatBoxes'][$fromUserId] = api_strtotime($chat['sent'], 'UTC');
+
+            $_SESSION['openChatBoxes'][$rowFrom] = api_strtotime($chat['sent'], 'UTC');
         }
 
         return $items;
     }
 
     /**
-     * Refreshes the chat windows (usually called every x seconds through AJAX).
+     * Refreshes the chat windows (legacy full payload; echoes JSON).
      */
     public function heartbeat()
     {
         $chatHistory = Session::read('chatHistory');
         $currentUserId = api_get_user_id();
 
-        // update current chats
+        // Update current chats
         if (!empty($chatHistory) && is_array($chatHistory)) {
             foreach ($chatHistory as $fromUserId => &$data) {
-                $userInfo = api_get_user_info($fromUserId, true);
+                $userInfo = $this->getUserInfoSafe((int) $fromUserId);
                 $count = $this->getCountMessagesExchangeBetweenUsers($fromUserId, $currentUserId);
                 $chatItems = $this->getLatestChat($fromUserId, $currentUserId, 5);
                 $data['window_user_info'] = $userInfo;
@@ -301,11 +334,11 @@ public function heartbeat()
 
         $chatList = [];
         while ($chat = Database::fetch_assoc($result)) {
-            $chatList[$chat['from_user']][] = $chat;
+            $chatList[(int) $chat['from_user']][] = $chat;
         }
 
         foreach ($chatList as $fromUserId => $messages) {
-            $userInfo = api_get_user_info($fromUserId, true);
+            $userInfo = $this->getUserInfoSafe((int) $fromUserId);
             $count = $this->getCountMessagesExchangeBetweenUsers($fromUserId, $currentUserId);
             $chatItems = $this->getLatestChat($fromUserId, $currentUserId, 5);
 
@@ -340,7 +373,7 @@ public function heartbeat()
      */
     public function saveWindow($userId)
     {
-        $this->window_list[$userId] = true;
+        $this->window_list[(int) $userId] = true;
         Session::write('window_list', $this->window_list);
     }
 
@@ -350,8 +383,10 @@ public function saveWindow($userId)
      * @param int    $fromUserId  The ID of the user sending the message
      * @param int    $to_user_id  The ID of the user receiving the message
      * @param string $message     Message
-     * @param bool   $printResult Optional. Whether print the result
+     * @param bool   $printResult Optional. Whether print the result (legacy behavior)
      * @param bool   $sanitize    Optional. Whether sanitize the message
+     *
+     * @return int Message id, or 0 on failure
      */
     public function send(
         $fromUserId,
@@ -359,25 +394,27 @@ public function send(
         $message,
         $printResult = true,
         $sanitize = true
-    ) {
+    ): int {
+        $fromUserId = (int) $fromUserId;
+        $to_user_id = (int) $to_user_id;
+
         $relation = SocialManager::get_relation_between_contacts($fromUserId, $to_user_id);
 
         if ($relation === UserRelUser::USER_RELATION_TYPE_FRIEND
-            || $relation === UserRelUser::USER_RELATION_TYPE_GOODFRIEND) {
+            || $relation === UserRelUser::USER_RELATION_TYPE_GOODFRIEND
+        ) {
             $now = api_get_utc_datetime();
             $user_info = api_get_user_info($to_user_id, true);
+
             $this->saveWindow($to_user_id);
             $_SESSION['openChatBoxes'][$to_user_id] = api_strtotime($now, 'UTC');
 
-            if ($sanitize) {
-                $messagesan = $this->sanitize($message);
-            } else {
-                $messagesan = $message;
-            }
+            $messagesan = $sanitize ? $this->sanitize($message) : $message;
 
             if (!isset($_SESSION['chatHistory'][$to_user_id])) {
                 $_SESSION['chatHistory'][$to_user_id] = [];
             }
+
             $item = [
                 's' => '1',
                 'f' => $fromUserId,
@@ -385,6 +422,7 @@ public function send(
                 'date' => api_strtotime($now, 'UTC'),
                 'username' => get_lang('Me'),
             ];
+
             $_SESSION['chatHistory'][$to_user_id]['items'][] = $item;
             $_SESSION['chatHistory'][$to_user_id]['user_info']['user_name'] = $user_info['complete_name'];
             $_SESSION['chatHistory'][$to_user_id]['user_info']['online'] = $user_info['user_is_online'];
@@ -394,18 +432,21 @@ public function send(
             unset($_SESSION['tsChatBoxes'][$to_user_id]);
 
             $params = [];
-            $params['from_user'] = (int) $fromUserId;
-            $params['to_user'] = (int) $to_user_id;
+            $params['from_user'] = $fromUserId;
+            $params['to_user'] = $to_user_id;
             $params['message'] = $messagesan;
             $params['sent'] = api_get_utc_datetime();
-            $params['recd']      = 0;
+            $params['recd'] = 0;
 
             if (!empty($fromUserId) && !empty($to_user_id)) {
-                $messageId = $this->save($params);
+                $messageId = (int) $this->save($params);
+
                 if ($printResult) {
-                    echo $messageId;
+                    echo (string) $messageId;
                     exit;
                 }
+
+                return $messageId;
             }
         }
 
@@ -413,6 +454,8 @@ public function send(
             echo '0';
             exit;
         }
+
+        return 0;
     }
 
     /**
@@ -422,6 +465,7 @@ public function send(
      */
     public function closeWindow($userId)
     {
+        $userId = (int) $userId;
         if (empty($userId)) {
             return false;
         }
@@ -461,7 +505,7 @@ public function close()
      */
     public function sanitize($text)
     {
-        $text = htmlspecialchars($text, ENT_QUOTES);
+        $text = htmlspecialchars((string) $text, ENT_QUOTES);
         $text = str_replace("\n\r", "\n", $text);
         $text = str_replace("\r\n", "\n", $text);
         $text = str_replace("\n", "<br>", $text);
@@ -515,12 +559,22 @@ public function isChatBlockedByExercises()
         return false;
     }
 
+    /**
+     * Mark messages as read up to a specific message id.
+     * recd = 0 => not delivered
+     * recd = 1 => delivered
+     * recd = 2 => read
+     */
     public function ackReadUpTo(int $fromUserId, int $toUserId, int $lastSeenMessageId): int
     {
         if ($fromUserId <= 0 || $toUserId <= 0 || $lastSeenMessageId <= 0) {
             return 0;
         }
 
+        $fromUserId = (int) $fromUserId;
+        $toUserId = (int) $toUserId;
+        $lastSeenMessageId = (int) $lastSeenMessageId;
+
         $sql = "UPDATE {$this->table}
             SET recd = 2
             WHERE from_user = {$fromUserId}
@@ -529,9 +583,49 @@ public function ackReadUpTo(int $fromUserId, int $toUserId, int $lastSeenMessage
               AND recd < 2";
 
         $res = Database::query($sql);
-        return $res ? Database::affected_rows($res) : 0;
+        if (!$res) {
+            return 0;
+        }
+
+        // Database::affected_rows() is used across Chamilo; keep it simple.
+        return (int) Database::affected_rows();
+    }
+
+    /**
+     * Get unread counts grouped by peer (from_user).
+     *
+     * @return array<int,int> map: peerId => unreadCount
+     */
+    public function getUnreadByPeer(int $userId): array
+    {
+        $uid = (int) $userId;
+        if ($uid <= 0) {
+            return [];
+        }
+
+        $tbl = Database::get_main_table(TABLE_MAIN_CHAT);
+
+        // Index-friendly with (to_user, recd, from_user) or (to_user, recd, id)
+        $sql = "SELECT from_user, COUNT(*) AS c
+            FROM {$tbl}
+            WHERE to_user = {$uid}
+              AND recd < 2
+            GROUP BY from_user";
+        $res = Database::query($sql);
+        $rows = Database::store_result($res);
+
+        $map = [];
+        foreach ($rows as $r) {
+            $map[(int) $r['from_user']] = (int) ($r['c'] ?? 0);
+        }
+
+        return $map;
     }
 
+    /**
+     * Minimal heartbeat: returns global last_id (> sinceId) and unread totals.
+     * Used by the docked chat when no peer is actively selected.
+     */
     public function heartbeatMin(int $userId, int $sinceId = 0): array
     {
         $uid = (int) $userId;
@@ -539,32 +633,32 @@ public function heartbeatMin(int $userId, int $sinceId = 0): array
 
         $tbl = Database::get_main_table(TABLE_MAIN_CHAT);
 
-        // Latest id (index-friendly with (to_user, id))
+        // Latest incoming id after sinceId
         $sqlLast = "SELECT MAX(id) AS last_id
-        FROM {$tbl}
-        WHERE to_user = {$uid} AND id > {$sinceId}";
+            FROM {$tbl}
+            WHERE to_user = {$uid} AND id > {$sinceId}";
         $resLast = Database::query($sqlLast);
         $rowLast = Database::fetch_array($resLast) ?: ['last_id' => 0];
         $lastId = (int) ($rowLast['last_id'] ?? 0);
 
-        // Unread count (index-friendly with (to_user, recd, id))
-        $unread = 0;
-        if ($lastId > 0) {
-            $sqlUnread = "SELECT COUNT(*) AS unread
+        // Unread total (independent from sinceId, so badges remain accurate)
+        $sqlUnread = "SELECT COUNT(*) AS unread
             FROM {$tbl}
             WHERE to_user = {$uid}
-              AND recd < 2
-              AND id > {$sinceId}";
-            $resUnread = Database::query($sqlUnread);
-            $rowUnread = Database::fetch_array($resUnread) ?: ['unread' => 0];
-            $unread = (int) ($rowUnread['unread'] ?? 0);
-        }
+              AND recd < 2";
+        $resUnread = Database::query($sqlUnread);
+        $rowUnread = Database::fetch_array($resUnread) ?: ['unread' => 0];
+        $unreadTotal = (int) ($rowUnread['unread'] ?? 0);
+
+        // Unread per peer (for per-contact dots)
+        $unreadByPeer = $this->getUnreadByPeer($uid);
 
         return [
-            'has_new'  => $lastId > $sinceId,
-            'last_id'  => $lastId,
-            'unread'   => $unread,
-            'since_id' => $sinceId,
+            'has_new'        => $lastId > $sinceId,
+            'last_id'        => $lastId,
+            'unread'         => $unreadTotal,
+            'unread_by_peer' => $unreadByPeer,
+            'since_id'       => $sinceId,
         ];
     }
 
@@ -574,9 +668,11 @@ public function heartbeatMin(int $userId, int $sinceId = 0): array
      */
     public function heartbeatTiny(int $userId, int $peerId, int $sinceId = 0): array
     {
-        $uid  = (int) $userId;
-        $pid  = (int) $peerId;
-        $tbl  = Database::get_main_table(TABLE_MAIN_CHAT);
+        $uid = (int) $userId;
+        $pid = (int) $peerId;
+        $sinceId = max(0, (int) $sinceId);
+
+        $tbl = Database::get_main_table(TABLE_MAIN_CHAT);
 
         $sql = "SELECT id
             FROM {$tbl}
@@ -587,11 +683,22 @@ public function heartbeatTiny(int $userId, int $peerId, int $sinceId = 0): array
         $row = Database::fetch_assoc($res) ?: ['id' => 0];
         $last = (int) ($row['id'] ?? 0);
 
+        // Optional: unread from this peer only (cheap)
+        $sqlUnread = "SELECT COUNT(*) AS unread
+            FROM {$tbl}
+            WHERE to_user = {$uid}
+              AND from_user = {$pid}
+              AND recd < 2";
+        $resUnread = Database::query($sqlUnread);
+        $rowUnread = Database::fetch_array($resUnread) ?: ['unread' => 0];
+        $unreadPeer = (int) ($rowUnread['unread'] ?? 0);
+
         return [
-            'has_new'  => $last > max(0, (int) $sinceId),
-            'last_id'  => $last,
-            'peer_id'  => $pid,
-            'since_id' => (int) $sinceId,
+            'has_new'    => $last > $sinceId,
+            'last_id'    => $last,
+            'peer_id'    => $pid,
+            'since_id'   => $sinceId,
+            'unread_peer'=> $unreadPeer,
         ];
     }
 
@@ -606,6 +713,10 @@ public function getIncomingSince(int $peerId, int $meId, int $sinceId = 0): arra
         $uid = (int) $meId;
         $sid = max(0, (int) $sinceId);
 
+        if ($pid <= 0 || $uid <= 0) {
+            return [];
+        }
+
         $sql = "SELECT id, from_user, to_user, message, sent, recd
             FROM {$tbl}
             WHERE from_user = {$pid}
@@ -616,15 +727,22 @@ public function getIncomingSince(int $peerId, int $meId, int $sinceId = 0): arra
         $res = Database::query($sql);
         $rows = Database::store_result($res);
 
-        if (empty($rows)) return [];
+        if (empty($rows)) {
+            return [];
+        }
 
-        $fromUserInfo = api_get_user_info($pid, true);
-        $toUserInfo   = api_get_user_info($uid, true);
+        $fromUserInfo = $this->getUserInfoSafe((int) $pid);
+        $toUserInfo   = $this->getUserInfoSafe((int) $uid);
 
         $items = [];
+        $ids = [];
+
         foreach ($rows as $chat) {
+            $id = (int) $chat['id'];
+            $ids[] = $id;
+
             $items[] = [
-                'id'             => (int) $chat['id'],
+                'id'             => $id,
                 'message'        => Security::remove_XSS($chat['message']),
                 'date'           => api_strtotime($chat['sent'], 'UTC'),
                 'recd'           => (int) $chat['recd'],
@@ -633,13 +751,37 @@ public function getIncomingSince(int $peerId, int $meId, int $sinceId = 0): arra
             ];
         }
 
-        // Mark as delivered
-        $ids = array_column($rows, 'id');
         if (!empty($ids)) {
             $idsCsv = implode(',', array_map('intval', $ids));
-            Database::query("UPDATE {$tbl} SET recd = GREATEST(recd,1) WHERE id IN ({$idsCsv})");
+            Database::query("UPDATE {$tbl} SET recd = GREATEST(recd, 1) WHERE id IN ({$idsCsv})");
         }
 
         return $items;
     }
+
+    private function getAiUserInfo(): array
+    {
+        return [
+            'id' => self::USER_AI_TUTOR,
+            'user_id' => self::USER_AI_TUTOR,
+            'complete_name' => 'AI Tutor',
+            'user_is_online_in_chat' => 1,
+            'user_is_online' => 1,
+            'online' => 1,
+            'avatar_small' => '',
+        ];
+    }
+
+    private function getUserInfoSafe(int $userId): array
+    {
+        if (self::USER_AI_TUTOR === $userId) {
+            return $this->getAiUserInfo();
+        }
+
+        if ($userId <= 0) {
+            return [];
+        }
+
+        return api_get_user_info($userId, true);
+    }
 }
diff --git a/public/main/inc/lib/exercise.lib.php b/public/main/inc/lib/exercise.lib.php
index 76982f135c8..6311d375364 100644
--- a/public/main/inc/lib/exercise.lib.php
+++ b/public/main/inc/lib/exercise.lib.php
@@ -9,6 +9,7 @@
 use Chamilo\CoreBundle\Entity\TrackEExercise;
 use Chamilo\CoreBundle\Enums\ActionIcon;
 use Chamilo\CoreBundle\Framework\Container;
+use Chamilo\CoreBundle\Helpers\AiHelper;
 use Chamilo\CoreBundle\Helpers\ChamiloHelper;
 use Chamilo\CoreBundle\Repository\ResourceNodeRepository;
 use Chamilo\CourseBundle\Entity\CLpItem;
@@ -4456,24 +4457,48 @@ public static function displayGroupMenu($name, $default, $onchange = "")
         return $res;
     }
 
-    /**
-     * @param int $exe_id
-     */
     public static function create_chat_exercise_session($exe_id)
     {
-        if (!isset($_SESSION['current_exercises'])) {
+        $exeId = (int) $exe_id;
+        if ($exeId <= 0) {
+            return;
+        }
+
+        if (!isset($_SESSION['current_exercises']) || !is_array($_SESSION['current_exercises'])) {
             $_SESSION['current_exercises'] = [];
         }
-        $_SESSION['current_exercises'][$exe_id] = true;
+        $_SESSION['current_exercises'][$exeId] = true;
+
+        try {
+            /** @var AiHelper $aiHelper */
+            $aiHelper = Container::$container->get(AiHelper::class);
+            $aiHelper->markUserInTest((int) $exeId);
+        } catch (\Throwable $e) {
+            // Ignore on legacy context (no hard dependency).
+        }
     }
 
-    /**
-     * @param int $exe_id
-     */
     public static function delete_chat_exercise_session($exe_id)
     {
-        if (isset($_SESSION['current_exercises'])) {
-            $_SESSION['current_exercises'][$exe_id] = false;
+        $exeId = (int) $exe_id;
+        if ($exeId <= 0) {
+            return;
+        }
+
+        if (isset($_SESSION['current_exercises']) && is_array($_SESSION['current_exercises'])) {
+            unset($_SESSION['current_exercises'][$exeId]);
+
+            if (empty($_SESSION['current_exercises'])) {
+                unset($_SESSION['current_exercises']);
+            }
+        }
+
+        try {
+            /** @var AiHelper $aiHelper */
+            $aiHelper = Container::$container->get(AiHelper::class);
+            $aiHelper->clearUserInTest((int) $exeId);
+        } catch (\Throwable $e) {
+            // Ignore on legacy context (no hard dependency).
         }
     }
 
diff --git a/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php b/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
new file mode 100644
index 00000000000..d87eb00d2f6
--- /dev/null
+++ b/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\AiProvider;
+
+interface AiChatCompletionClientInterface
+{
+    /**
+     * @param array<int, array{role:string,content:string}> $messages
+     * @param array<string,mixed> $options
+     */
+    public function chat(string $provider, array $messages, array $options = []): string;
+
+    /**
+     * Same as chat() but may also return a provider conversation id (previous_id, conversation_id, etc).
+     *
+     * @param array<int, array{role:string,content:string}> $messages
+     * @param array<string,mixed> $options
+     */
+    public function chatWithMeta(string $provider, array $messages, array $options = []): AiChatCompletionResult;
+}
diff --git a/src/CoreBundle/AiProvider/AiChatCompletionResult.php b/src/CoreBundle/AiProvider/AiChatCompletionResult.php
new file mode 100644
index 00000000000..81bd9f96daa
--- /dev/null
+++ b/src/CoreBundle/AiProvider/AiChatCompletionResult.php
@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\AiProvider;
+
+use Symfony\Component\DependencyInjection\Attribute\Exclude;
+
+#[Exclude]
+final class AiChatCompletionResult
+{
+    public function __construct(
+        public readonly string $text,
+        public readonly ?string $conversationId = null
+    ) {}
+}
diff --git a/src/CoreBundle/AiProvider/AiTutorChatService.php b/src/CoreBundle/AiProvider/AiTutorChatService.php
new file mode 100644
index 00000000000..e2f18c59003
--- /dev/null
+++ b/src/CoreBundle/AiProvider/AiTutorChatService.php
@@ -0,0 +1,456 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\AiProvider;
+
+use Chamilo\CoreBundle\Entity\AiTutorConversation;
+use Chamilo\CoreBundle\Entity\AiTutorMessage;
+use Chamilo\CoreBundle\Entity\Course;
+use Chamilo\CoreBundle\Entity\Session;
+use Chamilo\CoreBundle\Entity\User;
+use Chamilo\CoreBundle\Repository\AiTutorConversationRepository;
+use DateTime;
+use Doctrine\ORM\EntityManagerInterface;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\HttpFoundation\RequestStack;
+use Throwable;
+
+final class AiTutorChatService
+{
+    /**
+     * Special "friend id" used by the course chat UI to represent the AI Tutor.
+     * -  0 => course public chat
+     * >  0 => private chat with a user
+     * -1 => AI Tutor private conversation (per user)
+     */
+    public const FRIEND_AI = -1;
+
+    private const DEFAULT_PROVIDER = 'openai';
+
+    public function __construct(
+        private readonly RequestStack $requestStack,
+        private readonly AiProviderFactory $aiProviderFactory,
+        private readonly EntityManagerInterface $em,
+        private readonly AiTutorConversationRepository $conversationRepo,
+        private readonly AiChatCompletionClientInterface $client,
+        private readonly LoggerInterface $logger
+    ) {
+    }
+
+    public function getOrCreateConversation(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider
+    ): AiTutorConversation {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null !== $conversation) {
+            // Keep session updated when available (optional).
+            if (null !== $session && $conversation->getSession()?->getId() !== $session->getId()) {
+                $conversation->setSession($session);
+                $this->em->flush();
+            }
+
+            return $conversation;
+        }
+
+        /** @var User $userRef */
+        $userRef = $this->em->getReference(User::class, $userId);
+
+        $conversation = (new AiTutorConversation())
+            ->setUser($userRef)
+            ->setCourse($course)
+            ->setSession($session)
+            ->setAiProvider($provider)
+        ;
+
+        $this->em->persist($conversation);
+        $this->em->flush();
+
+        $this->logger->info('[AiTutorChat] Conversation created', [
+            'userId' => $userId,
+            'courseId' => (int) $course->getId(),
+            'provider' => $provider,
+            'sessionId' => $session?->getId(),
+            'conversationId' => $conversation->getId(),
+        ]);
+
+        return $conversation;
+    }
+
+    public function resetConversation(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider
+    ): void {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            // Nothing to reset.
+            return;
+        }
+
+        $deleted = $this->conversationRepo->clearMessages($conversation);
+
+        // Reset timestamps + provider conversation id.
+        $conversation->setLastMessageAt(null);
+        $conversation->setProviderConversationId(null);
+
+        // Keep session updated when available (optional).
+        if (null !== $session && $conversation->getSession()?->getId() !== $session->getId()) {
+            $conversation->setSession($session);
+        }
+
+        $this->em->flush();
+
+        $this->logger->info('[AiTutorChat] Conversation reset', [
+            'userId' => $userId,
+            'courseId' => (int) $course->getId(),
+            'provider' => $provider,
+            'deletedMessages' => $deleted,
+            'conversationId' => $conversation->getId(),
+        ]);
+    }
+
+    public function handleUserMessage(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider,
+        string $message
+    ): bool {
+        try {
+            $this->handleUserMessageAndGetAssistantText($userId, $course, $session, $provider, $message);
+            return true;
+        } catch (Throwable $e) {
+            $this->logger->error('[AiTutorChat] handleUserMessage failed', [
+                'userId' => $userId,
+                'courseId' => (int) $course->getId(),
+                'provider' => $provider,
+                'error' => $e->getMessage(),
+            ]);
+
+            return false;
+        }
+    }
+
+    public function renderHistoryHtml(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider
+    ): string {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            // Do not create a conversation just for polling; show an empty state.
+            return $this->renderEmptyState();
+        }
+
+        // Optional: keep session in sync when browsing the history.
+        if (null !== $session && $conversation->getSession()?->getId() !== $session->getId()) {
+            $conversation->setSession($session);
+            $this->em->flush();
+        }
+
+        $messages = $this->conversationRepo->findMessages($conversation);
+
+        if (empty($messages)) {
+            return $this->renderEmptyState();
+        }
+
+        return $this->renderMessages($messages);
+    }
+
+    public function getLastMessageId(
+        int $userId,
+        Course $course,
+        string $provider
+    ): int {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            return 0;
+        }
+
+        return (int) $this->conversationRepo->getLastMessageId($conversation);
+    }
+
+    public function generateGlobalAssistantReply(
+        int $userId,
+        string $providerKey,
+        string $message,
+        string $uiLang
+    ): string {
+        $systemPrompt = $this->resolveSystemPrompt($uiLang);
+
+        $messages = [
+            ['role' => 'system', 'content' => $systemPrompt],
+            ['role' => 'user', 'content' => $message],
+        ];
+
+        // Use the shared client for consistent behavior (text type + fallbacks).
+        return $this->client->chat($providerKey, $messages, [
+            'language' => $uiLang,
+            'user_id' => $userId,
+            'temperature' => 0.4,
+        ]);
+    }
+
+    private function resolveSystemPrompt(string $uiLang): string
+    {
+        try {
+            $req = $this->requestStack->getCurrentRequest();
+            if ($req && $req->hasSession()) {
+                $v = (string) $req->getSession()->get('ai_tutor_system_prompt', '');
+                if ('' !== trim($v)) {
+                    return $v;
+                }
+            }
+        } catch (\Throwable) {
+            // ignore
+        }
+
+        return "You are a digital tutor and mentor inside Chamilo. Answer in the user's language.";
+    }
+
+    private function generateAssistantReply(
+        string $provider,
+        Course $course,
+        AiTutorConversation $conversation
+    ): string {
+        $system = $this->buildSystemPrompt($course);
+
+        // Fetch last N messages.
+        $history = $this->conversationRepo->findMessages($conversation, 20);
+
+        $providerMessages = [
+            ['role' => 'system', 'content' => $system],
+        ];
+
+        foreach ($history as $m) {
+            $providerMessages[] = [
+                'role' => (string) $m->getRole(),
+                'content' => (string) $m->getContent(),
+            ];
+        }
+
+        // Pass stored provider conversation id when available.
+        $opts = [
+            'temperature' => 0.4,
+        ];
+
+        $prevId = $conversation->getProviderConversationId();
+        if (null !== $prevId && '' !== trim($prevId)) {
+            $opts['conversation_id'] = $prevId;
+        }
+
+        $res = $this->client->chatWithMeta($provider, $providerMessages, $opts);
+
+        // Persist provider conversation id when returned/updated.
+        if (null !== $res->conversationId && $res->conversationId !== $conversation->getProviderConversationId()) {
+            $conversation->setProviderConversationId($res->conversationId);
+            // No explicit flush needed here; handleUserMessage() flushes later when persisting assistant message.
+        }
+
+        $text = trim($res->text);
+        if ('' === $text) {
+            $text = 'I could not generate a response right now. Please try again.';
+        }
+
+        return $text;
+    }
+
+    private function buildSystemPrompt(Course $course, string $courseLanguage = ''): string
+    {
+        $title = (string) ($course->getTitle() ?: 'this course');
+        $lang = trim($courseLanguage);
+
+        return "You are a digital tutor and mentor. You help me understand topics related to my courses, in this case '{$title}'. "
+            .($lang ? "The course is in '{$lang}' but just answer me in whatever language I talk to you. " : "Just answer me in whatever language I talk to you. ")
+            ."This is an educational use, so content that would not be appropriate for children (or minors under any law) is not acceptable. "
+            ."You are not available to me when I'm taking an exam, just in case I forget and I ask why you weren't there. "
+            ."You must mention the course title when greeting or when the user asks what you are. "
+            ."If the user asks something unrelated to the course topic, politely redirect to course-related help.";
+    }
+
+    private function renderEmptyState(): string
+    {
+        return '<div class="py-10 text-center text-sm text-gray-500">'
+            .'<div class="mb-2 text-lg">🤖</div>'
+            .'<div class="font-medium text-gray-700">AI Tutor</div>'
+            .'<div class="mt-1">Ask a question to start the conversation.</div>'
+            .'</div>';
+    }
+
+    /**
+     * @param AiTutorMessage[] $messages
+     */
+    private function renderMessages(array $messages): string
+    {
+        $out = '<div class="space-y-3">';
+
+        foreach ($messages as $m) {
+            $role = (string) $m->getRole();
+            $content = $this->escape((string) $m->getContent());
+            $time = $this->formatTime($m->getCreatedAt());
+
+            $isUser = ('user' === $role);
+
+            $wrapCls = $isUser ? 'justify-end' : 'justify-start';
+            $bubbleCls = $isUser
+                ? 'bg-blue-600 text-white'
+                : 'bg-gray-100 text-gray-900';
+
+            $label = $isUser ? 'You' : 'AI Tutor';
+
+            $out .= '<div class="flex '.$wrapCls.'">';
+            $out .= '<div class="max-w-[80%] rounded-2xl px-3 py-2 text-sm '.$bubbleCls.'">';
+            $out .= '<div class="opacity-80 text-[11px] mb-1">'.$this->escape($label).' · '.$this->escape($time).'</div>';
+            $out .= '<div class="whitespace-pre-wrap">'.$content.'</div>';
+            $out .= '</div>';
+            $out .= '</div>';
+        }
+
+        $out .= '</div>';
+
+        return $out;
+    }
+
+    private function formatTime(DateTime $dt): string
+    {
+        return $dt->format('Y-m-d H:i');
+    }
+
+    private function escape(string $s): string
+    {
+        return htmlspecialchars($s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+    }
+
+    private function normalizeProvider(string $provider): string
+    {
+        $provider = trim($provider);
+
+        if ('' === $provider) {
+            $provider = self::DEFAULT_PROVIDER;
+        }
+
+        return strtolower($provider);
+    }
+
+    public function handleUserMessageAndGetAssistantText(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider,
+        string $message
+    ): string {
+        $provider = $this->normalizeProvider($provider);
+        $message = trim($message);
+
+        if ('' === $message) {
+            throw new \InvalidArgumentException('Empty message.');
+        }
+
+        $conversation = $this->getOrCreateConversation($userId, $course, $session, $provider);
+
+        // Store user message
+        $userMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('user')
+            ->setContent($message)
+        ;
+
+        $this->em->persist($userMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        // Generate assistant reply (and optionally store provider conversation id)
+        $result = $this->generateAssistantReplyWithMeta($provider, $course, $conversation);
+
+        $assistantText = trim((string) $result->text);
+        if ('' === $assistantText) {
+            $assistantText = 'I could not generate a response right now. Please try again.';
+        }
+
+        if (null !== $result->conversationId && '' !== trim($result->conversationId)) {
+            // Store provider conversation id if the provider supports it
+            if ($conversation->getProviderConversationId() !== $result->conversationId) {
+                $conversation->setProviderConversationId($result->conversationId);
+            }
+        }
+
+        // Store assistant message
+        $assistantMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('assistant')
+            ->setContent($assistantText)
+        ;
+
+        $this->em->persist($assistantMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        return $assistantText;
+    }
+
+    private function generateAssistantReplyWithMeta(
+        string $provider,
+        Course $course,
+        AiTutorConversation $conversation
+    ): AiChatCompletionResult {
+        $system = $this->buildSystemPrompt($course);
+
+        $history = $this->conversationRepo->findMessages($conversation, 20);
+
+        $providerMessages = [];
+        $providerMessages[] = ['role' => 'system', 'content' => $system];
+
+        foreach ($history as $m) {
+            $providerMessages[] = [
+                'role' => (string) $m->getRole(),
+                'content' => (string) $m->getContent(),
+            ];
+        }
+
+        $options = [
+            'temperature' => 0.4,
+        ];
+
+        // Optional: if provider supports conversation continuity via an id
+        if (null !== $conversation->getProviderConversationId() && '' !== trim($conversation->getProviderConversationId() ?? '')) {
+            $options['conversation_id'] = $conversation->getProviderConversationId();
+        }
+
+        return $this->client->chatWithMeta($provider, $providerMessages, $options);
+    }
+}
diff --git a/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php b/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
new file mode 100644
index 00000000000..3a2320908f1
--- /dev/null
+++ b/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
@@ -0,0 +1,205 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\AiProvider;
+
+use Psr\Log\LoggerInterface;
+use Throwable;
+
+final class DefaultAiChatCompletionClient implements AiChatCompletionClientInterface
+{
+    public function __construct(
+        private readonly AiProviderFactory $factory,
+        private readonly LoggerInterface $logger
+    ) {}
+
+    public function chat(string $provider, array $messages, array $options = []): string
+    {
+        $r = $this->chatWithMeta($provider, $messages, $options);
+
+        $text = trim($r->text);
+        if ('' === $text) {
+            return 'I could not generate a response right now. Please try again.';
+        }
+
+        return $text;
+    }
+
+    public function chatWithMeta(string $provider, array $messages, array $options = []): AiChatCompletionResult
+    {
+        try {
+            $providerInstance = $this->factory->getProvider($provider, 'text');
+
+            if (!\is_object($providerInstance)) {
+                $this->logger->warning('[AiTutorChat] Invalid provider instance', [
+                    'provider' => $provider,
+                    'type' => gettype($providerInstance),
+                ]);
+
+                return new AiChatCompletionResult('AI is temporarily unavailable. Please try again later.', null);
+            }
+
+            // If provider has a native chatWithMeta(), use it
+            if (method_exists($providerInstance, 'chatWithMeta')) {
+                $r = $providerInstance->chatWithMeta($messages, $options);
+                if ($r instanceof AiChatCompletionResult) {
+                    return $r;
+                }
+            }
+
+            // Default: fallback to chat() and no conversation id
+            $text = '';
+
+            if (method_exists($providerInstance, 'chat')) {
+                $text = (string) $providerInstance->chat($messages, $options);
+            } elseif (method_exists($providerInstance, 'generateText')) {
+                $prompt = $this->messagesToPrompt($messages);
+                $text = (string) $providerInstance->generateText($prompt, $options);
+            } elseif (method_exists($providerInstance, 'generate')) {
+                $prompt = $this->messagesToPrompt($messages);
+                $text = (string) $providerInstance->generate($prompt, $options);
+            }
+
+            $text = trim($text);
+            if ('' === $text) {
+                $text = 'I could not generate a response right now. Please try again.';
+            }
+
+            return new AiChatCompletionResult($text, null);
+        } catch (Throwable $e) {
+            $this->logger->error('[AiTutorChat] Chat provider call failed', [
+                'provider' => $provider,
+                'error' => $e->getMessage(),
+            ]);
+
+            return new AiChatCompletionResult('AI is temporarily unavailable. Please try again later.', null);
+        }
+    }
+
+    /**
+     * @param mixed $raw
+     */
+    private function extractResult(string $provider, mixed $raw): AiChatCompletionResult
+    {
+        // Already normalized
+        if ($raw instanceof AiChatCompletionResult) {
+            return $this->normalizeEmpty($raw);
+        }
+
+        $text = '';
+        $conversationId = null;
+
+        // Common array shapes: ['text' => '...', 'conversation_id' => '...']
+        if (\is_array($raw)) {
+            $text = (string) ($raw['text'] ?? $raw['content'] ?? $raw['message'] ?? $raw['output_text'] ?? '');
+            $conversationId = $this->extractConversationIdFromArray($raw);
+
+            return $this->normalizeEmpty(new AiChatCompletionResult(trim($text), $conversationId));
+        }
+
+        // Objects: try getters / public properties
+        if (\is_object($raw)) {
+            if (method_exists($raw, 'getText')) {
+                $text = (string) $raw->getText();
+            } elseif (property_exists($raw, 'text')) {
+                /** @phpstan-ignore-next-line */
+                $text = (string) $raw->text;
+            } elseif (method_exists($raw, '__toString')) {
+                $text = (string) $raw;
+            }
+
+            if (method_exists($raw, 'getConversationId')) {
+                $conversationId = $raw->getConversationId();
+            } elseif (property_exists($raw, 'conversationId')) {
+                /** @phpstan-ignore-next-line */
+                $conversationId = $raw->conversationId;
+            } elseif (property_exists($raw, 'conversation_id')) {
+                /** @phpstan-ignore-next-line */
+                $conversationId = $raw->conversation_id;
+            } elseif (property_exists($raw, 'previous_id')) {
+                /** @phpstan-ignore-next-line */
+                $conversationId = $raw->previous_id;
+            }
+
+            $conversationId = $this->normalizeConvId($conversationId);
+
+            return $this->normalizeEmpty(new AiChatCompletionResult(trim((string) $text), $conversationId));
+        }
+
+        // Strings
+        $text = trim((string) $raw);
+
+        // If provider returned empty/unknown, fallback message
+        if ('' === $text) {
+            $this->logger->warning('[AiTutorChat] Provider returned empty response', [
+                'provider' => $provider,
+                'rawType' => gettype($raw),
+            ]);
+
+            $text = 'I could not generate a response right now. Please try again.';
+        }
+
+        return new AiChatCompletionResult($text, null);
+    }
+
+    private function normalizeEmpty(AiChatCompletionResult $r): AiChatCompletionResult
+    {
+        $text = trim($r->text);
+        if ('' === $text) {
+            return new AiChatCompletionResult(
+                'I could not generate a response right now. Please try again.',
+                $this->normalizeConvId($r->conversationId)
+            );
+        }
+
+        return new AiChatCompletionResult($text, $this->normalizeConvId($r->conversationId));
+    }
+
+    /**
+     * @param array<string,mixed> $raw
+     */
+    private function extractConversationIdFromArray(array $raw): ?string
+    {
+        // Prefer explicit keys only (avoid picking generic "id" which might be message id).
+        $cand = $raw['conversation_id'] ?? $raw['conversationId'] ?? $raw['previous_id'] ?? $raw['previousId'] ?? null;
+
+        return $this->normalizeConvId($cand);
+    }
+
+    private function normalizeConvId(mixed $v): ?string
+    {
+        if (null === $v) {
+            return null;
+        }
+
+        $s = trim((string) $v);
+
+        return '' !== $s ? $s : null;
+    }
+
+    /**
+     * Convert messages into a compact prompt for non-chat providers.
+     *
+     * @param array<int, array{role:string,content:string}> $messages
+     */
+    private function messagesToPrompt(array $messages): string
+    {
+        $lines = [];
+
+        foreach ($messages as $m) {
+            $role = $m['role'] ?? 'user';
+            $content = trim((string) ($m['content'] ?? ''));
+
+            if ('' === $content) {
+                continue;
+            }
+
+            $lines[] = strtoupper($role).': '.$content;
+        }
+
+        return implode("\n", $lines);
+    }
+}
diff --git a/src/CoreBundle/AiProvider/GrokDocumentProvider.php b/src/CoreBundle/AiProvider/GrokDocumentProvider.php
deleted file mode 100644
index 53a48a95985..00000000000
--- a/src/CoreBundle/AiProvider/GrokDocumentProvider.php
+++ /dev/null
@@ -1,154 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Chamilo\CoreBundle\AiProvider;
-
-use Chamilo\CoreBundle\Entity\AiRequests;
-use Chamilo\CoreBundle\Repository\AiRequestsRepository;
-use Chamilo\CoreBundle\Settings\SettingsManager;
-use Exception;
-use RuntimeException;
-use Symfony\Bundle\SecurityBundle\Security;
-use Symfony\Component\Security\Core\User\UserInterface;
-use Symfony\Contracts\HttpClient\HttpClientInterface;
-
-/**
- * Grok (xAI) provider for document generation.
- * Note: This provider generates structured text (e.g., Markdown) that can be converted to PDF client-side.
- */
-class GrokDocumentProvider implements AiDocumentProviderInterface
-{
-    private string $apiUrl;
-    private string $apiKey;
-    private string $model;
-    private array $defaultOptions;
-
-    private HttpClientInterface $httpClient;
-    private AiRequestsRepository $aiRequestsRepository;
-    private SettingsManager $settingsManager;
-    private Security $security;
-
-    public function __construct(
-        HttpClientInterface $httpClient,
-        SettingsManager $settingsManager,
-        AiRequestsRepository $aiRequestsRepository,
-        Security $security
-    ) {
-        $this->httpClient = $httpClient;
-        $this->aiRequestsRepository = $aiRequestsRepository;
-        $this->settingsManager = $settingsManager;
-        $this->security = $security;
-
-        // Get AI providers from settings
-        $configJson = $settingsManager->getSetting('ai_helpers.ai_providers', true);
-        $config = json_decode($configJson, true) ?? [];
-
-        if (!isset($config['grok'])) {
-            throw new RuntimeException('Grok configuration is missing.');
-        }
-        if (!isset($config['grok']['document'])) {
-            throw new RuntimeException('Grok configuration for document generation is missing.');
-        }
-
-        $providerConfig = $config['grok'];
-        $documentConfig = $providerConfig['document'];
-
-        $this->apiKey = $providerConfig['api_key'] ?? '';
-        if (empty($this->apiKey)) {
-            throw new RuntimeException('Grok API key is missing.');
-        }
-
-        // Prefer type-specific config, fallback to root keys if needed
-        $this->apiUrl = $documentConfig['url'] ?? ($providerConfig['url'] ?? 'https://api.x.ai/v1/responses');
-        $this->model = $documentConfig['model'] ?? ($providerConfig['model'] ?? 'grok-4-1-fast-reasoning');
-
-        $this->defaultOptions = [
-            'temperature' => $documentConfig['temperature'] ?? ($providerConfig['temperature'] ?? 0.7),
-            'format' => $documentConfig['format'] ?? 'pdf',
-        ];
-    }
-
-    public function generateDocument(string $prompt, string $toolName, ?array $options = []): ?string
-    {
-        return $this->requestGrokAI($prompt, $toolName, $options ?? []);
-    }
-
-    private function requestGrokAI(string $prompt, string $toolName, array $options = []): ?string
-    {
-        $userId = $this->getUserId();
-        if (!$userId) {
-            throw new RuntimeException('User not authenticated.');
-        }
-
-        $systemContent = 'You are a helpful assistant that generates well-structured documents. Output in the specified format (e.g., Markdown for easy conversion to PDF).';
-
-        $userContent = $prompt;
-        $format = $options['format'] ?? $this->defaultOptions['format'];
-        if (!empty($format)) {
-            $userContent .= "\n\nOutput the document in {$format} format.";
-        }
-
-        $payload = [
-            'model' => $this->model,
-            'input' => [
-                ['role' => 'system', 'content' => $systemContent],
-                ['role' => 'user', 'content' => $userContent],
-            ],
-            ...array_merge($this->defaultOptions, $options),
-        ];
-
-        try {
-            $response = $this->httpClient->request('POST', $this->apiUrl, [
-                'headers' => [
-                    'Authorization' => 'Bearer '.$this->apiKey,
-                    'Content-Type' => 'application/json',
-                ],
-                'json' => $payload,
-            ]);
-
-            $statusCode = $response->getStatusCode();
-            if (200 !== $statusCode) {
-                throw new RuntimeException('API request failed with status: '.$statusCode);
-            }
-
-            $data = $response->toArray();
-
-            if (isset($data['error'])) {
-                throw new RuntimeException('API error: '.$data['error']['message']);
-            }
-
-            if (isset($data['output'][0]['content'][0]['text'])) {
-                $generatedContent = (string) $data['output'][0]['content'][0]['text'];
-
-                $usage = $data['usage'] ?? ['prompt_tokens' => 0, 'completion_tokens' => 0, 'total_tokens' => 0];
-
-                $aiRequest = new AiRequests();
-                $aiRequest->setUserId($userId)
-                    ->setToolName($toolName)
-                    ->setRequestText($prompt)
-                    ->setPromptTokens((int) ($usage['prompt_tokens'] ?? 0))
-                    ->setCompletionTokens((int) ($usage['completion_tokens'] ?? 0))
-                    ->setTotalTokens((int) ($usage['total_tokens'] ?? 0))
-                    ->setAiProvider('grok')
-                ;
-                $this->aiRequestsRepository->save($aiRequest);
-
-                return $generatedContent;
-            }
-
-            return null;
-        } catch (Exception $e) {
-            error_log('[AI][Grok][Document] Exception: '.$e->getMessage());
-
-            return null;
-        }
-    }
-
-    private function getUserId(): ?int
-    {
-        $user = $this->security->getUser();
-
-        return $user instanceof UserInterface ? $user->getId() : null;
-    }
-}
diff --git a/src/CoreBundle/AiProvider/GrokImageProvider.php b/src/CoreBundle/AiProvider/GrokImageProvider.php
deleted file mode 100644
index e397b5ee13b..00000000000
--- a/src/CoreBundle/AiProvider/GrokImageProvider.php
+++ /dev/null
@@ -1,150 +0,0 @@
-<?php
-
-declare(strict_types=1);
-
-namespace Chamilo\CoreBundle\AiProvider;
-
-use Chamilo\CoreBundle\Entity\AiRequests;
-use Chamilo\CoreBundle\Repository\AiRequestsRepository;
-use Chamilo\CoreBundle\Settings\SettingsManager;
-use Exception;
-use RuntimeException;
-use Symfony\Bundle\SecurityBundle\Security;
-use Symfony\Component\Security\Core\User\UserInterface;
-use Symfony\Contracts\HttpClient\HttpClientInterface;
-
-class GrokImageProvider implements AiImageProviderInterface
-{
-    private string $apiUrl;
-    private string $apiKey;
-    private string $model;
-    private array $defaultOptions;
-    private HttpClientInterface $httpClient;
-    private AiRequestsRepository $aiRequestsRepository;
-    private Security $security;
-
-    public function __construct(
-        HttpClientInterface $httpClient,
-        SettingsManager $settingsManager,
-        AiRequestsRepository $aiRequestsRepository,
-        Security $security
-    ) {
-        $this->httpClient = $httpClient;
-        $this->aiRequestsRepository = $aiRequestsRepository;
-        $this->security = $security;
-
-        // Get AI providers from settings
-        $configJson = $settingsManager->getSetting('ai_helpers.ai_providers', true);
-        $config = json_decode($configJson, true) ?? [];
-
-        if (!isset($config['grok'])) {
-            throw new RuntimeException('Grok configuration is missing.');
-        }
-        if (!isset($config['grok']['image'])) {
-            throw new RuntimeException('Grok configuration for image processing is missing.');
-        }
-
-        $this->apiKey = $config['grok']['api_key'] ?? '';
-        $this->apiUrl = $config['grok']['image']['url'] ?? 'https://api.x.ai/v1/images/generations';
-        $this->model = $config['grok']['image']['model'] ?? 'grok-2-image';
-        $this->defaultOptions = [
-            'response_format' => $config['grok']['image']['response_format'] ?? 'b64_json',
-            'n' => 1,
-        ];
-
-        if (empty($this->apiKey)) {
-            throw new RuntimeException('Grok API key is missing.');
-        }
-    }
-
-    public function generateImage(string $prompt, string $toolName, ?array $options = []): string|array|null
-    {
-        return $this->requestGrokAI($prompt, $toolName, $options ?? []);
-    }
-
-    private function requestGrokAI(string $prompt, string $toolName, array $options = []): string|array|null
-    {
-        $userId = $this->getUserId();
-        if (!$userId) {
-            throw new RuntimeException('User not authenticated.');
-        }
-
-        $payload = [
-            'model' => $this->model,
-            // Direct prompt string (no messages array for this endpoint)
-            'prompt' => $prompt,
-            ...array_merge($this->defaultOptions, $options),
-        ];
-
-        try {
-            $response = $this->httpClient->request('POST', $this->apiUrl, [
-                'headers' => [
-                    'Authorization' => 'Bearer '.$this->apiKey,
-                    'Content-Type' => 'application/json',
-                ],
-                'json' => $payload,
-            ]);
-
-            $statusCode = $response->getStatusCode();
-            if (200 !== $statusCode) {
-                throw new RuntimeException('API request failed with status: '.$statusCode);
-            }
-
-            $data = $response->toArray();
-
-            // Check for error key first
-            if (isset($data['error'])) {
-                throw new RuntimeException('API error: '.$data['error']['message']);
-            }
-
-            // Usage might not exist for images; default to 0
-            $usage = $data['usage'] ?? ['prompt_tokens' => 0, 'completion_tokens' => 0, 'total_tokens' => 0];
-
-            // Log request
-            $aiRequest = new AiRequests();
-            $aiRequest->setUserId($userId)
-                ->setToolName($toolName)
-                ->setRequestText($prompt)
-                ->setPromptTokens((int) ($usage['prompt_tokens'] ?? 0))
-                ->setCompletionTokens((int) ($usage['completion_tokens'] ?? 0))
-                ->setTotalTokens((int) ($usage['total_tokens'] ?? 0))
-                ->setAiProvider('grok')
-            ;
-            $this->aiRequestsRepository->save($aiRequest);
-
-            // Preferred response: base64
-            if (isset($data['data'][0]['b64_json'])) {
-                return [
-                    'content' => (string) $data['data'][0]['b64_json'],
-                    'is_base64' => true,
-                    'content_type' => 'image/png',
-                    'revised_prompt' => $data['data'][0]['revised_prompt'] ?? null,
-                ];
-            }
-
-            // Alternative response: URL
-            if (isset($data['data'][0]['url'])) {
-                return [
-                    'url' => (string) $data['data'][0]['url'],
-                    'is_base64' => false,
-                    'content_type' => 'image/png',
-                    'revised_prompt' => $data['data'][0]['revised_prompt'] ?? null,
-                ];
-            }
-
-            // Legacy fallback (should rarely happen)
-            return null;
-        } catch (Exception $e) {
-            error_log('[AI][Grok][Image] Exception: '.$e->getMessage());
-
-            return null;
-        }
-    }
-
-    private function getUserId(): ?int
-    {
-        $user = $this->security->getUser();
-
-        return $user instanceof UserInterface ? $user->getId() : null;
-    }
-}
diff --git a/src/CoreBundle/AiProvider/OpenAiProvider.php b/src/CoreBundle/AiProvider/OpenAiProvider.php
index dfaf9b5dfa4..342ec2abeb9 100644
--- a/src/CoreBundle/AiProvider/OpenAiProvider.php
+++ b/src/CoreBundle/AiProvider/OpenAiProvider.php
@@ -14,6 +14,8 @@
 use Symfony\Component\Mime\Part\Multipart\FormDataPart;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Chamilo\CoreBundle\AiProvider\AiChatCompletionResult;
+use Throwable;
 
 class OpenAiProvider implements AiProviderInterface, AiImageProviderInterface, AiVideoProviderInterface, AiDocumentProviderInterface
 {
@@ -51,6 +53,251 @@ public function __construct(
         }
     }
 
+    /**
+     * Chat completion entrypoint for AiTutorChatService.
+     *
+     * @param array<int, array{role:string,content:string}> $messages
+     * @param array<string,mixed> $options
+     */
+    public function chat(array $messages, array $options = []): string
+    {
+        $userId = $this->getUserId();
+        if (!$userId) {
+            error_log('[AI][OpenAI][chat] User not authenticated.');
+            return 'Error: User is not authenticated.';
+        }
+
+        $cfg = $this->getTypeConfig('text');
+        if (empty($cfg)) {
+            error_log('[AI][OpenAI][chat] Missing config for type: text');
+            return 'Error: OpenAI text configuration is missing.';
+        }
+
+        $url = (string) ($cfg['url'] ?? 'https://api.openai.com/v1/chat/completions');
+        $model = (string) (($options['model'] ?? null) ?? ($cfg['model'] ?? 'gpt-4o-mini'));
+        $temperature = (float) (($options['temperature'] ?? null) ?? ($cfg['temperature'] ?? 0.7));
+        $maxTokens = (int) (($options['max_tokens'] ?? null) ?? ($cfg['max_tokens'] ?? 1000));
+
+        $normalizedMessages = $this->normalizeChatMessages($messages);
+        if (empty($normalizedMessages)) {
+            error_log('[AI][OpenAI][chat] Empty messages payload.');
+            return 'Error: Empty chat messages.';
+        }
+
+        $payload = [
+            'model' => $model,
+            'messages' => $normalizedMessages,
+            'temperature' => $temperature,
+            'max_tokens' => $maxTokens,
+        ];
+
+        // Optional overrides (safe)
+        if (isset($options['top_p'])) {
+            $payload['top_p'] = (float) $options['top_p'];
+        }
+        if (isset($options['presence_penalty'])) {
+            $payload['presence_penalty'] = (float) $options['presence_penalty'];
+        }
+        if (isset($options['frequency_penalty'])) {
+            $payload['frequency_penalty'] = (float) $options['frequency_penalty'];
+        }
+
+        $logPreview = $this->messagesForLog($normalizedMessages, 900);
+
+        error_log(sprintf(
+            '[AI][OpenAI][chat] Request: userId=%d url=%s model=%s temperature=%.2f max_tokens=%d messages="%s"',
+            $userId,
+            $url,
+            $model,
+            $temperature,
+            $maxTokens,
+            $logPreview
+        ));
+
+        try {
+            $response = $this->httpClient->request('POST', $url, [
+                'headers' => $this->buildAuthHeaders(true),
+                'json' => $payload,
+            ]);
+
+            $data = $response->toArray(false);
+
+            // Handle API-level error payloads.
+            if (\is_array($data) && isset($data['error'])) {
+                $msg = $data['error']['message'] ?? null;
+                $msg = \is_string($msg) && '' !== trim($msg) ? trim($msg) : 'OpenAI returned an error response.';
+                error_log('[AI][OpenAI][chat] Error response: '.$msg);
+
+                return 'Error: '.$msg;
+            }
+
+            $generatedContent = $data['choices'][0]['message']['content'] ?? null;
+            if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
+                error_log('[AI][OpenAI][chat] Empty content returned.');
+                return 'Error: Empty response from OpenAI.';
+            }
+
+            $this->saveAiRequest(
+                $userId,
+                'chat',
+                $logPreview,
+                'openai',
+                (int) ($data['usage']['prompt_tokens'] ?? 0),
+                (int) ($data['usage']['completion_tokens'] ?? 0),
+                (int) ($data['usage']['total_tokens'] ?? 0)
+            );
+
+            return trim($generatedContent);
+        } catch (Throwable $e) {
+            error_log('[AI][OpenAI][chat] Exception: '.$e->getMessage());
+            return 'Error: '.$e->getMessage();
+        }
+    }
+
+    /**
+     * Optional fallback used by DefaultAiChatCompletionClient when a provider does not implement chat().
+     * Keeping this for compatibility.
+     */
+    public function generateText(string $prompt, array $options = []): string
+    {
+        $prompt = trim($prompt);
+        if ('' === $prompt) {
+            return 'Error: Empty prompt.';
+        }
+
+        $userId = $this->getUserId();
+        if (!$userId) {
+            error_log('[AI][OpenAI][generateText] User not authenticated.');
+            return 'Error: User is not authenticated.';
+        }
+
+        $cfg = $this->getTypeConfig('text');
+        if (empty($cfg)) {
+            error_log('[AI][OpenAI][generateText] Missing config for type: text');
+            return 'Error: OpenAI text configuration is missing.';
+        }
+
+        $url = (string) ($cfg['url'] ?? 'https://api.openai.com/v1/chat/completions');
+        $model = (string) (($options['model'] ?? null) ?? ($cfg['model'] ?? 'gpt-4o-mini'));
+        $temperature = (float) (($options['temperature'] ?? null) ?? ($cfg['temperature'] ?? 0.7));
+        $maxTokens = (int) (($options['max_tokens'] ?? null) ?? ($cfg['max_tokens'] ?? 1000));
+
+        $payload = [
+            'model' => $model,
+            'messages' => [
+                ['role' => 'system', 'content' => 'You are a helpful assistant.'],
+                ['role' => 'user', 'content' => $prompt],
+            ],
+            'temperature' => $temperature,
+            'max_tokens' => $maxTokens,
+        ];
+
+        error_log(sprintf(
+            '[AI][OpenAI][generateText] Request: userId=%d url=%s model=%s temperature=%.2f max_tokens=%d prompt="%s"',
+            $userId,
+            $url,
+            $model,
+            $temperature,
+            $maxTokens,
+            mb_substr($prompt, 0, 200)
+        ));
+
+        try {
+            $response = $this->httpClient->request('POST', $url, [
+                'headers' => $this->buildAuthHeaders(true),
+                'json' => $payload,
+            ]);
+
+            $data = $response->toArray(false);
+
+            if (\is_array($data) && isset($data['error'])) {
+                $msg = $data['error']['message'] ?? null;
+                $msg = \is_string($msg) && '' !== trim($msg) ? trim($msg) : 'OpenAI returned an error response.';
+                error_log('[AI][OpenAI][generateText] Error response: '.$msg);
+
+                return 'Error: '.$msg;
+            }
+
+            $generatedContent = $data['choices'][0]['message']['content'] ?? null;
+            if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
+                error_log('[AI][OpenAI][generateText] Empty content returned.');
+                return 'Error: Empty response from OpenAI.';
+            }
+
+            $this->saveAiRequest(
+                $userId,
+                'generateText',
+                mb_substr($prompt, 0, 900),
+                'openai',
+                (int) ($data['usage']['prompt_tokens'] ?? 0),
+                (int) ($data['usage']['completion_tokens'] ?? 0),
+                (int) ($data['usage']['total_tokens'] ?? 0)
+            );
+
+            return trim($generatedContent);
+        } catch (Throwable $e) {
+            error_log('[AI][OpenAI][generateText] Exception: '.$e->getMessage());
+            return 'Error: '.$e->getMessage();
+        }
+    }
+
+    /**
+     * @param array<int, array{role:string,content:string}> $messages
+     *
+     * @return array<int, array{role:string,content:string}>
+     */
+    private function normalizeChatMessages(array $messages): array
+    {
+        $out = [];
+
+        foreach ($messages as $m) {
+            if (!\is_array($m)) {
+                continue;
+            }
+
+            $role = isset($m['role']) ? trim((string) $m['role']) : '';
+            $content = isset($m['content']) ? trim((string) $m['content']) : '';
+
+            if ('' === $role || '' === $content) {
+                continue;
+            }
+
+            $role = strtolower($role);
+            if (!in_array($role, ['system', 'user', 'assistant', 'tool'], true)) {
+                $role = 'user';
+            }
+
+            $out[] = [
+                'role' => $role,
+                'content' => $content,
+            ];
+        }
+
+        return $out;
+    }
+
+    /**
+     * @param array<int, array{role:string,content:string}> $messages
+     */
+    private function messagesForLog(array $messages, int $maxChars = 900): string
+    {
+        $parts = [];
+        foreach ($messages as $m) {
+            $role = $m['role'] ?? 'user';
+            $content = $m['content'] ?? '';
+            $content = trim((string) $content);
+
+            if ('' === $content) {
+                continue;
+            }
+
+            $parts[] = strtoupper((string) $role).': '.mb_substr($content, 0, 300);
+        }
+
+        $s = implode(' | ', $parts);
+        return mb_substr($s, 0, $maxChars);
+    }
+
     public function generateQuestions(string $topic, int $numQuestions, string $questionType, string $language): ?string
     {
         $prompt = \sprintf(
@@ -855,4 +1102,92 @@ private function decodeOpenAiError(string $raw): array
             'param' => isset($err['param']) && is_string($err['param']) ? $err['param'] : null,
         ];
     }
+
+    /**
+     * Chat completion with conversation state (Responses API).
+     *
+     * @param array<int, array{role:string,content:string}> $messages
+     * @param array<string,mixed> $options
+     */
+    public function chatWithMeta(array $messages, array $options = []): AiChatCompletionResult
+    {
+        $text = $this->chat($messages, $options);
+        return new AiChatCompletionResult((string) $text, null);
+    }
+
+    /**
+     * Extract system instructions and build Responses API input items.
+     *
+     * @param array<int, array{role:string,content:string}> $messages
+     *
+     * @return array{0:string,1:array<int,array{role:string,content:string}>}
+     */
+    private function splitInstructionsAndInput(array $messages): array
+    {
+        $normalized = $this->normalizeChatMessages($messages);
+
+        $instructions = [];
+        $input = [];
+
+        foreach ($normalized as $m) {
+            $role = $m['role'] ?? 'user';
+            $content = trim((string) ($m['content'] ?? ''));
+
+            if ($content === '') {
+                continue;
+            }
+
+            if ($role === 'system') {
+                $instructions[] = $content;
+                continue;
+            }
+
+            $input[] = [
+                'role' => $role,
+                'content' => $content,
+            ];
+        }
+
+        return [implode("\n\n", $instructions), $input];
+    }
+
+    /**
+     * Extract the assistant text from Responses API payload.
+     */
+    private function extractResponsesApiText(array $data): string
+    {
+        // Many responses include output_text directly in the response object. :contentReference[oaicite:4]{index=4}
+        if (isset($data['output_text']) && is_string($data['output_text'])) {
+            return $data['output_text'];
+        }
+
+        // Fallback: walk through output[] -> content[] -> text.
+        if (!isset($data['output']) || !is_array($data['output'])) {
+            return '';
+        }
+
+        $parts = [];
+
+        foreach ($data['output'] as $item) {
+            if (!is_array($item)) {
+                continue;
+            }
+            if (!isset($item['content']) || !is_array($item['content'])) {
+                continue;
+            }
+
+            foreach ($item['content'] as $c) {
+                if (!is_array($c)) {
+                    continue;
+                }
+
+                // Typical shape: { "type": "output_text", "text": "..." }
+                if (isset($c['type']) && $c['type'] === 'output_text' && isset($c['text']) && is_string($c['text'])) {
+                    $parts[] = $c['text'];
+                }
+            }
+        }
+
+        return trim(implode("\n", $parts));
+    }
 }
diff --git a/src/CoreBundle/Controller/ChatController.php b/src/CoreBundle/Controller/ChatController.php
index 49a49cdf4b5..e6db9cdaf0c 100644
--- a/src/CoreBundle/Controller/ChatController.php
+++ b/src/CoreBundle/Controller/ChatController.php
@@ -6,18 +6,28 @@
 
 namespace Chamilo\CoreBundle\Controller;
 
+use Chamilo\CoreBundle\AiProvider\AiProviderFactory;
+use Chamilo\CoreBundle\AiProvider\AiTutorChatService;
+use Chamilo\CoreBundle\Entity\Course;
+use Chamilo\CoreBundle\Helpers\CidReqHelper;
+use Chamilo\CoreBundle\Helpers\LanguageHelper;
+use Chamilo\CoreBundle\Helpers\UserHelper;
+use Chamilo\CoreBundle\Repository\ChatRepository;
 use Chamilo\CoreBundle\Traits\ControllerTrait;
 use Chamilo\CoreBundle\Traits\CourseControllerTrait;
 use Chamilo\CoreBundle\Traits\ResourceControllerTrait;
-use Chamilo\CourseBundle\Controller\CourseControllerInterface;
 use Chamilo\CourseBundle\Entity\CChatConversation;
 use Chamilo\CourseBundle\Entity\CDocument;
 use Chamilo\CourseBundle\Repository\CChatConversationRepository;
 use Chamilo\CourseBundle\Repository\CDocumentRepository;
+use Chamilo\CourseBundle\Settings\SettingsCourseManager;
 use Chat;
 use CourseChatUtils;
+use DateTimeImmutable;
+use DateTimeZone;
 use Doctrine\Persistence\ManagerRegistry;
 use Event;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
 use Symfony\Component\HttpFoundation\JsonResponse;
 use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\HttpFoundation\Response;
@@ -27,15 +37,28 @@
 use const JSON_UNESCAPED_SLASHES;
 use const JSON_UNESCAPED_UNICODE;
 
-class ChatController extends AbstractResourceController implements CourseControllerInterface
+final class ChatController extends AbstractController
 {
     use ControllerTrait;
     use CourseControllerTrait;
     use ResourceControllerTrait;
 
+    public function __construct(
+        private readonly CidReqHelper $cidReqHelper,
+        private readonly UserHelper $userHelper,
+    ) {}
+
     #[Route(path: '/resources/chat/', name: 'chamilo_core_chat_home', options: ['expose' => true])]
-    public function index(Request $request, ManagerRegistry $doctrine): Response
-    {
+    public function index(
+        Request $request,
+        ManagerRegistry $doctrine,
+        SettingsCourseManager $courseSettingsManager
+    ): Response {
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            throw $this->createAccessDeniedException('User is not authenticated.');
+        }
+
         Event::event_access_tool(TOOL_CHAT);
         Event::registerLog([
             'tool' => TOOL_CHAT,
@@ -43,30 +66,52 @@ public function index(Request $request, ManagerRegistry $doctrine): Response
             'action_details' => 'start-chat',
         ]);
 
-        $course = api_get_course_entity();
-        $session = api_get_session_entity() ?: null;
+        $course = $this->cidReqHelper->getCourseEntity();
+        $session = $this->cidReqHelper->getSessionEntity();
+
+        if (null === $course) {
+            throw $this->createNotFoundException('Course context was not found in the request.');
+        }
 
         /** @var CDocumentRepository $docsRepo */
         $docsRepo = $doctrine->getRepository(CDocument::class);
         $docsRepo->ensureChatSystemFolder($course, $session);
 
+        // AI tab enable flag (safe default: off unless enabled).
+        $aiEnabled = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+
+        $courseSettingsManager->setCourse($course);
+        $aiDefaultProvider = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+
+        $sessionId = (int) ($session?->getId() ?? 0);
+        $group = $this->cidReqHelper->getGroupEntity();
+        $groupId = (int) ($group?->getIid() ?? 0);
+
         return $this->render('@ChamiloCore/Chat/chat.html.twig', [
             'restrict_to_coach' => ('true' === api_get_setting('chat.course_chat_restrict_to_coach')),
-            'user' => api_get_user_info(),
+            'user' => api_get_user_info($me, true),
             'emoji_smile' => '<span>&#128522;</span>',
             'course_url_params' => api_get_cidreq(),
             'course' => $course,
-            'session_id' => api_get_session_id(),
-            'group_id' => api_get_group_id(),
+            'session_id' => $sessionId,
+            'group_id' => $groupId,
             'chat_parent_node_id' => $course->getResourceNode()->getId(),
+
+            // AI flags for UI (course chat only)
+            'ai_enabled' => $aiEnabled,
+            'ai_default_provider' => $aiDefaultProvider,
         ]);
     }
 
     #[Route(path: '/resources/chat/conversations/', name: 'chamilo_core_chat_ajax', options: ['expose' => true])]
-    public function ajax(Request $request, ManagerRegistry $doctrine): Response
-    {
+    public function ajax(
+        Request $request,
+        ManagerRegistry $doctrine,
+        AiTutorChatService $aiTutorChatService
+    ): Response {
         $debug = false;
-        $log = function (string $msg, array $ctx = []) use ($debug): void {
+
+        $log = static function (string $msg, array $ctx = []) use ($debug): void {
             if (!$debug) {
                 return;
             }
@@ -77,13 +122,23 @@ public function ajax(Request $request, ManagerRegistry $doctrine): Response
             return new JsonResponse(['status' => false, 'error' => 'forbidden'], 403);
         }
 
-        $courseId = api_get_course_int_id();
-        $userId = api_get_user_id();
-        $sessionId = api_get_session_id();
-        $groupId = api_get_group_id();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['status' => false, 'error' => 'unauthorized'], 401);
+        }
+
+        $course = $this->cidReqHelper->getCourseEntity();
+        $session = $this->cidReqHelper->getSessionEntity();
+        $group = $this->cidReqHelper->getGroupEntity();
 
-        $course = api_get_course_entity();
-        $session = api_get_session_entity() ?: null;
+        if (null === $course) {
+            return new JsonResponse(['status' => false, 'error' => 'course_context_missing'], 400);
+        }
+
+        $courseId = (int) ($course->getId() ?? 0);
+        $userId = (int) $me;
+        $sessionId = (int) ($session?->getId() ?? 0);
+        $groupId = (int) ($group?->getIid() ?? 0);
 
         /** @var CChatConversationRepository $convRepo */
         $convRepo = $doctrine->getRepository(CChatConversation::class);
@@ -106,6 +161,12 @@ public function ajax(Request $request, ManagerRegistry $doctrine): Response
         $action = (string) $request->get('action', 'track');
         $json = ['status' => false];
 
+        // Read friend once (used by both legacy and AI paths)
+        $friend = (int) $request->get('friend', 0);
+
+        // Optional provider for AI tutor
+        $aiProvider = trim((string) $request->get('ai_provider', ''));
+
         try {
             switch ($action) {
                 case 'chat_logout':
@@ -115,17 +176,35 @@ public function ajax(Request $request, ManagerRegistry $doctrine): Response
                         'action_details' => 'exit-chat',
                     ]);
                     $json = ['status' => true];
-
                     break;
 
                 case 'track':
                     $chat->keepUserAsConnected();
                     $chat->disconnectInactiveUsers();
 
-                    $friend = (int) $request->get('friend', 0);
                     $newUsersOnline = $chat->countUsersOnline();
                     $oldUsersOnline = (int) $request->get('users_online', 0);
 
+                    if (AiTutorChatService::FRIEND_AI === $friend) {
+                        // AI Tutor conversation (private per user)
+                        $historyHtml = $aiTutorChatService->renderHistoryHtml($userId, $course, $session, $aiProvider);
+                        $lastId = $aiTutorChatService->getLastMessageId($userId, $course, $aiProvider);
+
+                        $json = [
+                            'status' => true,
+                            'data' => [
+                                // Use last message id as "size" so frontend can detect changes.
+                                'oldFileSize' => $lastId,
+                                'history' => $historyHtml,
+                                'usersOnline' => $newUsersOnline,
+                                'userList' => $newUsersOnline !== $oldUsersOnline ? $chat->listUsersOnline() : null,
+                                'currentFriend' => $friend,
+                            ],
+                        ];
+                        break;
+                    }
+
+                    // Legacy conversations (general + private user)
                     $json = [
                         'status' => true,
                         'data' => [
@@ -136,62 +215,96 @@ public function ajax(Request $request, ManagerRegistry $doctrine): Response
                             'currentFriend' => $friend,
                         ],
                     ];
-
                     break;
 
                 case 'preview':
                     $msg = (string) $request->get('message', '');
                     $json = ['status' => true, 'data' => ['message' => CourseChatUtils::prepareMessage($msg)]];
-
                     break;
 
                 case 'reset':
-                    $friend = (int) $request->get('friend', 0);
-                    $json = ['status' => true, 'data' => $chat->readMessages(true, $friend)];
+                    if (AiTutorChatService::FRIEND_AI === $friend) {
+                        $aiTutorChatService->resetConversation($userId, $course, $session, $aiProvider);
 
+                        $json = [
+                            'status' => true,
+                            'data' => $aiTutorChatService->renderHistoryHtml($userId, $course, $session, $aiProvider),
+                        ];
+                        break;
+                    }
+
+                    $json = ['status' => true, 'data' => $chat->readMessages(true, $friend)];
                     break;
 
                 case 'write':
-                    $friend = (int) $request->get('friend', 0);
                     $msg = (string) $request->get('message', '');
+
+                    if (AiTutorChatService::FRIEND_AI === $friend) {
+                        $ok = $aiTutorChatService->handleUserMessage($userId, $course, $session, $aiProvider, $msg);
+                        $json = ['status' => $ok, 'data' => ['writed' => $ok]];
+                        break;
+                    }
+
                     $ok = $chat->saveMessage($msg, $friend);
                     $json = ['status' => $ok, 'data' => ['writed' => $ok]];
-
                     break;
 
                 default:
                     $json = ['status' => false, 'error' => 'unknown_action'];
-
                     break;
             }
         } catch (Throwable $e) {
+            $log('ajax error', ['error' => $e->getMessage()]);
             $json = ['status' => false, 'error' => $e->getMessage()];
         }
 
         return new JsonResponse($json);
     }
 
+    /**
+     * ===== GLOBAL CHAT (docked) =====
+     * This is the API used by DockedChat.vue.
+     */
+
     #[Route(path: '/account/chat', name: 'chamilo_core_global_chat_home', options: ['expose' => true])]
     public function globalHome(): Response
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            throw $this->createAccessDeniedException('User is not authenticated.');
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return $this->redirectToRoute('homepage');
         }
 
-        return $this->render('@ChamiloCore/Chat/chat.html.twig', []);
+        // Render a simple container; DockedChat typically lives in the global layout.
+        return $this->render('@ChamiloCore/Chat/chat.html.twig', [
+            'restrict_to_coach' => false,
+            'user' => api_get_user_info($me, true),
+            'emoji_smile' => '<span>&#128522;</span>',
+
+            // Keep template vars safe even if not used.
+            'ai_enabled' => false,
+            'ai_default_provider' => 'openai',
+        ]);
     }
 
     #[Route(path: '/account/chat/api/start', name: 'chamilo_core_chat_api_start', options: ['expose' => true], methods: ['GET'])]
     public function globalStart(): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $chat = new Chat();
 
+        // Some legacy methods echo JSON directly; capture that safely.
         ob_start();
         $ret = $chat->startSession();
         $echoed = ob_get_clean();
@@ -210,7 +323,11 @@ public function globalStart(): JsonResponse
     #[Route(path: '/account/chat/api/contacts', name: 'chamilo_core_chat_api_contacts', options: ['expose' => true], methods: ['POST'])]
     public function globalContacts(): Response
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new Response('', 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new Response('', 403);
         }
@@ -218,13 +335,17 @@ public function globalContacts(): Response
         $chat = new Chat();
         $html = $chat->getContacts();
 
-        return new Response($html, 200, ['Content-Type' => 'text/html; charset=UTF-8']);
+        return new Response((string) $html, 200, ['Content-Type' => 'text/html; charset=UTF-8']);
     }
 
     #[Route(path: '/account/chat/api/heartbeat', name: 'chamilo_core_chat_api_heartbeat', options: ['expose' => true], methods: ['GET'])]
     public function globalHeartbeat(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
@@ -233,23 +354,23 @@ public function globalHeartbeat(Request $req): JsonResponse
         $sinceId = (int) $req->query->get('since_id', 0);
         $peerId = (int) $req->query->get('peer_id', 0);
 
-        // allow client to ask for presence inside the same heartbeat
+        // Allow client to ask for presence inside the same heartbeat.
         $presenceRaw = (string) $req->query->get('presence_ids', '');
         $presenceIds = $this->parseIdsFromRaw($presenceRaw);
 
-        // optional contacts refresh flag
+        // Optional contacts refresh flag.
         $includeContacts = (bool) $req->query->get('include_contacts', false);
 
         $chat = new Chat();
         $data = [];
 
-        // Tiny / min modes are now the "normal" unified path
+        // Tiny/min modes (recommended fast path).
         if ('tiny' === $mode && $peerId > 0) {
-            $data = $chat->heartbeatTiny(api_get_user_id(), $peerId, $sinceId);
+            $data = $chat->heartbeatTiny((int) $me, $peerId, $sinceId);
         } elseif ('min' === $mode) {
-            $data = $chat->heartbeatMin(api_get_user_id(), $sinceId);
+            $data = $chat->heartbeatMin((int) $me, $sinceId);
         } else {
-            // Fallback (legacy full heartbeat)
+            // Fallback (legacy full heartbeat).
             ob_start();
             $ret = $chat->heartbeat();
             $echoed = ob_get_clean();
@@ -265,12 +386,12 @@ public function globalHeartbeat(Request $req): JsonResponse
             $data = \is_array($ret) ? $ret : [];
         }
 
-        // Attach presence map when requested
+        // Attach presence map when requested.
         if (!empty($presenceIds)) {
             $data['presence'] = $this->buildPresenceMap($presenceIds);
         }
 
-        // Attach contacts HTML only when explicitly requested
+        // Attach contacts HTML only when explicitly requested.
         if ($includeContacts) {
             $html = $chat->getContacts();
             $data['contacts_html'] = \is_string($html) ? $html : '';
@@ -290,39 +411,228 @@ public function globalHeartbeat(Request $req): JsonResponse
     )]
     public function globalHistorySince(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $peerId = (int) $req->query->get('user_id', 0);
         $sinceId = (int) $req->query->get('since_id', 0);
+
         if ($peerId <= 0) {
             return new JsonResponse([]);
         }
 
         $chat = new Chat();
-        $items = $chat->getIncomingSince($peerId, api_get_user_id(), $sinceId);
+        $items = $chat->getIncomingSince($peerId, (int) $me, $sinceId);
+
         $resp = new JsonResponse($items);
         $resp->headers->set('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
 
         return $resp;
     }
 
-    #[Route(path: '/account/chat/api/send', name: 'chamilo_core_chat_api_send', options: ['expose' => true], methods: ['POST'])]
-    public function globalSend(Request $req): JsonResponse
-    {
-        api_block_anonymous_users();
+    #[Route(
+        path: '/account/chat/api/send',
+        name: 'chamilo_core_chat_api_send',
+        options: ['expose' => true],
+        methods: ['POST']
+    )]
+    public function globalSend(
+        Request $req,
+        AiTutorChatService $aiTutorChatService,
+        LanguageHelper $languageHelper,
+        AiProviderFactory $aiProviderFactory,
+        ChatRepository $chatRepository,
+        ManagerRegistry $doctrine
+    ): JsonResponse {
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $to = (int) $req->request->get('to', 0);
         $message = (string) $req->request->get('message', '');
+
+        // AI Tutor path (global chat)
+        if (AiTutorChatService::FRIEND_AI === $to) {
+            // Server-side guard: AI must not be available during tests.
+            if (!empty($_SESSION['is_in_a_test'])) {
+                return new JsonResponse(['error' => 'ai_disabled_in_exam'], 403);
+            }
+
+            $aiEnabledSetting = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+            if (!$aiEnabledSetting) {
+                return new JsonResponse([
+                    'error' => 'ai_disabled',
+                    'message' => 'AI tutor is disabled by configuration.',
+                ], 403);
+            }
+
+            $message = trim($message);
+            if ('' === $message) {
+                return new JsonResponse(['id' => 0]);
+            }
+
+            // Course context is OPTIONAL now.
+            $course = $this->resolveCourseFromRequest($req, $doctrine);
+
+            $uiLang = $languageHelper->getInterfaceIso();
+            $mode = (null !== $course) ? 'course' : 'global';
+
+            $courseTitle = 'Global';
+            $courseLang = $uiLang ?: 'en';
+
+            if (null !== $course) {
+                $courseTitle = (string) $course->getTitle();
+
+                $tmpLang = '';
+                if (method_exists($course, 'getCourseLanguage')) {
+                    $tmpLang = (string) ($course->getCourseLanguage() ?? '');
+                }
+                if ('' === $tmpLang && method_exists($course, 'getLanguage')) {
+                    $tmpLang = (string) ($course->getLanguage() ?? '');
+                }
+                if ('' !== $tmpLang) {
+                    $courseLang = $tmpLang;
+                }
+            }
+
+            // Store context + strict system prompt in session for the AI layer.
+            $ctx = [
+                'mode' => $mode,
+                'course_id' => (int) ($course?->getId() ?? 0),
+                'title' => $courseTitle,
+                'lang' => $courseLang ?: 'en',
+            ];
+
+            try {
+                if ($req->hasSession()) {
+                    $req->getSession()->set('ai_tutor_context', $ctx);
+                    $req->getSession()->set('ai_tutor_system_prompt', $this->buildAiTutorSystemPrompt($ctx));
+                }
+            } catch (Throwable) {
+                // Best effort: ignore session storage failures.
+            }
+
+            // Resolve a valid provider key for "text".
+            $requestedProvider = trim((string) $req->request->get('ai_provider', ''));
+            $providerKey = $this->resolveTextProviderKey($requestedProvider, $aiProviderFactory);
+
+            if (null === $providerKey) {
+                return new JsonResponse([
+                    'error' => 'ai_not_configured',
+                    'message' => 'No AI provider is configured for text generation.',
+                ], 503);
+            }
+
+            $chat = new Chat();
+
+            $nowUtc = new DateTimeImmutable('now', new DateTimeZone('UTC'));
+            $now = $nowUtc->format('Y-m-d H:i:s');
+            $nowTs = $nowUtc->getTimestamp();
+
+            // Store the user message as a normal chat row (me -> -1)
+            $userSanitized = $chat->sanitize($message);
+            $userMsgId = $chatRepository->insertChatRow(
+                (int) $me,
+                AiTutorChatService::FRIEND_AI,
+                $userSanitized,
+                1,
+                $now
+            );
+
+            try {
+                if (null !== $course) {
+                    // Persist into ai_tutor_* when course context exists
+                    $assistantText = $aiTutorChatService->handleUserMessageAndGetAssistantText(
+                        (int) $me,
+                        $course,
+                        null,
+                        $providerKey,
+                        $message
+                    );
+                } else {
+                    // Global mode: keep current behavior (no ai_tutor_* persistence without course)
+                    $assistantText = $aiTutorChatService->generateGlobalAssistantReply(
+                        (int) $me,
+                        $providerKey,
+                        $message,
+                        $uiLang
+                    );
+                }
+            } catch (Throwable $e) {
+                error_log('[AI][chat] Failed to generate assistant reply: '.$e->getMessage());
+
+                return new JsonResponse([
+                    'id' => (int) $userMsgId,
+                    'error' => 'ai_failed',
+                    'message' => $e->getMessage(),
+                ], 503);
+            }
+
+            $assistantText = \is_string($assistantText) ? trim($assistantText) : '';
+            if ('' === $assistantText) {
+                return new JsonResponse([
+                    'id' => (int) $userMsgId,
+                    'error' => 'ai_empty_reply',
+                    'message' => 'AI provider returned an empty reply.',
+                ], 503);
+            }
+
+            if (str_starts_with($assistantText, 'Error:')) {
+                return new JsonResponse([
+                    'id' => (int) $userMsgId,
+                    'error' => 'ai_failed',
+                    'message' => $assistantText,
+                ], 503);
+            }
+
+            // Store assistant message (-1 -> me) as unread (recd=0)
+            $assistantSanitized = $chat->sanitize($assistantText);
+            $assistantId = $chatRepository->insertChatRow(
+                AiTutorChatService::FRIEND_AI,
+                (int) $me,
+                $assistantSanitized,
+                0,
+                (new DateTimeImmutable('now', new DateTimeZone('UTC')))->format('Y-m-d H:i:s')
+            );
+
+            return new JsonResponse([
+                'id' => (int) $userMsgId,
+                'assistant' => [
+                    'id' => (int) $assistantId,
+                    'message' => \Security::remove_XSS($assistantSanitized),
+                    'date' => $nowTs,
+                    'recd' => 0,
+                    'from_user_info' => [
+                        'id' => AiTutorChatService::FRIEND_AI,
+                        'user_id' => AiTutorChatService::FRIEND_AI,
+                        'complete_name' => 'AI Tutor',
+                        'user_is_online_in_chat' => 1,
+                        'user_is_online' => 1,
+                        'online' => 1,
+                        'avatar_small' => '',
+                    ],
+                    'to_user_info' => api_get_user_info((int) $me, true),
+                ],
+                'mode' => $mode,
+            ]);
+        }
+
+        // Legacy path (normal users)
         $chat = new Chat();
 
         ob_start();
-        $ret = $chat->send(api_get_user_id(), $to, $message);
+        $ret = $chat->send((int) $me, $to, $message);
         $echoed = ob_get_clean();
 
         if ('' !== $echoed) {
@@ -344,7 +654,11 @@ public function globalSend(Request $req): JsonResponse
     #[Route(path: '/account/chat/api/status', name: 'chamilo_core_chat_api_status', options: ['expose' => true], methods: ['POST'])]
     public function globalStatus(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
@@ -360,7 +674,11 @@ public function globalStatus(Request $req): JsonResponse
     #[Route(path: '/account/chat/api/history', name: 'chamilo_core_chat_api_history', options: ['expose' => true], methods: ['GET'])]
     public function globalHistory(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
@@ -368,12 +686,12 @@ public function globalHistory(Request $req): JsonResponse
         $peerId = (int) $req->query->get('user_id', 0);
         $visible = (int) $req->query->get('visible_messages', 0);
 
-        if (!$peerId) {
+        if ($peerId <= 0) {
             return new JsonResponse([]);
         }
 
         $chat = new Chat();
-        $items = $chat->getPreviousMessages($peerId, api_get_user_id(), $visible);
+        $items = $chat->getPreviousMessages($peerId, (int) $me, $visible);
 
         if (!empty($items)) {
             sort($items);
@@ -387,7 +705,11 @@ public function globalHistory(Request $req): JsonResponse
     #[Route(path: '/account/chat/api/preview', name: 'chamilo_core_chat_api_preview', options: ['expose' => true], methods: ['POST'])]
     public function globalPreview(Request $req): Response
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new Response('', 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new Response('', 403);
         }
@@ -400,7 +722,11 @@ public function globalPreview(Request $req): Response
     #[Route(path: '/account/chat/api/presence', name: 'chamilo_core_chat_api_presence', options: ['expose' => true], methods: ['POST'])]
     public function globalPresence(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
@@ -416,27 +742,155 @@ public function globalPresence(Request $req): JsonResponse
     #[Route(path: '/account/chat/api/ack', name: 'chamilo_core_chat_api_ack', options: ['expose' => true], methods: ['POST'])]
     public function globalAck(Request $req): JsonResponse
     {
-        api_block_anonymous_users();
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
         if ('true' !== api_get_setting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $peerId = (int) $req->request->get('peer_id', 0);
         $lastSeenId = (int) $req->request->get('last_seen_id', 0);
-        if ($peerId <= 0 || $lastSeenId <= 0) {
+
+        if ($lastSeenId <= 0) {
+            return new JsonResponse(['ok' => false, 'error' => 'bad_params'], 400);
+        }
+
+        // AI tutor thread is not a real peer in classic chat ack. No-op.
+        if (AiTutorChatService::FRIEND_AI === $peerId) {
+            return new JsonResponse(['ok' => true, 'updated' => 0]);
+        }
+
+        if ($peerId <= 0) {
             return new JsonResponse(['ok' => false, 'error' => 'bad_params'], 400);
         }
 
         $chat = new Chat();
 
         try {
-            $n = $chat->ackReadUpTo($peerId, api_get_user_id(), $lastSeenId);
+            $n = $chat->ackReadUpTo($peerId, (int) $me, $lastSeenId);
 
             return new JsonResponse(['ok' => true, 'updated' => $n]);
         } catch (Throwable $e) {
+            error_log('[Chat][ack] Failed to ack messages: '.$e->getMessage());
+
             return new JsonResponse(['ok' => false, 'error' => $e->getMessage()], 500);
         }
     }
+    #[Route(
+        path: '/account/chat/api/tutor_context',
+        name: 'chamilo_core_chat_api_tutor_context',
+        options: ['expose' => true],
+        methods: ['GET']
+    )]
+    public function globalTutorContext(
+        Request $req,
+        AiProviderFactory $aiProviderFactory
+    ): JsonResponse {
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
+        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+            return new JsonResponse(['error' => 'disabled'], 403);
+        }
+
+        $inTest = !empty($_SESSION['is_in_a_test']);
+
+        // Allow showing AI Tutor globally. Also verify at least one text provider exists.
+        $aiEnabledSetting = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+        $providers = $aiProviderFactory->getProvidersForType('text');
+        $hasTextProvider = !empty($providers);
+
+        $enabled = $aiEnabledSetting && $hasTextProvider;
+
+        // Course context depends on cid/cidReq if present.
+        $course = $this->cidReqHelper->getDoctrineCourseEntity();
+
+        $coursePayload = null;
+        $ctx = [
+            'mode' => null,
+            'course_id' => 0,
+            'title' => 'Global',
+            'lang' => 'en',
+        ];
+
+        if (null !== $course) {
+            $courseLang = '';
+            if (method_exists($course, 'getCourseLanguage')) {
+                $courseLang = (string) ($course->getCourseLanguage() ?? '');
+            }
+            if ('' === $courseLang && method_exists($course, 'getLanguage')) {
+                $courseLang = (string) ($course->getLanguage() ?? '');
+            }
+            if ('' === $courseLang) {
+                $courseLang = 'en';
+            }
+
+            $ctx = [
+                'mode' => 'course',
+                'course_id' => (int) $course->getId(),
+                'title' => (string) $course->getTitle(),
+                'lang' => $courseLang,
+            ];
+
+            $coursePayload = [
+                'id' => $ctx['course_id'],
+                'title' => $ctx['title'],
+                'language' => $ctx['lang'],
+            ];
+        } else {
+            $ctx['mode'] = 'global';
+        }
+
+        // Store context so the AI service can build prompts consistently.
+        try {
+            if ($req->hasSession()) {
+                $req->getSession()->set('ai_tutor_context', $ctx);
+                $req->getSession()->set('ai_tutor_system_prompt', $this->buildAiTutorSystemPrompt($ctx));
+            }
+        } catch (Throwable) {
+            // Best effort: ignore session storage failures.
+        }
+
+        return new JsonResponse([
+            'enabled' => $enabled,
+            'in_test' => $inTest,
+            'course' => $coursePayload,
+            'mode' => $ctx['mode'],
+            'reason' => $enabled ? null : (!$aiEnabledSetting ? 'disabled_by_setting' : 'no_text_provider'),
+        ]);
+    }
+
+    private function buildAiTutorSystemPrompt(array $ctx): string
+    {
+        $title = (string) ($ctx['title'] ?? 'Global');
+        $lang = (string) ($ctx['lang'] ?? 'en');
+        $mode = (string) ($ctx['mode'] ?? 'global');
+
+        if ('course' === $mode) {
+            return sprintf(
+                "You are a digital tutor and mentor. You help the user understand topics related to their course '%s'. ".
+                "When greeting OR when the user asks what you are, you MUST mention the course title '%s'. ".
+                "The course is in '%s' but you must answer in whatever language the user speaks. ".
+                "This is educational use. Content that is not appropriate for minors is not acceptable. ".
+                "You are not available during exams.",
+                $title,
+                $title,
+                $lang
+            );
+        }
+
+        return sprintf(
+            "You are a digital tutor and mentor inside Chamilo. You help the user with learning and studying in general. ".
+            "You must answer in whatever language the user speaks. ".
+            "This is educational use. Content that is not appropriate for minors is not acceptable. ".
+            "You are not available during exams."
+        );
+    }
 
     /**
      * @param string $raw Raw "ids" input ("1,2,3" or JSON array)
@@ -449,15 +903,12 @@ private function parseIdsFromRaw(string $raw): array
             return [];
         }
 
-        $ids = [];
         $tryJson = json_decode($raw, true);
         if (\is_array($tryJson)) {
-            $ids = array_filter(array_map('intval', $tryJson));
-        } else {
-            $ids = array_filter(array_map('intval', preg_split('/[,\s]+/', $raw)));
+            return array_values(array_filter(array_map('intval', $tryJson)));
         }
 
-        return $ids;
+        return array_values(array_filter(array_map('intval', preg_split('/[,\s]+/', $raw) ?: [])));
     }
 
     /**
@@ -470,6 +921,19 @@ private function buildPresenceMap(array $ids): array
         $map = [];
 
         foreach ($ids as $id) {
+            $id = (int) $id;
+
+            // AI Tutor is always online.
+            if (AiTutorChatService::FRIEND_AI === $id) {
+                $map[$id] = 1;
+                continue;
+            }
+
+            if ($id <= 0) {
+                continue;
+            }
+
+            // Keep legacy user info lookup to preserve existing "online" behavior.
             $ui = api_get_user_info($id, true);
             $v = $ui['user_is_online_in_chat'] ?? $ui['user_is_online'] ?? $ui['online'] ?? null;
             $online = false;
@@ -483,13 +947,82 @@ private function buildPresenceMap(array $ids): array
             }
 
             if (false === $online && !empty($ui['last_connection'])) {
-                $ts = api_strtotime($ui['last_connection'], 'UTC');
+                $ts = strtotime((string) $ui['last_connection']) ?: 0;
                 $online = (time() - $ts) <= 120;
             }
 
             $map[$id] = $online ? 1 : 0;
         }
 
+        // Ensure AI Tutor presence exists when requested ids include it.
+        if (in_array(AiTutorChatService::FRIEND_AI, $ids, true)) {
+            $map[AiTutorChatService::FRIEND_AI] = 1;
+        }
+
         return $map;
     }
+
+    /**
+     * Pick a valid provider key for the "text" service.
+     * - If requested provider is valid for "text", use it.
+     * - Otherwise fallback to the first available "text" provider (config order).
+     */
+    private function resolveTextProviderKey(string $requestedProvider, AiProviderFactory $aiProviderFactory): ?string
+    {
+        $available = $aiProviderFactory->getProvidersForType('text');
+
+        if (empty($available)) {
+            return null;
+        }
+
+        if ('' !== $requestedProvider && in_array($requestedProvider, $available, true)) {
+            return $requestedProvider;
+        }
+
+        // Fallback: first provider configured for text in ai_helpers.ai_providers JSON.
+        return $available[0] ?? null;
+    }
+
+    /**
+     * Returns the authenticated user id using UserHelper.
+     */
+    private function getCurrentUserIdOrNull(): ?int
+    {
+        $user = $this->userHelper->getCurrent();
+
+        if (null === $user) {
+            return null;
+        }
+
+        $id = $user->getId();
+        if (null === $id) {
+            return null;
+        }
+
+        return (int) $id;
+    }
+
+    private function resolveCourseFromRequest(Request $req, ManagerRegistry $doctrine): ?Course
+    {
+        $course = $this->cidReqHelper->getDoctrineCourseEntity();
+        if (null !== $course) {
+            return $course;
+        }
+
+        $cid = (int) (
+            $req->query->get('cidReq')
+            ?? $req->query->get('cidreq')
+            ?? $req->query->get('cid')
+            ?? $req->request->get('cidReq')
+            ?? $req->request->get('cidreq')
+            ?? $req->request->get('cid')
+            ?? 0
+        );
+
+        if ($cid <= 0) {
+            return null;
+        }
+
+        return $doctrine->getRepository(Course::class)->find($cid);
+    }
 }
diff --git a/src/CoreBundle/Entity/AiTutorConversation.php b/src/CoreBundle/Entity/AiTutorConversation.php
index 407421e1fa3..35891163b2c 100644
--- a/src/CoreBundle/Entity/AiTutorConversation.php
+++ b/src/CoreBundle/Entity/AiTutorConversation.php
@@ -6,12 +6,13 @@
 
 namespace Chamilo\CoreBundle\Entity;
 
+use Chamilo\CoreBundle\Repository\AiTutorConversationRepository;
 use DateTime;
 use Doctrine\Common\Collections\ArrayCollection;
 use Doctrine\Common\Collections\Collection;
 use Doctrine\ORM\Mapping as ORM;
 
-#[ORM\Entity]
+#[ORM\Entity(repositoryClass: AiTutorConversationRepository::class)]
 #[ORM\Table(name: 'ai_tutor_conversation')]
 #[ORM\UniqueConstraint(name: 'uniq_ai_tutor_conv_user_course_provider', columns: ['user_id', 'course_id', 'ai_provider'])]
 #[ORM\Index(columns: ['user_id', 'course_id'], name: 'idx_ai_tutor_conv_user_course')]
diff --git a/src/CoreBundle/Entity/AiTutorMessage.php b/src/CoreBundle/Entity/AiTutorMessage.php
index 1b17523f9c3..1c0ad03be50 100644
--- a/src/CoreBundle/Entity/AiTutorMessage.php
+++ b/src/CoreBundle/Entity/AiTutorMessage.php
@@ -9,7 +9,6 @@
 use DateTime;
 use Doctrine\ORM\Mapping as ORM;
 
-
 #[ORM\Entity]
 #[ORM\Table(name: 'ai_tutor_message')]
 #[ORM\Index(columns: ['conversation_id', 'created_at'], name: 'idx_ai_tutor_msg_conv_created')]
@@ -21,7 +20,7 @@ class AiTutorMessage
     #[ORM\Column(name: 'id', type: 'integer')]
     protected ?int $id = null;
 
-    #[ORM\ManyToOne(targetEntity: AiTutorConversation::class)]
+    #[ORM\ManyToOne(targetEntity: AiTutorConversation::class, inversedBy: 'messages')]
     #[ORM\JoinColumn(name: 'conversation_id', referencedColumnName: 'id', nullable: false, onDelete: 'CASCADE')]
     protected AiTutorConversation $conversation;
 
diff --git a/src/CoreBundle/Entity/Chat.php b/src/CoreBundle/Entity/Chat.php
index b9362a54516..a9a8c623f02 100644
--- a/src/CoreBundle/Entity/Chat.php
+++ b/src/CoreBundle/Entity/Chat.php
@@ -6,16 +6,17 @@
 
 namespace Chamilo\CoreBundle\Entity;
 
+use Chamilo\CoreBundle\Repository\ChatRepository;
 use DateTime;
 use Doctrine\ORM\Mapping as ORM;
 
 /**
  * Chat.
  */
+#[ORM\Entity(repositoryClass: ChatRepository::class)]
 #[ORM\Table(name: 'chat')]
-#[ORM\Index(name: 'idx_chat_to_user', columns: ['to_user'])]
-#[ORM\Index(name: 'idx_chat_from_user', columns: ['from_user'])]
-#[ORM\Entity]
+#[ORM\Index(columns: ['to_user'], name: 'idx_chat_to_user')]
+#[ORM\Index(columns: ['from_user'], name: 'idx_chat_from_user')]
 class Chat
 {
     #[ORM\Column(name: 'id', type: 'integer')]
diff --git a/src/CoreBundle/Helpers/AiHelper.php b/src/CoreBundle/Helpers/AiHelper.php
new file mode 100644
index 00000000000..73b6d3585ce
--- /dev/null
+++ b/src/CoreBundle/Helpers/AiHelper.php
@@ -0,0 +1,242 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\Helpers;
+
+use Symfony\Component\HttpFoundation\RequestStack;
+use Symfony\Component\HttpFoundation\Session\SessionInterface;
+
+final class AiHelper
+{
+    public const SESSION_CURRENT_EXERCISES = 'current_exercises';
+    public const SESSION_IS_IN_A_TEST = 'is_in_a_test';
+    public const SESSION_IN_TEST_LP = 'ai_in_test_lp';
+
+    public function __construct(
+        private readonly RequestStack $requestStack
+    ) {}
+
+    private function getSession(): ?SessionInterface
+    {
+        $request = $this->requestStack->getCurrentRequest();
+        if (null === $request || !$request->hasSession()) {
+            return null;
+        }
+
+        return $request->getSession();
+    }
+
+    /**
+     * Returns true when the user is in any test context:
+     * - at least one exercise attempt marked as active (current_exercises)
+     * - or inside a quiz item in LP (ai_in_test_lp)
+     */
+    public function isUserInTest(): bool
+    {
+        $map = $this->readCurrentExercisesMap();
+        if (!empty($map)) {
+            return true;
+        }
+
+        return $this->readLpInTestFlag();
+    }
+
+    /**
+     * Marks an exercise attempt as active.
+     */
+    public function markUserInTest(int $exeId): void
+    {
+        if ($exeId <= 0) {
+            return;
+        }
+
+        $map = $this->readCurrentExercisesMap();
+        $map[$exeId] = true;
+
+        $this->writeCurrentExercisesMap($map);
+        $this->syncAggregateInTestFlag($map, null);
+    }
+
+    /**
+     * Unmarks a specific attempt. If no attempts remain active, removes the map.
+     */
+    public function clearUserInTest(int $exeId): void
+    {
+        if ($exeId <= 0) {
+            return;
+        }
+
+        $map = $this->readCurrentExercisesMap();
+
+        if (isset($map[$exeId])) {
+            unset($map[$exeId]);
+        }
+
+        if (empty($map)) {
+            $this->removeCurrentExercisesMap();
+            $this->syncAggregateInTestFlag([], null);
+            return;
+        }
+
+        $this->writeCurrentExercisesMap($map);
+        $this->syncAggregateInTestFlag($map, null);
+    }
+
+    /**
+     * LP hook: sets/unsets "in test" when the current LP item is a quiz.
+     * This does NOT require an exercise exe_id.
+     */
+    public function setUserInTestFromLearningPath(bool $inTest): void
+    {
+        $this->writeLpInTestFlag($inTest);
+
+        // Keep the aggregate flag in sync with both sources.
+        $map = $this->readCurrentExercisesMap();
+        $this->syncAggregateInTestFlag($map, $inTest);
+    }
+
+    /**
+     * Clears all attempts and LP test flag (e.g. on logout).
+     */
+    public function clearAllTests(): void
+    {
+        $this->removeCurrentExercisesMap();
+        $this->writeLpInTestFlag(false);
+        $this->removeAggregateInTestFlag();
+    }
+
+    // ------------------------------------------------------------------
+    // Internal session read/write (Symfony session first, then $_SESSION)
+    // ------------------------------------------------------------------
+
+    private function readCurrentExercisesMap(): array
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            $value = $session->get(self::SESSION_CURRENT_EXERCISES, []);
+            return is_array($value) ? $value : [];
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        $value = $_SESSION[self::SESSION_CURRENT_EXERCISES] ?? [];
+        return is_array($value) ? $value : [];
+    }
+
+    private function writeCurrentExercisesMap(array $map): void
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            $session->set(self::SESSION_CURRENT_EXERCISES, $map);
+            return;
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        $_SESSION[self::SESSION_CURRENT_EXERCISES] = $map;
+    }
+
+    private function removeCurrentExercisesMap(): void
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            $session->remove(self::SESSION_CURRENT_EXERCISES);
+            return;
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        unset($_SESSION[self::SESSION_CURRENT_EXERCISES]);
+    }
+
+    private function readLpInTestFlag(): bool
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            return (bool) $session->get(self::SESSION_IN_TEST_LP, false);
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        return !empty($_SESSION[self::SESSION_IN_TEST_LP]);
+    }
+
+    private function writeLpInTestFlag(bool $inTest): void
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            if ($inTest) {
+                $session->set(self::SESSION_IN_TEST_LP, true);
+            } else {
+                $session->remove(self::SESSION_IN_TEST_LP);
+            }
+            return;
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        if ($inTest) {
+            $_SESSION[self::SESSION_IN_TEST_LP] = true;
+        } else {
+            unset($_SESSION[self::SESSION_IN_TEST_LP]);
+        }
+    }
+
+    /**
+     * Writes the legacy-like aggregate flag "is_in_a_test" as:
+     * (current_exercises not empty) OR (lp flag true).
+     */
+    private function syncAggregateInTestFlag(array $map, ?bool $lpFlagOverride): void
+    {
+        $lpFlag = $lpFlagOverride ?? $this->readLpInTestFlag();
+        $inTest = (!empty($map)) || $lpFlag;
+
+        $session = $this->getSession();
+        if (null !== $session) {
+            if ($inTest) {
+                $session->set(self::SESSION_IS_IN_A_TEST, 1);
+            } else {
+                $session->remove(self::SESSION_IS_IN_A_TEST);
+            }
+            return;
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        if ($inTest) {
+            $_SESSION[self::SESSION_IS_IN_A_TEST] = 1;
+        } else {
+            unset($_SESSION[self::SESSION_IS_IN_A_TEST]);
+        }
+    }
+
+    private function removeAggregateInTestFlag(): void
+    {
+        $session = $this->getSession();
+        if (null !== $session) {
+            $session->remove(self::SESSION_IS_IN_A_TEST);
+            return;
+        }
+
+        if (PHP_SESSION_ACTIVE !== session_status()) {
+            @session_start();
+        }
+
+        unset($_SESSION[self::SESSION_IS_IN_A_TEST]);
+    }
+}
diff --git a/src/CoreBundle/Helpers/LanguageHelper.php b/src/CoreBundle/Helpers/LanguageHelper.php
index a346a565a1a..57274cb527d 100644
--- a/src/CoreBundle/Helpers/LanguageHelper.php
+++ b/src/CoreBundle/Helpers/LanguageHelper.php
@@ -14,17 +14,22 @@
     public function __construct(
         private LanguageRepository $languageRepository,
         private RequestStack $requestStack,
+        private UserHelper $userHelper,
     ) {}
 
+    /**
+     * Returns a BCP-47 language tag (WCAG-friendly), like "en-US" or "es-ES".
+     * Existing behavior is preserved.
+     */
     public function getWcagIso(): string
     {
-        $locale = $this->requestStack->getMainRequest()?->getLocale();
+        $locale = $this->resolveLocaleCandidate();
 
-        if ($locale) {
+        if ('' !== $locale) {
             $language = $this->languageRepository->findByIsoCode($locale);
 
             if ($language) {
-                if ($language?->getParent()) {
+                if ($language->getParent()) {
                     $language = $language->getParent();
                 }
 
@@ -34,4 +39,96 @@ public function getWcagIso(): string
 
         return 'en-US';
     }
+
+    /**
+     * Returns the current interface language ISO for features like AI/chat.
+     * Example outputs: "es", "en", "es_MX".
+     */
+    public function getInterfaceIso(): string
+    {
+        $locale = $this->resolveLocaleCandidate();
+        if ('' === $locale) {
+            return 'en';
+        }
+
+        $iso = $this->normalizeIso($locale);
+
+        // Prefer exact match (es_MX), then short match (es).
+        if (null !== $this->languageRepository->findByIsoCode($iso)) {
+            return $iso;
+        }
+
+        $short = $this->toShortIso($iso);
+        if ('' !== $short && null !== $this->languageRepository->findByIsoCode($short)) {
+            return $short;
+        }
+
+        return 'en';
+    }
+
+    private function resolveLocaleCandidate(): string
+    {
+        // Request locale (usually already the effective UI locale)
+        $reqLocale = (string) ($this->requestStack->getMainRequest()?->getLocale() ?? '');
+        $reqLocale = trim($reqLocale);
+        if ('' !== $reqLocale) {
+            return $this->normalizeIso($reqLocale);
+        }
+
+        // Authenticated user locale (no legacy functions)
+        $user = $this->userHelper->getCurrent();
+        if ($user) {
+            $userLocale = trim($user->getLocale());
+            if ('' !== $userLocale) {
+                return $this->normalizeIso($userLocale);
+            }
+        }
+
+        // Platform default ISO from settings (via repository)
+        $platformIso = trim((string) ($this->languageRepository->getPlatformDefaultIso() ?? ''));
+        if ('' !== $platformIso) {
+            return $this->normalizeIso($platformIso);
+        }
+
+        // 4) Final fallback
+        return 'en';
+    }
+
+    private function normalizeIso(string $raw): string
+    {
+        $raw = trim($raw);
+        if ('' === $raw) {
+            return '';
+        }
+
+        // Convert "es-ES" to "es_ES"
+        $raw = str_replace('-', '_', $raw);
+
+        // Normalize casing for xx_YY
+        if (preg_match('/^([a-z]{2})_([a-z]{2})$/i', $raw, $m)) {
+            return strtolower($m[1]).'_'.strtoupper($m[2]);
+        }
+
+        // If it's already "xx_YY" keep it
+        if (preg_match('/^[a-z]{2}_[A-Z]{2}$/', $raw)) {
+            return $raw;
+        }
+
+        // If it's "xx", keep
+        if (preg_match('/^[a-z]{2}$/', strtolower($raw))) {
+            return strtolower($raw);
+        }
+
+        // Otherwise, reduce to 2 letters
+        return substr(strtolower($raw), 0, 2);
+    }
+
+    private function toShortIso(string $iso): string
+    {
+        if (preg_match('/^([a-z]{2})_/', $iso, $m)) {
+            return $m[1];
+        }
+
+        return preg_match('/^[a-z]{2}$/', $iso) ? $iso : '';
+    }
 }
diff --git a/src/CoreBundle/Repository/AiTutorConversationRepository.php b/src/CoreBundle/Repository/AiTutorConversationRepository.php
new file mode 100644
index 00000000000..6fd3ccefc61
--- /dev/null
+++ b/src/CoreBundle/Repository/AiTutorConversationRepository.php
@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\Repository;
+
+use Chamilo\CoreBundle\Entity\AiTutorConversation;
+use Chamilo\CoreBundle\Entity\AiTutorMessage;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+class AiTutorConversationRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, AiTutorConversation::class);
+    }
+
+    public function findOneByUserCourseProvider(int $userId, int $courseId, string $provider): ?AiTutorConversation
+    {
+        return $this->createQueryBuilder('c')
+            ->andWhere('IDENTITY(c.user) = :uid')
+            ->andWhere('IDENTITY(c.course) = :cid')
+            ->andWhere('c.aiProvider = :p')
+            ->setParameter('uid', $userId)
+            ->setParameter('cid', $courseId)
+            ->setParameter('p', $provider)
+            ->getQuery()
+            ->getOneOrNullResult();
+    }
+
+    /**
+     * @return AiTutorMessage[]
+     */
+    public function findMessages(AiTutorConversation $conversation, int $limit = 0): array
+    {
+        $qb = $this->getEntityManager()->createQueryBuilder()
+            ->select('m')
+            ->from(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->setParameter('c', $conversation)
+            ->orderBy('m.createdAt', 'ASC');
+
+        if ($limit > 0) {
+            $qb->setMaxResults($limit);
+        }
+
+        return $qb->getQuery()->getResult();
+    }
+
+    public function clearMessages(AiTutorConversation $conversation): int
+    {
+        return (int) $this->getEntityManager()
+            ->createQueryBuilder()
+            ->delete(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->setParameter('c', $conversation)
+            ->getQuery()
+            ->execute();
+    }
+
+    public function getLastMessageId(AiTutorConversation $conversation): int
+    {
+        $id = $this->getEntityManager()
+            ->createQueryBuilder()
+            ->select('MAX(m.id)')
+            ->from(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->setParameter('c', $conversation)
+            ->getQuery()
+            ->getSingleScalarResult();
+
+        return (int) ($id ?? 0);
+    }
+}
diff --git a/src/CoreBundle/Repository/ChatRepository.php b/src/CoreBundle/Repository/ChatRepository.php
new file mode 100644
index 00000000000..f981f8f5b41
--- /dev/null
+++ b/src/CoreBundle/Repository/ChatRepository.php
@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+/* For licensing terms, see /license.txt */
+
+namespace Chamilo\CoreBundle\Repository;
+
+use Chamilo\CoreBundle\Entity\Chat as ChatEntity;
+use DateTime;
+use DateTimeImmutable;
+use DateTimeZone;
+use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
+use Doctrine\Persistence\ManagerRegistry;
+
+final class ChatRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, ChatEntity::class);
+    }
+
+    public function insertMessage(
+        int $fromUser,
+        int $toUser,
+        string $message,
+        int $recd,
+        DateTimeImmutable $sentUtc
+    ): int {
+        $chat = (new ChatEntity())
+            ->setFromUser($fromUser)
+            ->setToUser($toUser)
+            ->setMessage($message)
+            ->setRecd($recd)
+            ->setSent(\DateTime::createFromImmutable($sentUtc));
+
+        $em = $this->getEntityManager();
+        $em->persist($chat);
+        $em->flush();
+
+        return (int) $chat->getId();
+    }
+
+    /**
+     * Inserts a chat row and returns its id.
+     * Uses UTC date string (Y-m-d H:i:s) to remain compatible with legacy helpers.
+     */
+    public function insertChatRow(
+        int $fromUser,
+        int $toUser,
+        string $message,
+        int $recd,
+        string $sentUtcDateTime
+    ): int {
+        $sent = DateTime::createFromFormat('Y-m-d H:i:s', $sentUtcDateTime, new DateTimeZone('UTC'));
+        if (false === $sent) {
+            $sent = new DateTime('now', new DateTimeZone('UTC'));
+        }
+
+        $entity = (new ChatEntity())
+            ->setFromUser($fromUser)
+            ->setToUser($toUser)
+            ->setMessage($message)
+            ->setSent($sent)
+            ->setRecd($recd);
+
+        $em = $this->getEntityManager();
+        $em->persist($entity);
+        $em->flush();
+
+        return (int) $entity->getId();
+    }
+}
diff --git a/src/CoreBundle/Repository/LanguageRepository.php b/src/CoreBundle/Repository/LanguageRepository.php
index df6eb5eef3b..32cd5ced523 100644
--- a/src/CoreBundle/Repository/LanguageRepository.php
+++ b/src/CoreBundle/Repository/LanguageRepository.php
@@ -84,7 +84,7 @@ public function getAllAvailableToArray(
         return $list;
     }
 
-    private function getPlatformDefaultIso(): ?string
+    public function getPlatformDefaultIso(): ?string
     {
         $iso = trim($this->settingsManager->getSetting('language.platform_language', true));
         if ('' !== $iso) {
diff --git a/src/CoreBundle/Resources/config/services.yml b/src/CoreBundle/Resources/config/services.yml
index 8840b48c93e..316401f2c03 100644
--- a/src/CoreBundle/Resources/config/services.yml
+++ b/src/CoreBundle/Resources/config/services.yml
@@ -178,3 +178,7 @@ services:
       arguments:
         $inner: '@Chamilo\CoreBundle\Command\DoctrineMigrationsMigrateCommandDecorator.inner'
       tags: [ 'console.command' ]
+
+    Chamilo\CoreBundle\AiProvider\AiChatCompletionClientInterface:
+      class: Chamilo\CoreBundle\AiProvider\DefaultAiChatCompletionClient
+      public: true
diff --git a/src/CoreBundle/Resources/views/Chat/chat.html.twig b/src/CoreBundle/Resources/views/Chat/chat.html.twig
index d82fa8328fd..4c20a30cb56 100644
--- a/src/CoreBundle/Resources/views/Chat/chat.html.twig
+++ b/src/CoreBundle/Resources/views/Chat/chat.html.twig
@@ -10,6 +10,9 @@
         {% set courseLabel = course.title|default('Course') %}
         {% set courseUrl = '/course/' ~ course.id ~ '/home?sid=' ~ sid %}
 
+        {% set aiEnabled = ai_enabled|default(false) %}
+        {% set aiDefaultProvider = ai_default_provider|default('openai') %}
+
         <script>
           window.breadcrumb = [
             { name: "{{ rootLabel|e('js') }}", url: "{{ rootUrl|e('js') }}" },
@@ -51,6 +54,15 @@
                                                 class="tab-btn active whitespace-nowrap rounded-full px-3 py-1.5 text-sm font-medium"
                                         >{{ 'All'|trans }}</button>
                                     {% endif %}
+
+                                    {% if aiEnabled %}
+                                        <!--button
+                                                data-user="-1"
+                                                id="chat-tab--1"
+                                                class="tab-btn whitespace-nowrap rounded-full px-3 py-1.5 text-sm font-medium text-gray-600 hover:bg-gray-50"
+                                        >🤖 {{ 'AI Tutor'|trans }}</button-->
+                                    {% endif %}
+
                                     {# Dynamic user tabs added by JS #}
                                 </div>
                             </div>
@@ -60,6 +72,12 @@
                                 <div class="tab-panel" id="panel-0">
                                     <div class="chat-history" id="chat-history"></div>
                                 </div>
+
+                                {% if aiEnabled %}
+                                    <div class="tab-panel hidden" id="panel--1">
+                                        <div class="chat-history" id="chat-history--1"></div>
+                                    </div>
+                                {% endif %}
                             </div>
 
                             {# Composer #}
@@ -127,7 +145,9 @@
               chat: '{{ "Chat"|trans|e('js') }}',
               confirmReset: '{{ "Are you sure you want to clear this chat?"|trans|e('js') }}',
               loading: '{{ "Loading…"|trans|e('js') }}',
-              loadingPlain: 'Loading…'
+              loadingPlain: 'Loading…',
+              aiTutorPlaceholder: 'Ask the AI Tutor…',
+              defaultPlaceholder: '{{ "Write…"|trans|e('js') }}'
             };
 
             // ---------- helpers ----------
@@ -136,6 +156,9 @@
             const restrictToCoach = {{ restrict_to_coach ? 'true' : 'false' }};
             const parentNodeId = {{ chat_parent_node_id|default('0') }};
 
+            const aiEnabled = {{ aiEnabled ? 'true' : 'false' }};
+            const aiDefaultProvider = '{{ aiDefaultProvider|e('js') }}';
+
             const $  = (sel, root=document) => root.querySelector(sel);
             const $$ = (sel, root=document) => Array.from(root.querySelectorAll(sel));
             const qs = (obj) => new URLSearchParams(obj).toString();
@@ -145,13 +168,13 @@
             let currentFriendForNode = 0;
 
             // Ensure node parameter travels with requests ONLY for general chat (friend=0).
-            // Privacy-by-default: do not associate private conversations with a ResourceNode.
+            // Privacy-by-default: do not associate private conversations (users) nor AI Tutor with a ResourceNode.
             const withNode = (params = {}) => {
               const p = { ...params };
               const friend = Number(p.friend ?? currentFriendForNode ?? 0);
-              const isPrivate = friend > 0;
+              const isGeneral = (friend === 0);
 
-              if (!isPrivate && parentNodeId && String(parentNodeId) !== '0') {
+              if (isGeneral && parentNodeId && String(parentNodeId) !== '0') {
                 p.node = parentNodeId;
               }
               return p;
@@ -207,6 +230,16 @@
               el.scrollTop = 0;
             }
 
+            function updateComposerPlaceholder(userId) {
+              const ta = $('#chat-writer');
+              if (!ta) return;
+              if (userId === -1) {
+                ta.placeholder = T.aiTutorPlaceholder;
+              } else {
+                ta.placeholder = T.defaultPlaceholder;
+              }
+            }
+
             // ---------- Emoji picker (Unicode only) ----------
             const EMOJIS = ['😀','😃','😄','😁','😆','😅','😂','🙂','😉','😊','😇','😍','😘','😋','😛','😜','🤪','🤗','🤔','🤨','😐','😑','🙄','😏','😴','🤤','😪','😮','😯','😲','😳','🥵','🥶','😰','😥','😭','😤','😠','😡','🤬','😎','🤓','🥳','🤩','👏','👍','👎','🙏','💪','🔥','❤️','💙','💚','💛'];
             const EMOJI_ROWS = 3;
@@ -356,6 +389,8 @@
                   sendBtn.disabled = (restrictToCoach && userId === 0);
                 }
 
+                updateComposerPlaceholder(userId);
+
                 // Force server to re-send full history for the new tab
                 this._historySize = -1;
               },
@@ -372,6 +407,8 @@
                 // UX: clear the visible history while the new one loads.
                 renderHistoryLoading(userId);
 
+                updateComposerPlaceholder(userId);
+
                 return this.track({ force: true });
               },
 
@@ -393,12 +430,19 @@
 
                 const prevSize = this._historySize;
 
-                return getJSON({
+                const params = {
                   action: 'track',
                   size: this._historySize,
                   users_online: this.usersOnline,
                   friend: this.currentFriend
-                }, { signal })
+                };
+
+                // AI Tutor: attach provider hint
+                if (this.currentFriend === -1) {
+                  params.ai_provider = aiDefaultProvider;
+                }
+
+                return getJSON(params, { signal })
                   .then(response => {
                     if (!response || !response.status) return;
 
@@ -523,6 +567,10 @@
                   sid: {{ session_id|default(0) }}
                 };
 
+                if (this.currentFriend === -1) {
+                  params.ai_provider = aiDefaultProvider;
+                }
+
                 // Primary: POST
                 postForm(params)
                   .then(response => {
@@ -566,7 +614,12 @@
                 // User activity: reset backoff.
                 this._resetBackoff();
 
-                getJSON({ action: 'reset', friend: this.currentFriend })
+                const params = { action: 'reset', friend: this.currentFriend };
+                if (this.currentFriend === -1) {
+                  params.ai_provider = aiDefaultProvider;
+                }
+
+                getJSON(params)
                   .then(response => {
                     if (!response || !response.status) return;
                     this.setHistory(response.data);
@@ -658,20 +711,30 @@
                 this._started = true;
 
                 const defaultTab = document.getElementById('chat-tab-0');
+                const aiTab = document.getElementById('chat-tab--1');
+
                 if (defaultTab) {
                   setActiveTab(defaultTab);
                   showPanel(0);
                   this.currentFriend = 0;
                   currentFriendForNode = 0;
+                  updateComposerPlaceholder(0);
+                } else if (aiEnabled && aiTab) {
+                  setActiveTab(aiTab);
+                  showPanel(-1);
+                  this.currentFriend = -1;
+                  currentFriendForNode = -1;
+                  updateComposerPlaceholder(-1);
                 } else {
                   // No "All" tab exists (restrict-to-coach mode). Keep state at 0, user must pick a peer.
                   this.currentFriend = 0;
                   currentFriendForNode = 0;
+                  updateComposerPlaceholder(0);
                 }
 
                 if (restrictToCoach) {
                   const sendBtn = document.getElementById('chat-send-message');
-                  if (sendBtn) sendBtn.disabled = true;
+                  if (sendBtn) sendBtn.disabled = (this.currentFriend === 0);
                 }
 
                 this._resetBackoff();

From 67431d861980750fbb8ff999c3b4c5dabca876c3 Mon Sep 17 00:00:00 2001
From: Christian Beeznest <christian.fasanando@beeznest.com>
Date: Thu, 15 Jan 2026 23:06:33 -0500
Subject: [PATCH 2/3] Chat: Course-scoped AI tutor conversations - refs #7306

---
 assets/vue/components/chat/DockedChat.vue     | 660 ++++++++----------
 public/main/inc/lib/add_course.lib.inc.php    |  81 +++
 public/main/inc/lib/chat.lib.php              |   6 +-
 .../AiProvider/AiTutorChatService.php         | 397 +++++++++++
 src/CoreBundle/Controller/ChatController.php  | 480 ++++++++++---
 .../AiTutorConversationRepository.php         |  50 +-
 src/CoreBundle/Settings/SettingsManager.php   | 153 ++++
 7 files changed, 1378 insertions(+), 449 deletions(-)

diff --git a/assets/vue/components/chat/DockedChat.vue b/assets/vue/components/chat/DockedChat.vue
index 3b0d3417c63..fef61795a58 100644
--- a/assets/vue/components/chat/DockedChat.vue
+++ b/assets/vue/components/chat/DockedChat.vue
@@ -64,7 +64,7 @@
 
             <!-- AI Tutor quick entry (only when course context is available) -->
             <div
-              v-if="tutorCtx.enabled && !contactsHasAiTutor"
+              v-if="inCourse && tutorCtx.enabled && !contactsHasAiTutor"
               class="chd-ai"
             >
               <button
@@ -131,7 +131,7 @@
                     <span
                       class="chd-presence"
                       :class="activePeer.online ? 'on' : 'off'"
-                    ></span>
+                    />
                   </div>
                 </template>
                 <template v-else>
@@ -230,15 +230,16 @@
 <script setup>
 import { ref, reactive, computed, onBeforeUnmount, watch, onMounted } from "vue"
 import { useI18n } from "vue-i18n"
+import { useRoute } from "vue-router"
 import { useCidReq } from "../../composables/cidReq"
 
 const { t } = useI18n({ useScope: "global" })
+const route = useRoute()
 
 /**
  * cidreq context (course/session/group).
- * DockedChat may be mounted in pages without vue-router.
- * In those cases, useCidReq() can throw and would prevent the whole dock from rendering.
- * We bind it defensively and fallback to reading window.location.
+ * We prefer vue-router (route.fullPath) because DockedChat is mounted in App.vue.
+ * We still keep a safe fallback to window.location for edge cases.
  */
 const cid = ref(0)
 const sid = ref(0)
@@ -251,125 +252,84 @@ function toInt(v) {
 
 function extractCourseIdFromPath(pathname) {
   const p = String(pathname || "")
-
-  // Examples:
-  // /course/1/home
-  // /course/1/...
-  // /courses/1/...
   let m = p.match(/\/course\/(\d+)(?:\/|$)/i)
   if (m) return toInt(m[1]) || 0
-
   m = p.match(/\/courses\/(\d+)(?:\/|$)/i)
   if (m) return toInt(m[1]) || 0
-
   return 0
 }
 
-function readCidReqFromLocation() {
-  // URL parsing (supports cid/sid/gid and cidReq when numeric).
-  const sp = new URLSearchParams(window.location.search || "")
-  const cidFromQuery = toInt(sp.get("cid")) || toInt(sp.get("cidReq")) || toInt(sp.get("cidreq")) || 0
-  const cidFromPath = extractCourseIdFromPath(window.location.pathname)
+function readCidReqFromRouteAndLocation() {
+  // Try route query first
+  const q = route?.query || {}
+  const qp = (k) => (q?.[k] ?? "").toString()
 
-  cid.value = cidFromQuery || cidFromPath || 0
-  sid.value = toInt(sp.get("sid") ?? "0") || 0
-  gid.value = toInt(sp.get("gid") ?? "0") || 0
-}
+  let c = toInt(qp("cid")) || toInt(qp("cidReq")) || toInt(qp("cidreq")) || 0
+  let s = toInt(qp("sid")) || 0
+  let g = toInt(qp("gid")) || 0
 
-function bindMaybeRef(target, source) {
-  if (source && typeof source === "object" && "value" in source) {
-    target.value = toInt(source.value) || 0
-    watch(
-      source,
-      (v) => {
-        target.value = toInt(v) || 0
-      },
-      { immediate: false },
-    )
-    return
+  // Fallback to URL path for routes like /course/5/home
+  if (c <= 0) c = extractCourseIdFromPath(route?.path || window.location.pathname)
+
+  // Last fallback: raw window.location search
+  if (c <= 0) {
+    const sp = new URLSearchParams(window.location.search || "")
+    c = toInt(sp.get("cid")) || toInt(sp.get("cidReq")) || toInt(sp.get("cidreq")) || 0
+    s = s || toInt(sp.get("sid") ?? "0") || 0
+    g = g || toInt(sp.get("gid") ?? "0") || 0
+    if (c <= 0) c = extractCourseIdFromPath(window.location.pathname)
   }
-  target.value = toInt(source) || 0
+
+  cid.value = c || 0
+  sid.value = s || 0
+  gid.value = g || 0
 }
 
+/**
+ * Keep compatibility: if useCidReq() works, bind to it.
+ * If it doesn't provide cid for path-based routes, route watcher will override via readCidReqFromRouteAndLocation().
+ */
 function safeBindCidReq() {
-  let bound = false
-
   try {
     const r = useCidReq()
-    bindMaybeRef(cid, r?.cid)
-    bindMaybeRef(sid, r?.sid)
-    bindMaybeRef(gid, r?.gid)
-    bound = true
-  } catch (e) {
-    // No router / injection context: fallback to URL parsing.
-  }
-
-  // Even if useCidReq() exists, it might return 0 on URLs like /course/1/home (no cidReq in query).
-  // Fallback to location parsing when cid is still missing.
-  if (!bound || toInt(cid.value) <= 0) {
-    readCidReqFromLocation()
+    if (r?.cid && typeof r.cid === "object" && "value" in r.cid) cid.value = toInt(r.cid.value) || 0
+    if (r?.sid && typeof r.sid === "object" && "value" in r.sid) sid.value = toInt(r.sid.value) || 0
+    if (r?.gid && typeof r.gid === "object" && "value" in r.gid) gid.value = toInt(r.gid.value) || 0
+  } catch {
+    // No injection/router in some contexts: ignore.
   }
 }
 
 safeBindCidReq()
+readCidReqFromRouteAndLocation()
 
-function installUrlChangeHooks() {
-  const notify = () => readCidReqFromLocation()
-
-  window.addEventListener("popstate", notify)
-  window.addEventListener("hashchange", notify)
-
-  const wrap =
-    (fn) =>
-    (...args) => {
-      const ret = fn.apply(history, args)
-      queueMicrotask(notify)
-      return ret
-    }
-
-  history.pushState = wrap(history.pushState)
-  history.replaceState = wrap(history.replaceState)
-}
-
-installUrlChangeHooks()
-
-/**
- * Runtime cid detection (authoritative at request time).
- * This ensures that if we are in /course/{id}/... pages, we still propagate cid even without cidReq in the query.
- */
 function getRuntimeCidReq() {
-  const sp = new URLSearchParams(window.location.search || "")
-
-  let c = toInt(sp.get("cid")) || toInt(sp.get("cidReq")) || toInt(sp.get("cidreq")) || 0
+  // Use the most up-to-date reactive values first.
+  let c = toInt(cid.value)
+  let s = toInt(sid.value)
+  let g = toInt(gid.value)
 
-  let s = toInt(sp.get("sid") ?? "0") || 0
-  let g = toInt(sp.get("gid") ?? "0") || 0
-
-  if (c <= 0) {
-    c = extractCourseIdFromPath(window.location.pathname)
-  }
-
-  return { cid: c || 0, sid: s, gid: g }
+  // Ensure cid is resolved from path if needed.
+  if (c <= 0) c = extractCourseIdFromPath(route?.path || window.location.pathname)
+  return { cid: c || 0, sid: s || 0, gid: g || 0 }
 }
 
 function runtimeCidReqParams() {
   const { cid: c, sid: s, gid: g } = getRuntimeCidReq()
   if (c <= 0) return {}
-
-  // Send all 3 keys for maximum compatibility with legacy Chamilo code.
-  return {
-    cid: c,
-    cidReq: c,
-    cidreq: c,
-    sid: s || 0,
-    gid: g || 0,
-  }
+  // Keep all aliases to be compatible with legacy endpoints.
+  return { cid: c, cidReq: c, cidreq: c, sid: s || 0, gid: g || 0 }
 }
 
-// Keep cid in sync on browser navigation.
-let popstateHandler = null
-popstateHandler = () => readCidReqFromLocation()
-window.addEventListener("popstate", popstateHandler)
+watch(
+  () => {
+    const r = getRuntimeCidReq()
+    return `${r.cid}:${r.sid}:${r.gid}`
+  },
+  async (nv, ov) => {
+    if (nv === ov) return
+  },
+)
 
 /** AI peer id used across backend/services */
 const AI_PEER_ID = -1
@@ -378,25 +338,14 @@ const openedOnce = ref(false)
 const AUTO_OPEN_LAST_PEER = false
 const queuedBadgePids = new Set()
 
-/** Active peer must exist before we watch it (avoid ReferenceError). */
 const activePeer = ref(null) // { id, name, online, image }
+const activePeerAvatar = computed(() => (typeof activePeer.value?.image === "string" ? activePeer.value.image : ""))
 
-/** Avatar helper (template uses it). */
-const activePeerAvatar = computed(() => {
-  const img = activePeer.value?.image || ""
-  return typeof img === "string" ? img : ""
-})
-
-/** Persist last opened peer locally (nice UX). */
 const LAST_PEER_KEY = "chd:lastPeerId"
 watch(activePeer, (v) => {
   if (v?.id) localStorage.setItem(LAST_PEER_KEY, String(v.id))
 })
 
-/**
- * Gate: render dock only when enabled and not in pages where it must be hidden.
- * NOTE: Global chat should be visible outside courses too. Course context only affects tutor + cidReq propagation.
- */
 function isAssignmentsPage() {
   const p = String(window.location.pathname || "")
   const q = String(window.location.search || "")
@@ -420,31 +369,12 @@ function isExercisePage() {
   )
 }
 
-const cidNum = computed(() => toInt(cid.value || 0))
-const sidNum = computed(() => toInt(sid.value || 0))
-const gidNum = computed(() => toInt(gid.value || 0))
+const inCourse = computed(() => getRuntimeCidReq().cid > 0)
 
-const inCourse = computed(() => {
-  // Use runtime to avoid stale refs when cid is only in the path.
-  return getRuntimeCidReq().cid > 0
-})
-
-/**
- * Optional runtime flag set by backend. If missing, default to enabled.
- * Supported sources:
- * - window.CHAMILO_CHAT_DOCK_ENABLED
- * - window.CHAT_DOCK_ENABLED
- * - <body data-chat-dock-enabled="1|true|0|false">
- */
 const dockEnabled = computed(() => {
   const bodyVal = document?.body?.dataset?.chatDockEnabled
   const v = window?.CHAMILO_CHAT_DOCK_ENABLED ?? window?.CHAT_DOCK_ENABLED ?? window?.CHAT_DOCKED_ENABLED ?? bodyVal
-
-  if (v === undefined || v === null || v === "") {
-    // If the component is mounted, assume it's enabled unless explicitly disabled.
-    return true
-  }
-
+  if (v === undefined || v === null || v === "") return true
   if (typeof v === "string") return /^(1|true|on|yes)$/i.test(v)
   return !!v
 })
@@ -456,7 +386,6 @@ const canRenderDock = computed(() => {
   return true
 })
 
-/** ===== Endpoints ===== */
 function RG(candidates, fallback) {
   for (const name of candidates) {
     try {
@@ -483,12 +412,11 @@ const API = {
   preview: RG(["chat_api_preview", "chamilo_core_chat_api_preview"], "/account/chat/api/preview"),
   presence: RG(["chat_api_presence", "chamilo_core_chat_api_presence"], "/account/chat/api/presence"),
   ack: RG(["chat_api_ack", "chamilo_core_chat_api_ack"], "/account/chat/api/ack"),
-
-  // New: tutor context endpoint (course-aware, test-aware)
   tutor_context: RG(
     ["chat_api_tutor_context", "chamilo_core_chat_api_tutor_context"],
     "/account/chat/api/tutor_context",
   ),
+  tutor_reset: RG(["chat_api_tutor_reset", "chamilo_core_chat_api_tutor_reset"], "/account/chat/api/tutor/reset"),
 }
 
 /** ===== State ===== */
@@ -511,17 +439,17 @@ const scrollBox = ref(null)
 /** Tutor context (backend-authoritative) */
 const tutorCtx = reactive({
   loaded: false,
-  enabled: false,
+  enabled: false, // TRUE only when backend says enabled (course-aware)
   inTest: false,
   course: null, // { id, title, language }
+  provider: "", // default provider key
 })
 
-/** Unread tracking (client-side only) */
-const unreadByPeer = reactive(new Map()) // peerId -> count
-const clearedAtByPeer = reactive(new Map()) // peerId -> epoch seconds
-const lastSeenMsgIdByPeer = reactive(new Map()) // peerId -> last msg id seen
+/** Unread tracking */
+const unreadByPeer = reactive(new Map())
+const clearedAtByPeer = reactive(new Map())
+const lastSeenMsgIdByPeer = reactive(new Map())
 
-/** FAB global unread from /heartbeat?mode=min */
 const fabUnread = ref(0)
 const unreadTotal = computed(() => {
   let s = 0
@@ -533,58 +461,20 @@ const fabHasUnread = computed(() => unreadTotal.value > 0 || fabUnread.value > 0
 let hbTimer = null
 let contactsTimer = null
 
-/** ===== Utils ===== */
 function qs(obj) {
   return new URLSearchParams(obj).toString()
 }
 
-function cidReqParams() {
-  return runtimeCidReqParams()
-}
-
-/**
- * More robust AI Tutor detection to prevent duplicate entry:
- * - Detect explicit -1 in legacy onclick or data attrs
- * - Fallback to "AI Tutor" label + -1 hints (value=-1, uid=-1, etc.)
- */
-const contactsHasAiTutor = computed(() => {
-  const html = String(contactsHtml.value || "")
-  if (!html) return false
-
-  // Strong signals
-  if (
-    /chatWith\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
-    /openChat\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
-    /startChat\s*\(\s*['"]?-1['"]?\s*\)/i.test(html) ||
-    /data-(?:user|id|uid|peer|contact-id)\s*=\s*["']-1["']/i.test(html) ||
-    /\b(peer_id|user_id|uid)\s*=\s*-1\b/i.test(html) ||
-    /\bvalue\s*=\s*["']-1["']\b/i.test(html)
-  ) {
-    // If -1 appears anywhere, it's very likely the AI Tutor contact exists in legacy list.
-    return true
-  }
-
-  // Fallback: label + -1 close to it
-  if (/(AI\s*Tutor)/i.test(html) && /["'\s]-1["'\s]/.test(html)) return true
-
-  return false
-})
-
-function mergeParams(a, b) {
-  return { ...(a || {}), ...(b || {}) }
-}
-
 function withCidReq(params) {
-  // Always attach cidReq when context exists (even outside classic cidReq pages).
-  const extra = cidReqParams()
+  const extra = runtimeCidReqParams()
   if (!Object.keys(extra).length) return params || {}
-  return mergeParams(params, extra)
+  return { ...(params || {}), ...extra }
 }
 
 function addCidReqToUrl(url) {
   try {
     const u = new URL(url, window.location.origin)
-    const p = cidReqParams()
+    const p = runtimeCidReqParams()
     Object.entries(p).forEach(([k, v]) => u.searchParams.set(k, String(v)))
     return u.toString()
   } catch {
@@ -592,6 +482,51 @@ function addCidReqToUrl(url) {
   }
 }
 
+const contactsHasAiTutor = computed(() => {
+  const html = String(contactsHtml.value || "")
+  if (!html) return false
+  return (
+    /data-(?:user|id|uid|peer|contact-id)\s*=\s*["']-1["']/i.test(html) ||
+    /\b(peer_id|user_id|uid)\s*=\s*-1\b/i.test(html) ||
+    /(AI\s*Tutor)/i.test(html)
+  )
+})
+
+function normalizeContactsHtmlForAiTutor(html) {
+  const raw = String(html || "")
+  if (!raw) return ""
+
+  const wrap = document.createElement("div")
+  wrap.innerHTML = raw
+
+  // Remove any existing AI tutor rows first (different possible markers).
+  wrap
+    .querySelectorAll(
+      '.chd-ai-contact,[data-user="-1"],[data-id="-1"],[data-uid="-1"],[data-user-id="-1"],[data-id-user="-1"]',
+    )
+    .forEach((n) => n.remove())
+
+  const shouldShowAi = !!tutorCtx.enabled && !!inCourse.value && !tutorCtx.inTest
+
+  if (shouldShowAi) {
+    const row = document.createElement("div")
+    row.className = "chd-ai-contact"
+    row.dataset.user = String(AI_PEER_ID)
+    row.setAttribute("data-name", "AI Tutor")
+    row.style.cursor = "pointer"
+    row.style.padding = "10px"
+    row.style.borderBottom = "1px solid #eee"
+    row.innerHTML = `
+      <span style="margin-right:8px;">🤖</span>
+      <strong>AI Tutor</strong>
+      <span style="float:right; color:#2e7d32;">●</span>
+    `
+    wrap.prepend(row)
+  }
+
+  return wrap.innerHTML
+}
+
 function linkify(str) {
   return (str || "").replace(/(https?:\/\/[^\s<]+)/g, '<a href="$1" target="_blank" rel="noopener">$1</a>')
 }
@@ -625,7 +560,6 @@ function isMine(m) {
   return Number(m?.from_user_info?.id) === me.id || Number(m?.f) === me.id
 }
 
-/** ===== Acks: UI helpers ===== */
 function ackGlyph(msg) {
   const v = Number(msg?.recd ?? 0)
   if (v >= 2) return "✓✓"
@@ -639,7 +573,6 @@ function ackTitle(msg) {
   return t("Sending")
 }
 
-/** API helpers */
 async function getJSON(url, params) {
   const full = params ? `${url}?${qs(withCidReq(params))}` : addCidReqToUrl(url)
   const r = await fetch(full, { credentials: "same-origin" })
@@ -659,7 +592,18 @@ async function post(url, params, expectJson = true) {
   return expectJson ? r.json() : r.text()
 }
 
-/** Normalize + filters */
+function byChronoId(a, b) {
+  const da = Number(a?.date) || 0
+  const db = Number(b?.date) || 0
+  if (da !== db) return da - db
+  const aid = Number(a?.id) || 0
+  const bid = Number(b?.id) || 0
+  const aneg = aid < 0
+  const bneg = bid < 0
+  if (aneg !== bneg) return aneg ? 1 : -1
+  return aid - bid
+}
+
 function normalizeItems(raw) {
   const list = Array.isArray(raw) ? raw.slice() : Object.values(raw || {})
   return list.sort(byChronoId)
@@ -670,8 +614,8 @@ function filterAfterClear(pid, list) {
   return list.filter((m) => Number(m?.date) > cut)
 }
 
-/** Pending + dedupe (optimistic UI) */
-const pendingByPeer = reactive(new Map()) // peerId -> [{ id: tempId, msg, ts }]
+/** Pending optimistic messages */
+const pendingByPeer = reactive(new Map())
 function addPending(pid, tempId, msg, ts) {
   const arr = pendingByPeer.get(pid) || []
   arr.push({ id: tempId, msg: String(msg || ""), ts: Number(ts) })
@@ -680,10 +624,8 @@ function addPending(pid, tempId, msg, ts) {
 function removePending(pid, tempId) {
   const arr = pendingByPeer.get(pid) || []
   const idx = arr.findIndex((x) => x.id === tempId)
-  if (idx >= 0) {
-    arr.splice(idx, 1)
-    pendingByPeer.set(pid, arr)
-  }
+  if (idx >= 0) arr.splice(idx, 1)
+  pendingByPeer.set(pid, arr)
 }
 function replaceTempId(pid, tempId, newMsg) {
   const arr = messagesByPeer.get(pid) || []
@@ -705,7 +647,7 @@ function sameContent(a, b) {
   if (textA !== textB) return false
   const ta = Number(a?.date) || 0
   const tb = Number(b?.date) || 0
-  return Math.abs(ta - tb) <= 10 // tolerate minor clock drift
+  return Math.abs(ta - tb) <= 10
 }
 function adoptPendingFromServer(pid, srvList, prevList) {
   const pend = pendingByPeer.get(pid) || []
@@ -755,40 +697,60 @@ function isAtBottom(el, tolerance = 24) {
 
 async function markActiveAsRead() {
   if (!activePeer.value) return
-
   const pid = Number(activePeer.value.id || 0)
   const arr = messagesByPeer.get(pid) || []
   if (!arr.length) return
 
   const last = Number(arr[arr.length - 1]?.id || 0)
   const lastSeenPrev = Number(lastSeenMsgIdByPeer.get(pid) || 0)
-
   if (last <= 0 || last <= lastSeenPrev) return
 
-  // Update local state (best effort).
   lastSeenMsgIdByPeer.set(pid, last)
   resetUnread(pid)
 
-  // AI tutor (-1) (and any non-positive peer) is not part of classic chat ack.
+  // AI tutor is not part of classic chat ack.
   if (pid <= 0) return
 
   try {
     await post(API.ack, { peer_id: pid, last_seen_id: last })
   } catch {
-    // Best effort: ignore ack failures.
+    // ignore
   }
 }
 
+let ackDebounceTimer = null
+function debounceMarkAsRead(ms = 180) {
+  clearTimeout(ackDebounceTimer)
+  ackDebounceTimer = setTimeout(() => markActiveAsRead(), ms)
+}
+
+function isActuallyViewingActivePeer() {
+  const el = scrollBox.value
+  return open.value && document.hasFocus() && !!activePeer.value && !!el && el.clientHeight > 0 && isAtBottom(el, 24)
+}
+function maybeMarkAsReadOnView() {
+  if (isActuallyViewingActivePeer()) debounceMarkAsRead()
+}
+
+function onScrollUpLoadMore(e) {
+  const el = e.target
+  if (!activePeer.value || fetchingPrev.value) return
+  if (el.scrollTop <= 0) getPreviousMessages()
+}
+function onBodyScrollForRead() {
+  if (!activePeer.value) return
+  maybeMarkAsReadOnView()
+}
+
+/** Contacts DOM helpers */
 function extractPeerIdFromNode(node) {
   if (!node) return 0
   const ds = node.dataset || {}
-
   const cand = Number(ds.user || ds.id || ds.userId || ds.idUser || ds.uid || ds.friend || ds.contactId || 0)
   if (cand) return cand
-
   if (node.matches?.("a[href]")) {
     try {
-      const u = new URL(node.getAttribute("href"), location.origin)
+      const u = new URL(node.getAttribute("href"), window.location.origin)
       const p = Number(
         u.searchParams.get("user") ||
           u.searchParams.get("id") ||
@@ -802,20 +764,16 @@ function extractPeerIdFromNode(node) {
       // ignore
     }
   }
-
   const oc = node.getAttribute?.("onclick") || ""
   if (oc) {
     const m = oc.match(/(?:chatWith|openChat|startChat)\s*\(\s*['"]?(\d+)['"]?/i)
     if (m) return Number(m[1])
   }
-
-  // id="friend_123" / "contact-123"
   const idAttr = node.id || ""
   if (idAttr) {
     const m2 = idAttr.match(/(?:friend|user|contact|person|peer)[_-]?(\d+)/i)
     if (m2) return Number(m2[1])
   }
-
   return 0
 }
 
@@ -874,29 +832,12 @@ function repaintAllContactBadges() {
   }
 }
 
-/** Presence helpers */
-function resolveOnlineFromInfo(ui) {
-  if (!ui) return false
-  let v = ui.user_is_online_in_chat ?? ui.user_is_online ?? ui.online ?? ui.is_online ?? ui.presence
-  if (v !== undefined && v !== null) {
-    if (typeof v === "string") return /^(1|true|online|on)$/i.test(v)
-    return !!Number(v) || v === true
-  }
-  const ts = ui.last_seen_ts ?? ui.last_active_ts ?? ui.last_active_at ?? null
-  if (ts) {
-    const now = Date.now()
-    const tms = Number(ts) > 1e12 ? Number(ts) : Number(ts) * 1000
-    return now - tms <= 120000
-  }
-  return false
-}
-
 function collectVisibleContactIds() {
   const root = document.querySelector(".chd .chd-contacts .chd-contacts-html")
   const ids = new Set()
 
-  // Include AI Tutor when enabled so presence map always has it.
-  if (tutorCtx.enabled) ids.add(AI_PEER_ID)
+  // Only include AI Tutor when backend says it is enabled (course-aware).
+  if (tutorCtx.enabled && inCourse.value) ids.add(AI_PEER_ID)
 
   if (root) {
     root
@@ -911,11 +852,10 @@ function collectVisibleContactIds() {
   return Array.from(ids)
 }
 
-/** Paint presence icons on contact list */
 function paintPresenceOnContacts(map) {
   const root = document.querySelector(".chd .chd-contacts .chd-contacts-html")
   if (!root) return
-  Object.entries(map).forEach(([sid, online]) => {
+  Object.entries(map || {}).forEach(([sid, online]) => {
     const pid = Number(sid)
     const rows = findContactNodesByPeerId(root, pid)
     rows.forEach((row) => {
@@ -933,30 +873,30 @@ function paintPresenceOnContacts(map) {
   })
 }
 
+/** Tutor context */
 async function loadTutorContext() {
   tutorCtx.loaded = false
   tutorCtx.enabled = false
   tutorCtx.inTest = false
   tutorCtx.course = null
+  tutorCtx.provider = ""
 
   try {
-    // Backend decides if it's "course" or "global".
     const r = await getJSON(API.tutor_context)
-
     tutorCtx.enabled = !!r?.enabled
     tutorCtx.inTest = !!r?.in_test
     tutorCtx.course = r?.course || null
+    tutorCtx.provider = typeof r?.provider === "string" ? r.provider : ""
   } catch {
-    // Best effort: keep it disabled if request fails.
     tutorCtx.enabled = false
     tutorCtx.inTest = false
     tutorCtx.course = null
+    tutorCtx.provider = ""
   } finally {
     tutorCtx.loaded = true
   }
 }
 
-/** Flows */
 async function startSession() {
   const data = await getJSON(API.start)
   if (!data) return
@@ -968,11 +908,10 @@ async function startSession() {
   if (data.items) {
     Object.entries(data.items).forEach(([peerId, userItems]) => {
       const pid = Number(peerId)
+      // Ignore AI peer state from classic chat payload
+      if (pid <= 0) return
       const arr = filterAfterClear(pid, normalizeItems(userItems?.items ?? []))
       messagesByPeer.set(pid, arr)
-      if (activePeer.value?.id === pid && userItems?.window_user_info) {
-        activePeer.value.online = resolveOnlineFromInfo(userItems.window_user_info)
-      }
       if (arr.length) lastSeenMsgIdByPeer.set(pid, arr[arr.length - 1].id)
     })
   }
@@ -982,16 +921,13 @@ async function loadContacts() {
   loadingContacts.value = true
   try {
     const html = await post(API.contacts, { to: "user_id" }, false)
-    contactsHtml.value = String(html || "")
-    requestAnimationFrame(() => {
-      repaintAllContactBadges()
-    })
+    contactsHtml.value = normalizeContactsHtmlForAiTutor(String(html || ""))
+    requestAnimationFrame(() => repaintAllContactBadges())
   } finally {
     loadingContacts.value = false
   }
 }
 
-/** Contacts click handler */
 function onContactsClick(e) {
   const a = e.target.closest("a[href]")
   if (a) {
@@ -1023,7 +959,7 @@ function onContactsClick(e) {
 
   if (a) {
     try {
-      const u = new URL(a.getAttribute("href"), location.origin)
+      const u = new URL(a.getAttribute("href"), window.location.origin)
       const id = Number(u.searchParams.get("user") || u.searchParams.get("id") || 0)
       if (id) {
         const name = a.getAttribute("data-name") || a.textContent?.trim() || "User"
@@ -1049,15 +985,35 @@ function pickOnline() {
   return undefined
 }
 
+function aiQueryParamsIfNeeded(pid) {
+  if (Number(pid) !== AI_PEER_ID) return {}
+  return tutorCtx.provider ? { ai_provider: tutorCtx.provider } : {}
+}
+
+const lastIdByPeer = reactive(new Map())
+
+function resetAiThreadCache() {
+  messagesByPeer.delete(AI_PEER_ID)
+  unreadByPeer.set(AI_PEER_ID, 0)
+  lastSeenMsgIdByPeer.set(AI_PEER_ID, 0)
+  lastIdByPeer.set(AI_PEER_ID, 0)
+}
+
 async function openConversation(peer) {
+  const pid = Number(peer.id)
+
+  // Guard: AI Tutor must be course-only and enabled by backend.
+  if (pid === AI_PEER_ID && (!tutorCtx.enabled || !inCourse.value || tutorCtx.inTest)) return
+
   activePeer.value = {
-    id: Number(peer.id),
+    id: pid,
     name: peer.name || "User",
     image: peer.image || "",
-    online: Number(peer.id) === AI_PEER_ID ? true : (pickOnline(peer.id) ?? false),
+    online: pid === AI_PEER_ID ? true : (pickOnline(pid) ?? false),
   }
 
-  if (!messagesByPeer.get(activePeer.value.id)) {
+  const existing = messagesByPeer.get(pid)
+  if (!existing || existing.length === 0) {
     await getPreviousMessages()
   }
 
@@ -1067,34 +1023,10 @@ async function openConversation(peer) {
     maybeMarkAsReadOnView()
   })
 
-  lastIdByPeer.set(activePeer.value.id, lastKnownIdForPeer(activePeer.value.id))
+  lastIdByPeer.set(pid, lastKnownIdForPeer(pid))
   maybeResetScheduler()
 }
 
-let ackDebounceTimer = null
-function debounceMarkAsRead(ms = 180) {
-  clearTimeout(ackDebounceTimer)
-  ackDebounceTimer = setTimeout(() => markActiveAsRead(), ms)
-}
-
-function isActuallyViewingActivePeer() {
-  const el = scrollBox.value
-  return open.value && document.hasFocus() && !!activePeer.value && !!el && el.clientHeight > 0 && isAtBottom(el, 24)
-}
-function maybeMarkAsReadOnView() {
-  if (isActuallyViewingActivePeer()) debounceMarkAsRead()
-}
-
-function onScrollUpLoadMore(e) {
-  const el = e.target
-  if (!activePeer.value || fetchingPrev.value) return
-  if (el.scrollTop <= 0) getPreviousMessages()
-}
-function onBodyScrollForRead() {
-  if (!activePeer.value) return
-  maybeMarkAsReadOnView()
-}
-
 async function getPreviousMessages() {
   if (!activePeer.value) return
   const pid = activePeer.value.id
@@ -1102,7 +1034,7 @@ async function getPreviousMessages() {
   const visible = current.length
   fetchingPrev.value = true
   try {
-    const items = await getJSON(API.history, { user_id: pid, visible_messages: visible })
+    const items = await getJSON(API.history, { user_id: pid, visible_messages: visible, ...aiQueryParamsIfNeeded(pid) })
     const list = filterAfterClear(pid, normalizeItems(items))
     if (list.length) {
       const merged = [...list, ...current].sort(byChronoId)
@@ -1117,8 +1049,6 @@ async function getPreviousMessages() {
   }
 }
 
-/** per-peer last id cache and incremental fetch */
-const lastIdByPeer = reactive(new Map())
 function lastKnownIdForPeer(pid) {
   const arr = messagesByPeer.get(pid) || []
   for (let i = arr.length - 1; i >= 0; i--) {
@@ -1130,7 +1060,7 @@ function lastKnownIdForPeer(pid) {
 
 async function fetchNewForActivePeer(pid) {
   const since = lastKnownIdForPeer(pid)
-  const items = await getJSON(API.history_since, { user_id: pid, since_id: since })
+  const items = await getJSON(API.history_since, { user_id: pid, since_id: since, ...aiQueryParamsIfNeeded(pid) })
   const list = normalizeItems(items)
   if (!list.length) return
 
@@ -1147,7 +1077,8 @@ async function fetchNewForActivePeer(pid) {
 
   const viewing = open.value && activePeer.value?.id === pid && isAtBottom(scrollBox.value) && document.hasFocus()
   if (!viewing) {
-    incUnread(pid, newOnes.filter((m) => !isMine(m)).length || 0)
+    // Do not count unread for AI Tutor.
+    if (pid !== AI_PEER_ID) incUnread(pid, newOnes.filter((m) => !isMine(m)).length || 0)
   } else {
     maybeMarkAsReadOnView()
     requestAnimationFrame(() => {
@@ -1157,7 +1088,7 @@ async function fetchNewForActivePeer(pid) {
   }
 }
 
-/** Progressive backoff scheduler with override (1s→5s→10s→30s) */
+/** Backoff scheduler (kept) */
 function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
   const phases = [
     { ms: 1000, repeats: 5 },
@@ -1233,7 +1164,6 @@ function createBackoffScheduler({ onTick, onReset, getOverrideDelayMs } = {}) {
   return { start, stop, reset }
 }
 
-/** Minimal heartbeat tick */
 const lastHeartbeatId = ref(0)
 let noChangeTicks = 0
 
@@ -1246,7 +1176,6 @@ function computeGlobalLastId() {
 }
 
 function shouldPoll() {
-  // Only poll when the user is marked as online.
   return userStatus.value === 1
 }
 
@@ -1262,9 +1191,14 @@ function maybeResetScheduler() {
 function syncUnreadFromServer(payload) {
   const map = payload?.unread_by_peer
   if (!map) return
+
   Object.entries(map).forEach(([sid, count]) => {
-    unreadByPeer.set(Number(sid), Number(count) || 0)
+    const pid = Number(sid)
+    // Ignore non-positive peers (including AI Tutor = -1).
+    if (!Number.isFinite(pid) || pid <= 0) return
+    unreadByPeer.set(pid, Number(count) || 0)
   })
+
   requestAnimationFrame(() => repaintAllContactBadges())
 }
 
@@ -1274,7 +1208,6 @@ async function heartbeatMinTick() {
   const presenceIds = collectVisibleContactIds()
   const presenceParam = presenceIds.length > 0 ? { presence_ids: JSON.stringify(presenceIds) } : {}
 
-  // Ultra-light path when a conversation is active
   const pid = activePeer.value?.id
   if (pid) {
     try {
@@ -1291,19 +1224,13 @@ async function heartbeatMinTick() {
         noChangeTicks++
       }
 
-      if (r?.presence) {
-        paintPresenceOnContacts(r.presence)
-        if (activePeer.value?.id && r.presence[activePeer.value.id] !== undefined) {
-          activePeer.value.online = !!r.presence[activePeer.value.id]
-        }
-      }
+      if (r?.presence) paintPresenceOnContacts(r.presence)
     } catch {
       // ignore
     }
     return
   }
 
-  // No active peer: ultra-light global (for FAB + unread)
   try {
     const since = lastHeartbeatId.value || computeGlobalLastId()
     const params = { mode: "min", since_id: since, ...presenceParam }
@@ -1315,9 +1242,8 @@ async function heartbeatMinTick() {
     const srvLast = Number(r?.last_id ?? 0)
     const hasNew = !!r?.has_new || srvLast > since
 
-    if (typeof r?.unread === "number") {
-      fabUnread.value = r.unread
-    }
+    // Prefer local computed total instead of trusting server "unread".
+    fabUnread.value = unreadTotal.value
 
     if (hasNew) {
       lastHeartbeatId.value = Math.max(srvLast || 0, computeGlobalLastId(), since)
@@ -1330,15 +1256,11 @@ async function heartbeatMinTick() {
   }
 }
 
-// Shared backoff scheduler for both dock states (open/closed).
 const scheduler = createBackoffScheduler({
   onTick: heartbeatMinTick,
   onReset: () => {},
   getOverrideDelayMs: (baseMs) => {
-    // When the dock is closed, clamp polling to slower intervals.
-    if (!open.value) {
-      return Math.min(Math.max(baseMs, 10000), 30000) // 10s..30s
-    }
+    if (!open.value) return Math.min(Math.max(baseMs, 10000), 30000)
     return baseMs
   },
 })
@@ -1353,7 +1275,6 @@ function stopHeartbeat() {
   hbTimer = null
 }
 
-/** Send / Status / Clear */
 async function goOnline() {
   await post(API.status, { status: 1 })
   userStatus.value = 1
@@ -1378,6 +1299,7 @@ const sendDisabled = computed(() => {
   if (sending.value) return true
   if (userStatus.value !== 1) return true
   if (isAiThread.value && tutorCtx.inTest) return true
+  if (isAiThread.value && (!tutorCtx.enabled || !inCourse.value)) return true
   return false
 })
 
@@ -1387,15 +1309,14 @@ async function send() {
   const pid = Number(activePeer.value.id)
   const raw = draft.value
 
-  // Prevent sending to AI tutor when tests are running (client-side guard).
-  if (pid === AI_PEER_ID && tutorCtx.inTest) {
-    return
+  if (pid === AI_PEER_ID) {
+    if (tutorCtx.inTest) return
+    if (!tutorCtx.enabled || !inCourse.value) return
   }
 
   const msgEscaped = escapeForHtml(raw)
   const nowSec = Math.floor(Date.now() / 1000)
 
-  // Optimistic bubble
   const tempId = -Date.now()
   const optimistic = {
     from_user_info: { id: me.id, complete_name: "me" },
@@ -1421,10 +1342,11 @@ async function send() {
   sending.value = true
 
   try {
-    const res = await post(API.send, { to: pid, message: raw, chat_sec_token: me.secToken })
+    const extra = pid === AI_PEER_ID ? { ai_provider: tutorCtx.provider } : {}
+    const res = await post(API.send, { to: pid, message: raw, chat_sec_token: me.secToken, ...extra })
+
     if (res?.assistant?.id) {
       const arr2 = messagesByPeer.get(pid) || []
-      // Avoid duplicate if it already exists
       if (!arr2.find((m) => Number(m.id) === Number(res.assistant.id))) {
         messagesByPeer.set(pid, [...arr2, res.assistant].sort(byChronoId))
       }
@@ -1433,9 +1355,10 @@ async function send() {
         if (el) el.scrollTop = el.scrollHeight
       })
     }
+
     if (res && typeof res === "object" && Number(res.id) > 0) {
       if (res.sec_token) me.secToken = res.sec_token
-      replaceTempId(pid, tempId, { id: Number(res.id), recd: 0, date: nowSec })
+      replaceTempId(pid, tempId, { id: Number(res.id), recd: 2, date: nowSec })
       removePending(pid, tempId)
       return
     }
@@ -1446,39 +1369,42 @@ async function send() {
   }
 }
 
-function onComposerKeydown() {
-  // Intentionally left blank.
-}
-function newline() {
-  // Shift+Enter: let browser insert newline naturally.
-}
-
 async function clearConversation() {
   if (!activePeer.value) return
   if (!confirm(t("Are you sure you want to clear this conversation?"))) return
   clearing.value = true
   try {
     const pid = activePeer.value.id
-    const nowSec = Math.floor(Date.now() / 1000)
-    clearedAtByPeer.set(pid, nowSec)
-    messagesByPeer.set(pid, [])
-    resetUnread(pid)
+
+    if (Number(pid) === AI_PEER_ID) {
+      // Server reset for AI tutor (course-only)
+      await post(API.tutor_reset, { ai_provider: tutorCtx.provider || "" })
+      resetAiThreadCache()
+      await getPreviousMessages()
+    } else {
+      const nowSec = Math.floor(Date.now() / 1000)
+      clearedAtByPeer.set(pid, nowSec)
+      messagesByPeer.set(pid, [])
+      resetUnread(pid)
+    }
+
     requestAnimationFrame(() => {
       const el = scrollBox.value
       if (el) el.scrollTop = el.scrollHeight
     })
+  } catch {
+    // ignore
   } finally {
     clearing.value = false
   }
 }
 
-/** Computed */
 const activeMessages = computed(() => {
   if (!activePeer.value) return []
   return messagesByPeer.get(activePeer.value.id) || []
 })
 
-/** Title blink for unread */
+/** Title blink */
 const originalTitle = document.title
 let blinkTimer = null
 let blinkState = false
@@ -1526,7 +1452,6 @@ window.addEventListener("online", () => {
 })
 window.addEventListener("offline", () => scheduler.stop())
 
-/** Legacy compatibility layer */
 function registerLegacyChatGlobals() {
   const handler = (id, name) => {
     try {
@@ -1542,13 +1467,15 @@ function registerLegacyChatGlobals() {
   if (!("startChat" in window)) window.startChat = handler
 }
 
-/** Local unread reconciliation */
 function recomputeUnreadFromLocal() {
   let total = 0
   const pids = new Set([...Array.from(messagesByPeer.keys()), ...Array.from(lastSeenMsgIdByPeer.keys())])
 
   pids.forEach((pid0) => {
     const pid = Number(pid0)
+    // Ignore AI tutor in local unread computation.
+    if (pid <= 0) return
+
     const arr = messagesByPeer.get(pid) || []
     const lastSeen = Number(lastSeenMsgIdByPeer.get(pid) || 0)
     const cut = Number(clearedAtByPeer.get(pid) || 0)
@@ -1556,7 +1483,7 @@ function recomputeUnreadFromLocal() {
     let c = 0
     for (const m of arr) {
       const mid = Number(m?.id) || 0
-      if (mid <= 0) continue // ignore optimistic bubbles
+      if (mid <= 0) continue
       if (cut && Number(m?.date) <= cut) continue
       if (isMine(m)) continue
       if (mid > lastSeen) c++
@@ -1570,21 +1497,74 @@ function recomputeUnreadFromLocal() {
   requestAnimationFrame(() => repaintAllContactBadges())
 }
 
-/** Lifecycle */
+/**
+ * SPA navigation handler:
+ * - update cid/sid/gid from route
+ * - refresh tutor context
+ * - refresh contacts (AI Tutor visibility)
+ * - if AI thread is active, reload history for the new course
+ */
+let navDebounceTimer = null
+async function onNavigationChanged() {
+  readCidReqFromRouteAndLocation()
+
+  if (!canRenderDock.value) return
+
+  const aiActive = Number(activePeer.value?.id || 0) === AI_PEER_ID
+  if (!open.value && !aiActive) {
+    // Keep AI cache clean for next time.
+    resetAiThreadCache()
+    return
+  }
+
+  await loadTutorContext()
+
+  try {
+    await loadContacts()
+  } catch {
+    // ignore
+  }
+
+  if (aiActive) {
+    if (!tutorCtx.enabled || !inCourse.value || tutorCtx.inTest) {
+      activePeer.value = null
+      resetAiThreadCache()
+      return
+    }
+    resetAiThreadCache()
+    await getPreviousMessages()
+    requestAnimationFrame(() => {
+      const el = scrollBox.value
+      if (el) el.scrollTop = el.scrollHeight
+      maybeMarkAsReadOnView()
+    })
+  } else {
+    resetAiThreadCache()
+  }
+}
+
+// Use vue-router signal (no history patching, no polling).
+watch(
+  () => route.fullPath,
+  () => {
+    clearTimeout(navDebounceTimer)
+    navDebounceTimer = setTimeout(() => {
+      onNavigationChanged().catch(() => {})
+    }, 80)
+  },
+  { immediate: false },
+)
+
 async function toggleDock(v) {
   if (v === open.value) return
-
-  // Defensive: do not open when gate says we should not render here.
   if (v && !canRenderDock.value) return
 
   const wasOpen = open.value
   open.value = v
 
   if (v) {
-    // Ensure tutor context is loaded as soon as the dock opens.
     await loadTutorContext()
 
-    // OPEN: reset backoff phases when user explicitly opens.
     if (!openedOnce.value) {
       await startSession()
 
@@ -1597,7 +1577,6 @@ async function toggleDock(v) {
         userStatus.value = 1
       }
 
-      // First open: ask heartbeat for contacts + presence in one go
       const presenceIds = collectVisibleContactIds()
       const params = { mode: "min", since_id: lastHeartbeatId.value || 0, include_contacts: 1 }
       if (presenceIds.length > 0) params.presence_ids = JSON.stringify(presenceIds)
@@ -1605,7 +1584,7 @@ async function toggleDock(v) {
       const r = await getJSON(API.heartbeat, params)
 
       if (typeof r?.contacts_html === "string") {
-        contactsHtml.value = r.contacts_html
+        contactsHtml.value = normalizeContactsHtmlForAiTutor(String(r.contacts_html || ""))
         requestAnimationFrame(() => repaintAllContactBadges())
       }
       if (r?.presence) paintPresenceOnContacts(r.presence)
@@ -1631,48 +1610,38 @@ async function toggleDock(v) {
     if (!wasOpen) {
       if (AUTO_OPEN_LAST_PEER) {
         const last = Number(localStorage.getItem(LAST_PEER_KEY) || 0)
-        if (last > 0 && !activePeer.value) {
-          openConversation({ id: last, name: "User" })
-        }
+        if (last > 0 && !activePeer.value) openConversation({ id: last, name: "User" })
       } else {
         activePeer.value = null
       }
     }
   } else {
-    // CLOSE
     activePeer.value = null
     clearInterval(contactsTimer)
     contactsTimer = null
-    // Keep scheduler running in "closed" mode (slower intervals via override).
     recomputeUnreadFromLocal()
   }
 }
 
-function byChronoId(a, b) {
-  const da = Number(a?.date) || 0
-  const db = Number(b?.date) || 0
-  if (da !== db) return da - db
-  const aid = Number(a?.id) || 0
-  const bid = Number(b?.id) || 0
-  const aneg = aid < 0
-  const bneg = bid < 0
-  if (aneg !== bneg) return aneg ? 1 : -1
-  return aid - bid
-}
+watch(open, (v) => {
+  if (!v) activePeer.value = null
+})
+
+function onContactsScroll() {}
+function onComposerKeydown() {}
+function newline() {}
 
 onMounted(async () => {
   registerLegacyChatGlobals()
 
-  // If dock is not allowed here, do not boot any network calls.
   if (!canRenderDock.value) return
 
-  // Load tutor context early (only effective in courses).
-  await loadTutorContext()
+  // Ensure cid is set on initial mount (important for /course/ID/home routes).
+  readCidReqFromRouteAndLocation()
 
-  // Boot minimal session state so unread can be computed even when dock is closed.
+  await loadTutorContext()
   await startSession()
 
-  // If user already online at mount time, start scheduler immediately.
   if (userStatus.value === 1) startHeartbeat()
 
   try {
@@ -1687,20 +1656,7 @@ onBeforeUnmount(() => {
   clearInterval(contactsTimer)
   contactsTimer = null
   stopBlinkNow()
-
-  if (popstateHandler) {
-    window.removeEventListener("popstate", popstateHandler)
-    popstateHandler = null
-  }
 })
-
-watch(open, (v) => {
-  if (!v) activePeer.value = null
-})
-
-function onContactsScroll() {
-  // Intentionally left blank (no pagination yet).
-}
 </script>
 
 <style scoped>
diff --git a/public/main/inc/lib/add_course.lib.inc.php b/public/main/inc/lib/add_course.lib.inc.php
index 889070fee45..5e5a8783a93 100644
--- a/public/main/inc/lib/add_course.lib.inc.php
+++ b/public/main/inc/lib/add_course.lib.inc.php
@@ -16,6 +16,28 @@
 class AddCourse
 {
     public const FIRST_EXPIRATION_DATE = 31536000; // 365 days in seconds
+    /**
+     * Platform -> course_setting default propagation for NEW courses.
+     * Extend this map later for other categories/features.
+     */
+    private const PLATFORM_TO_COURSE_SETTING_DEFAULTS = [
+        'ai_helpers' => [
+            'enable' => 'enable_ai_helpers',
+            'keys' => [
+                'learning_path_generator',
+                'exercise_generator',
+                'open_answers_grader',
+                'tutor_chatbot',
+                'task_grader',
+                'content_analyser',
+                'image_generator',
+                'glossary_terms_generator',
+                'video_generator',
+                'course_analyser',
+            ],
+            'course_category' => 'ai_helpers',
+        ],
+    ];
 
     /**
      * Defines the four needed keys to create a course based on several parameters.
@@ -324,6 +346,9 @@ private static function insertCourseSettings(Course $course): void
             );
             $counter++;
         }
+
+        // Apply platform defaults for this new course (AI helpers, etc.)
+        self::applyPlatformDefaultsToCourseSettings($course);
     }
 
     /**
@@ -990,4 +1015,60 @@ public static function generateToolId($courseId)
 
         return $newIdResultData['new_id'] > 0 ? $newIdResultData['new_id'] : 1;
     }
+
+    /**
+     * Apply platform defaults into legacy course_setting for a newly created course.
+     * Inserts missing rows only (does not overwrite existing rows).
+     */
+    private static function applyPlatformDefaultsToCourseSettings(Course $course, int $accessUrlId = 0): void
+    {
+        $courseId = (int) $course->getId();
+        if ($courseId <= 0) {
+            return;
+        }
+
+        $table = Database::get_course_table(TABLE_COURSE_SETTING);
+
+        foreach (self::PLATFORM_TO_COURSE_SETTING_DEFAULTS as $platformCategory => $cfg) {
+            $enableKey = (string) ($cfg['enable'] ?? '');
+            if ('' === $enableKey) {
+                continue;
+            }
+
+            // Gate: if the main switch is off, do nothing
+            if ('true' !== (string) api_get_setting($platformCategory.'.'.$enableKey)) {
+                continue;
+            }
+
+            $courseCategory = (string) ($cfg['course_category'] ?? 'course');
+            $keys = (array) ($cfg['keys'] ?? []);
+
+            foreach ($keys as $var) {
+                $var = (string) $var;
+                if ('' === $var) {
+                    continue;
+                }
+
+                // Only propagate helpers enabled at platform-level
+                if ('true' !== (string) api_get_setting($platformCategory.'.'.$var)) {
+                    continue;
+                }
+
+                $varEsc = Database::escape_string($var);
+                $catEsc = Database::escape_string($courseCategory);
+
+                // Insert only if missing (portable SQL)
+                $sql = "
+                INSERT INTO $table (c_id, title, variable, value, category)
+                SELECT $courseId, '', '$varEsc', 'true', '$catEsc'
+                WHERE NOT EXISTS (
+                    SELECT 1 FROM $table
+                    WHERE c_id = $courseId AND variable = '$varEsc'
+                    LIMIT 1
+                )
+            ";
+                Database::query($sql);
+            }
+        }
+    }
 }
diff --git a/public/main/inc/lib/chat.lib.php b/public/main/inc/lib/chat.lib.php
index bf23d2523c5..dde686ccc2b 100644
--- a/public/main/inc/lib/chat.lib.php
+++ b/public/main/inc/lib/chat.lib.php
@@ -96,14 +96,14 @@ public function getContacts(): string
         $html = (string) SocialManager::listMyFriendsBlock(api_get_user_id(), '', true);
 
         // Add AI Tutor contact when enabled (global chat).
-        if ('true' === api_get_setting('ai_helpers.tutor_chatbot')) {
+        if ('true' === api_get_setting('ai_helpers.tutor_chatbot') && api_get_course_int_id() > 0) {
             // Hide AI when user is in an exam (best effort).
             if (empty($_SESSION['is_in_a_test'])) {
                 $ai = ''
                     .'<div class="chd-ai-contact" data-user="'.self::USER_AI_TUTOR.'" data-name="AI Tutor" style="cursor:pointer; padding:10px; border-bottom:1px solid #eee;">'
                     .'<span style="margin-right:8px;">🤖</span>'
-                    .'<strong>AI Tutor</strong>'
-                    .'<span style="float:right; color:#2e7d32;">●</span>'
+                    .'<strong>'.get_lang('AI Tutor').'</strong>'
+                    .'<span style="float:right; color:#10B981;">●</span>'
                     .'</div>';
                 $html = $ai.$html;
             }
diff --git a/src/CoreBundle/AiProvider/AiTutorChatService.php b/src/CoreBundle/AiProvider/AiTutorChatService.php
index e2f18c59003..4e760764aee 100644
--- a/src/CoreBundle/AiProvider/AiTutorChatService.php
+++ b/src/CoreBundle/AiProvider/AiTutorChatService.php
@@ -453,4 +453,401 @@ private function generateAssistantReplyWithMeta(
 
         return $this->client->chatWithMeta($provider, $providerMessages, $options);
     }
+
+    public function sendTutorMessageForDockedChat(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider,
+        string $message,
+        string $uiLang
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+        $message = trim($message);
+
+        if ('' === $message) {
+            return ['id' => 0];
+        }
+
+        $conversation = $this->getOrCreateConversation($userId, $course, $session, $provider);
+
+        // Persist user message
+        $userMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('user')
+            ->setContent($message)
+        ;
+
+        $this->em->persist($userMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        // Generate assistant reply with meta (may update provider conversation id)
+        $result = $this->generateAssistantReplyWithMeta($provider, $course, $conversation);
+
+        $assistantText = trim((string) $result->text);
+        if ('' === $assistantText) {
+            $assistantText = 'I could not generate a response right now. Please try again.';
+        }
+
+        if (null !== $result->conversationId && '' !== trim($result->conversationId)) {
+            if ($conversation->getProviderConversationId() !== $result->conversationId) {
+                $conversation->setProviderConversationId($result->conversationId);
+            }
+        }
+
+        // Persist assistant message
+        $assistantMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('assistant')
+            ->setContent($assistantText)
+        ;
+
+        $this->em->persist($assistantMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        $assistantItem = $this->toDockedChatItem($assistantMsg, $userId, $provider);
+
+        return [
+            'id' => (int) $userMsg->getId(),
+            'assistant' => $assistantItem,
+            'mode' => 'course',
+        ];
+    }
+
+    /**
+     * Returns a page of messages for the docked UI (older messages loading).
+     * $visibleMessages is how many messages are already shown in the UI.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    public function getHistoryPageAsDockedItems(
+        int $userId,
+        Course $course,
+        string $provider,
+        int $visibleMessages,
+        int $pageSize = 30
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            return [];
+        }
+
+        $total = $this->conversationRepo->countMessages($conversation);
+        if ($total <= 0) {
+            return [];
+        }
+
+        $visible = max(0, $visibleMessages);
+        $remaining = max(0, $total - $visible);
+
+        if ($remaining <= 0) {
+            return [];
+        }
+
+        $limit = min($pageSize, $remaining);
+        $offset = max(0, $total - $visible - $limit);
+
+        $messages = $this->conversationRepo->findMessagesPage($conversation, $offset, $limit);
+
+        $items = [];
+        foreach ($messages as $m) {
+            $items[] = $this->toDockedChatItem($m, $userId, $provider);
+        }
+
+        return $items;
+    }
+
+    /**
+     * Returns incoming messages since a given ID for the docked UI.
+     * For the AI tutor, "incoming" means assistant messages only.
+     *
+     * @return array<int, array<string, mixed>>
+     */
+    public function getIncomingSinceAsDockedItems(
+        int $userId,
+        Course $course,
+        string $provider,
+        int $sinceId
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            return [];
+        }
+
+        $sinceId = max(0, $sinceId);
+        $messages = $this->conversationRepo->findAssistantMessagesSince($conversation, $sinceId);
+
+        $items = [];
+        foreach ($messages as $m) {
+            $items[] = $this->toDockedChatItem($m, $userId, $provider);
+        }
+
+        return $items;
+    }
+
+    /**
+     * Stores last-seen id in session (course + provider scoped).
+     */
+    public function ackTutorReadUpTo(
+        int $userId,
+        Course $course,
+        string $provider,
+        int $lastSeenId
+    ): int {
+        $provider = $this->normalizeProvider($provider);
+        $lastSeenId = max(0, $lastSeenId);
+
+        try {
+            $req = $this->requestStack->getCurrentRequest();
+            if (null === $req || !$req->hasSession()) {
+                return 0;
+            }
+
+            $key = $this->buildLastSeenSessionKey((int) $course->getId(), $provider);
+
+            $current = (int) $req->getSession()->get($key, 0);
+            if ($lastSeenId > $current) {
+                $req->getSession()->set($key, $lastSeenId);
+                return 1;
+            }
+
+            return 0;
+        } catch (Throwable) {
+            return 0;
+        }
+    }
+
+    private function buildLastSeenSessionKey(int $courseId, string $provider): string
+    {
+        return 'ai_tutor_last_seen_'.$courseId.'_'.$provider;
+    }
+
+    private function getLastSeenFromSession(int $courseId, string $provider): int
+    {
+        try {
+            $req = $this->requestStack->getCurrentRequest();
+            if (null === $req || !$req->hasSession()) {
+                return 0;
+            }
+
+            $key = $this->buildLastSeenSessionKey($courseId, $provider);
+            return (int) $req->getSession()->get($key, 0);
+        } catch (Throwable) {
+            return 0;
+        }
+    }
+
+    /**
+     * Converts an AiTutorMessage into the same shape used by classic chat JSON items.
+     *
+     * @return array<string, mixed>
+     */
+    private function toDockedChatItem(AiTutorMessage $m, int $meUserId, string $provider): array
+    {
+        $id = (int) $m->getId();
+        $role = (string) $m->getRole();
+        $createdAt = $m->getCreatedAt();
+        $ts = $createdAt ? (int) $createdAt->getTimestamp() : time();
+
+        $isAssistant = ('assistant' === $role);
+
+        $fromId = $isAssistant ? self::FRIEND_AI : $meUserId;
+        $toId = $isAssistant ? $meUserId : self::FRIEND_AI;
+
+        $courseId = (int) $m->getConversation()->getCourse()->getId();
+        $lastSeen = $this->getLastSeenFromSession($courseId, $provider);
+
+        // recd=1 means "read"; for assistant messages we mark as unread if above lastSeen.
+        $recd = 1;
+        if ($isAssistant) {
+            $recd = ($id <= $lastSeen) ? 1 : 0;
+        }
+
+        $content = (string) $m->getContent();
+        $safeHtml = $this->toSafeHtml($content);
+
+        return [
+            'id' => $id,
+            'message' => $safeHtml,
+            'date' => $ts,
+            'recd' => $recd,
+            'from_user_info' => $isAssistant ? $this->getAiTutorUserInfo() : api_get_user_info($meUserId, true),
+            'to_user_info' => $isAssistant ? api_get_user_info($meUserId, true) : $this->getAiTutorUserInfo(),
+            'from' => $fromId,
+            'to' => $toId,
+        ];
+    }
+
+    private function getAiTutorUserInfo(): array
+    {
+        return [
+            'id' => self::FRIEND_AI,
+            'user_id' => self::FRIEND_AI,
+            'complete_name' => 'AI Tutor',
+            'user_is_online_in_chat' => 1,
+            'user_is_online' => 1,
+            'online' => 1,
+            'avatar_small' => '',
+        ];
+    }
+
+    private function toSafeHtml(string $text): string
+    {
+        $text = trim($text);
+        if ('' === $text) {
+            return '';
+        }
+
+        // Keep line breaks readable in the UI, avoid raw HTML injection.
+        $escaped = htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
+        $html = nl2br($escaped);
+
+        return \Security::remove_XSS($html);
+    }
+
+    public function handleUserMessageForDock(
+        int $userId,
+        Course $course,
+        ?Session $session,
+        string $provider,
+        string $message
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+        $message = trim($message);
+
+        if ('' === $message) {
+            throw new \InvalidArgumentException('Empty message.');
+        }
+
+        $conversation = $this->getOrCreateConversation($userId, $course, $session, $provider);
+
+        // Persist user message
+        $userMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('user')
+            ->setContent($message)
+        ;
+
+        $this->em->persist($userMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        // Generate assistant reply (with meta to keep provider conversation id)
+        $result = $this->generateAssistantReplyWithMeta($provider, $course, $conversation);
+
+        $assistantText = trim((string) $result->text);
+        if ('' === $assistantText) {
+            $assistantText = 'I could not generate a response right now. Please try again.';
+        }
+
+        if (null !== $result->conversationId && '' !== trim($result->conversationId)) {
+            if ($conversation->getProviderConversationId() !== $result->conversationId) {
+                $conversation->setProviderConversationId($result->conversationId);
+            }
+        }
+
+        // Persist assistant message
+        $assistantMsg = (new AiTutorMessage())
+            ->setConversation($conversation)
+            ->setRole('assistant')
+            ->setContent($assistantText)
+        ;
+
+        $this->em->persist($assistantMsg);
+        $conversation->touchLastMessageAt();
+        $this->em->flush();
+
+        return [
+            'conversation' => $conversation,
+            'user' => $userMsg,
+            'assistant' => $assistantMsg,
+            'assistant_text' => $assistantText,
+        ];
+    }
+
+    /**
+     * Returns one "page" of messages for the dock, based on how many are already visible.
+     *
+     * @return AiTutorMessage[]
+     */
+    public function getDockMessagesPage(
+        int $userId,
+        Course $course,
+        string $provider,
+        int $visible,
+        int $pageSize = 20
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            return [];
+        }
+
+        $total = $this->conversationRepo->countMessages($conversation);
+        if ($total <= 0) {
+            return [];
+        }
+
+        $visible = max(0, $visible);
+        $pageSize = max(1, $pageSize);
+
+        // We want the slice just before the currently visible tail.
+        // Example: total=100, visible=20, pageSize=20 => return messages[60..79]
+        $end = max(0, $total - $visible);
+        $start = max(0, $end - $pageSize);
+        $len = max(0, $end - $start);
+
+        if ($len <= 0) {
+            return [];
+        }
+
+        return $this->conversationRepo->findMessagesSlice($conversation, $start, $len);
+    }
+
+    /**
+     * @return AiTutorMessage[]
+     */
+    public function getDockMessagesSince(
+        int $userId,
+        Course $course,
+        string $provider,
+        int $sinceId,
+        int $limit = 80
+    ): array {
+        $provider = $this->normalizeProvider($provider);
+
+        $conversation = $this->conversationRepo->findOneByUserCourseProvider(
+            $userId,
+            (int) $course->getId(),
+            $provider
+        );
+
+        if (null === $conversation) {
+            return [];
+        }
+
+        return $this->conversationRepo->findMessagesSinceId($conversation, max(0, $sinceId), $limit);
+    }
 }
diff --git a/src/CoreBundle/Controller/ChatController.php b/src/CoreBundle/Controller/ChatController.php
index e6db9cdaf0c..a0f4805d24b 100644
--- a/src/CoreBundle/Controller/ChatController.php
+++ b/src/CoreBundle/Controller/ChatController.php
@@ -8,11 +8,13 @@
 
 use Chamilo\CoreBundle\AiProvider\AiProviderFactory;
 use Chamilo\CoreBundle\AiProvider\AiTutorChatService;
+use Chamilo\CoreBundle\Entity\AiTutorMessage;
 use Chamilo\CoreBundle\Entity\Course;
 use Chamilo\CoreBundle\Helpers\CidReqHelper;
 use Chamilo\CoreBundle\Helpers\LanguageHelper;
 use Chamilo\CoreBundle\Helpers\UserHelper;
 use Chamilo\CoreBundle\Repository\ChatRepository;
+use Chamilo\CoreBundle\Settings\SettingsManager;
 use Chamilo\CoreBundle\Traits\ControllerTrait;
 use Chamilo\CoreBundle\Traits\CourseControllerTrait;
 use Chamilo\CoreBundle\Traits\ResourceControllerTrait;
@@ -46,6 +48,7 @@ final class ChatController extends AbstractController
     public function __construct(
         private readonly CidReqHelper $cidReqHelper,
         private readonly UserHelper $userHelper,
+        private readonly SettingsManager $settingsManager
     ) {}
 
     #[Route(path: '/resources/chat/', name: 'chamilo_core_chat_home', options: ['expose' => true])]
@@ -78,7 +81,7 @@ public function index(
         $docsRepo->ensureChatSystemFolder($course, $session);
 
         // AI tab enable flag (safe default: off unless enabled).
-        $aiEnabled = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+        $aiEnabled = ('true' === $this->settingsManager->getSetting('ai_helpers.tutor_chatbot'));
 
         $courseSettingsManager->setCourse($course);
         $aiDefaultProvider = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
@@ -88,7 +91,7 @@ public function index(
         $groupId = (int) ($group?->getIid() ?? 0);
 
         return $this->render('@ChamiloCore/Chat/chat.html.twig', [
-            'restrict_to_coach' => ('true' === api_get_setting('chat.course_chat_restrict_to_coach')),
+            'restrict_to_coach' => ('true' === $this->settingsManager->getSetting('chat.course_chat_restrict_to_coach')),
             'user' => api_get_user_info($me, true),
             'emoji_smile' => '<span>&#128522;</span>',
             'course_url_params' => api_get_cidreq(),
@@ -274,7 +277,7 @@ public function globalHome(): Response
             throw $this->createAccessDeniedException('User is not authenticated.');
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return $this->redirectToRoute('homepage');
         }
 
@@ -298,7 +301,7 @@ public function globalStart(): JsonResponse
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -328,7 +331,7 @@ public function globalContacts(): Response
             return new Response('', 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new Response('', 403);
         }
 
@@ -346,7 +349,7 @@ public function globalHeartbeat(Request $req): JsonResponse
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -409,20 +412,84 @@ public function globalHeartbeat(Request $req): JsonResponse
         options: ['expose' => true],
         methods: ['GET']
     )]
-    public function globalHistorySince(Request $req): JsonResponse
-    {
+    public function globalHistorySince(
+        Request $req,
+        AiTutorChatService $aiTutorChatService,
+        AiProviderFactory $aiProviderFactory,
+        SettingsCourseManager $courseSettingsManager,
+        ManagerRegistry $doctrine
+    ): JsonResponse {
         $me = $this->getCurrentUserIdOrNull();
         if (null === $me) {
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $peerId = (int) $req->query->get('user_id', 0);
         $sinceId = (int) $req->query->get('since_id', 0);
 
+        if ($peerId === AiTutorChatService::FRIEND_AI) {
+            $course = $this->resolveCourseFromRequest($req, $doctrine);
+            if (null === $course) {
+                return new JsonResponse([]);
+            }
+
+            $courseSettingsManager->setCourse($course);
+            $courseSettingValue = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+            if (!$this->isCourseTutorEnabled($courseSettingValue)) {
+                return new JsonResponse([]);
+            }
+
+            $requestedProvider = trim((string) $req->query->get('ai_provider', ''));
+            $providerKey = $this->resolveTextProviderKey($requestedProvider ?: $courseSettingValue, $aiProviderFactory);
+            if (null === $providerKey) {
+                return new JsonResponse([]);
+            }
+
+            $msgs = $aiTutorChatService->getDockMessagesSince((int) $me, $course, $providerKey, max(0, $sinceId), 80);
+
+            $out = [];
+            foreach ($msgs as $m) {
+                $role = (string) $m->getRole();
+                $fromId = ('user' === $role) ? (int) $me : AiTutorChatService::FRIEND_AI;
+
+                $out[] = [
+                    'id' => (int) $m->getId(),
+                    'message' => \Security::remove_XSS(nl2br(htmlspecialchars((string) $m->getContent(), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'))),
+                    'date' => (int) $m->getCreatedAt()->getTimestamp(),
+                    'recd' => 2,
+                    'from_user_info' => ('user' === $role)
+                        ? api_get_user_info((int) $me, true)
+                        : [
+                            'id' => AiTutorChatService::FRIEND_AI,
+                            'user_id' => AiTutorChatService::FRIEND_AI,
+                            'complete_name' => 'AI Tutor',
+                            'user_is_online_in_chat' => 1,
+                            'user_is_online' => 1,
+                            'online' => 1,
+                            'avatar_small' => '',
+                        ],
+                    'to_user_info' => ('user' === $role)
+                        ? [
+                            'id' => AiTutorChatService::FRIEND_AI,
+                            'user_id' => AiTutorChatService::FRIEND_AI,
+                            'complete_name' => 'AI Tutor',
+                            'user_is_online_in_chat' => 1,
+                            'user_is_online' => 1,
+                            'online' => 1,
+                            'avatar_small' => '',
+                        ]
+                        : api_get_user_info((int) $me, true),
+                    'f' => $fromId,
+                ];
+            }
+
+            return new JsonResponse($out);
+        }
+
         if ($peerId <= 0) {
             return new JsonResponse([]);
         }
@@ -448,14 +515,15 @@ public function globalSend(
         LanguageHelper $languageHelper,
         AiProviderFactory $aiProviderFactory,
         ChatRepository $chatRepository,
-        ManagerRegistry $doctrine
+        ManagerRegistry $doctrine,
+        SettingsCourseManager $courseSettingsManager
     ): JsonResponse {
         $me = $this->getCurrentUserIdOrNull();
         if (null === $me) {
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -469,7 +537,7 @@ public function globalSend(
                 return new JsonResponse(['error' => 'ai_disabled_in_exam'], 403);
             }
 
-            $aiEnabledSetting = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+            $aiEnabledSetting = ('true' === $this->settingsManager->getSetting('ai_helpers.tutor_chatbot'));
             if (!$aiEnabledSetting) {
                 return new JsonResponse([
                     'error' => 'ai_disabled',
@@ -482,38 +550,51 @@ public function globalSend(
                 return new JsonResponse(['id' => 0]);
             }
 
-            // Course context is OPTIONAL now.
+            // AI tutor must be available only inside a course.
             $course = $this->resolveCourseFromRequest($req, $doctrine);
+            if (null === $course) {
+                return new JsonResponse([
+                    'error' => 'ai_requires_course_context',
+                    'message' => 'AI tutor is only available inside a course.',
+                ], 403);
+            }
+
+            // Check course setting (teacher can disable it per course).
+            $courseSettingsManager->setCourse($course);
+            $courseSettingValue = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+
+            if (!$this->isCourseTutorEnabled($courseSettingValue)) {
+                return new JsonResponse([
+                    'error' => 'disabled_by_course_setting',
+                    'message' => 'AI tutor is disabled for this course.',
+                ], 403);
+            }
 
             $uiLang = $languageHelper->getInterfaceIso();
-            $mode = (null !== $course) ? 'course' : 'global';
 
-            $courseTitle = 'Global';
+            // Build course context
+            $courseTitle = (string) $course->getTitle();
             $courseLang = $uiLang ?: 'en';
 
-            if (null !== $course) {
-                $courseTitle = (string) $course->getTitle();
-
-                $tmpLang = '';
-                if (method_exists($course, 'getCourseLanguage')) {
-                    $tmpLang = (string) ($course->getCourseLanguage() ?? '');
-                }
-                if ('' === $tmpLang && method_exists($course, 'getLanguage')) {
-                    $tmpLang = (string) ($course->getLanguage() ?? '');
-                }
-                if ('' !== $tmpLang) {
-                    $courseLang = $tmpLang;
-                }
+            $tmpLang = '';
+            if (method_exists($course, 'getCourseLanguage')) {
+                $tmpLang = (string) ($course->getCourseLanguage() ?? '');
+            }
+            if ('' === $tmpLang && method_exists($course, 'getLanguage')) {
+                $tmpLang = (string) ($course->getLanguage() ?? '');
+            }
+            if ('' !== $tmpLang) {
+                $courseLang = $tmpLang;
             }
 
-            // Store context + strict system prompt in session for the AI layer.
             $ctx = [
-                'mode' => $mode,
-                'course_id' => (int) ($course?->getId() ?? 0),
+                'mode' => 'course',
+                'course_id' => (int) ($course->getId() ?? 0),
                 'title' => $courseTitle,
                 'lang' => $courseLang ?: 'en',
             ];
 
+            // Store context + strict system prompt in session for the AI layer.
             try {
                 if ($req->hasSession()) {
                     $req->getSession()->set('ai_tutor_context', $ctx);
@@ -602,7 +683,7 @@ public function globalSend(
                 AiTutorChatService::FRIEND_AI,
                 (int) $me,
                 $assistantSanitized,
-                0,
+                1,
                 (new DateTimeImmutable('now', new DateTimeZone('UTC')))->format('Y-m-d H:i:s')
             );
 
@@ -612,7 +693,7 @@ public function globalSend(
                     'id' => (int) $assistantId,
                     'message' => \Security::remove_XSS($assistantSanitized),
                     'date' => $nowTs,
-                    'recd' => 0,
+                    'recd' => 1,
                     'from_user_info' => [
                         'id' => AiTutorChatService::FRIEND_AI,
                         'user_id' => AiTutorChatService::FRIEND_AI,
@@ -624,7 +705,7 @@ public function globalSend(
                     ],
                     'to_user_info' => api_get_user_info((int) $me, true),
                 ],
-                'mode' => $mode,
+                'mode' => 'course',
             ]);
         }
 
@@ -651,6 +732,81 @@ public function globalSend(
         return new JsonResponse($ret ?? ['id' => 0]);
     }
 
+    /**
+     * Course setting parser for tutor enablement.
+     * Empty value defaults to enabled (global setting already checked).
+     */
+    private function isCourseTutorEnabled(string $value): bool
+    {
+        $v = trim($value);
+        if ('' === $v) {
+            return true;
+        }
+
+        return 1 === preg_match('/^(1|true|on|yes)$/i', $v);
+    }
+
+    #[Route(
+        path: '/account/chat/api/tutor/reset',
+        name: 'chamilo_core_chat_api_tutor_reset',
+        options: ['expose' => true],
+        methods: ['POST']
+    )]
+    public function globalTutorReset(
+        Request $req,
+        AiTutorChatService $aiTutorChatService,
+        AiProviderFactory $aiProviderFactory,
+        SettingsCourseManager $courseSettingsManager,
+        ManagerRegistry $doctrine
+    ): JsonResponse {
+        $me = $this->getCurrentUserIdOrNull();
+        if (null === $me) {
+            return new JsonResponse(['error' => 'unauthorized'], 401);
+        }
+
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
+            return new JsonResponse(['error' => 'disabled'], 403);
+        }
+
+        $course = $this->resolveCourseFromRequest($req, $doctrine);
+        if (null === $course) {
+            return new JsonResponse(['error' => 'not_in_course'], 403);
+        }
+
+        $courseSettingsManager->setCourse($course);
+        $courseSettingValue = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+        if (!$this->isCourseTutorEnabled($courseSettingValue)) {
+            return new JsonResponse(['error' => 'disabled_by_course_setting'], 403);
+        }
+
+        $requestedProvider = trim((string) $req->request->get('ai_provider', ''));
+        $providerKey = $this->resolveTextProviderKey($requestedProvider ?: $courseSettingValue, $aiProviderFactory);
+
+        if (null === $providerKey) {
+            return new JsonResponse(['error' => 'ai_not_configured'], 503);
+        }
+
+        $aiTutorChatService->resetConversation((int) $me, $course, null, $providerKey);
+
+        return new JsonResponse(['ok' => true]);
+    }
+
+    /**
+     * Try to resolve the course language from entity data; fallback to UI language.
+     */
+    private function resolveCourseLanguage(Course $course): string
+    {
+        $tmpLang = '';
+        if (method_exists($course, 'getCourseLanguage')) {
+            $tmpLang = (string) ($course->getCourseLanguage() ?? '');
+        }
+        if ('' === $tmpLang && method_exists($course, 'getLanguage')) {
+            $tmpLang = (string) ($course->getLanguage() ?? '');
+        }
+
+        return $tmpLang;
+    }
+
     #[Route(path: '/account/chat/api/status', name: 'chamilo_core_chat_api_status', options: ['expose' => true], methods: ['POST'])]
     public function globalStatus(Request $req): JsonResponse
     {
@@ -659,7 +815,7 @@ public function globalStatus(Request $req): JsonResponse
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -670,22 +826,86 @@ public function globalStatus(Request $req): JsonResponse
 
         return new JsonResponse(['ok' => true, 'status' => $status]);
     }
-
     #[Route(path: '/account/chat/api/history', name: 'chamilo_core_chat_api_history', options: ['expose' => true], methods: ['GET'])]
-    public function globalHistory(Request $req): JsonResponse
-    {
+    public function globalHistory(
+        Request $req,
+        AiTutorChatService $aiTutorChatService,
+        AiProviderFactory $aiProviderFactory,
+        SettingsCourseManager $courseSettingsManager,
+        ManagerRegistry $doctrine
+    ): JsonResponse {
         $me = $this->getCurrentUserIdOrNull();
         if (null === $me) {
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $peerId = (int) $req->query->get('user_id', 0);
         $visible = (int) $req->query->get('visible_messages', 0);
 
+        if ($peerId === AiTutorChatService::FRIEND_AI) {
+            // Course-only AI tutor history
+            $course = $this->resolveCourseFromRequest($req, $doctrine);
+            if (null === $course) {
+                return new JsonResponse([]);
+            }
+
+            $courseSettingsManager->setCourse($course);
+            $courseSettingValue = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+            if (!$this->isCourseTutorEnabled($courseSettingValue)) {
+                return new JsonResponse([]);
+            }
+
+            $requestedProvider = trim((string) $req->query->get('ai_provider', ''));
+            $providerKey = $this->resolveTextProviderKey($requestedProvider ?: $courseSettingValue, $aiProviderFactory);
+            if (null === $providerKey) {
+                return new JsonResponse([]);
+            }
+
+            $msgs = $aiTutorChatService->getDockMessagesPage((int) $me, $course, $providerKey, max(0, $visible), 20);
+
+            $out = [];
+            foreach ($msgs as $m) {
+                $role = (string) $m->getRole();
+                $fromId = ('user' === $role) ? (int) $me : AiTutorChatService::FRIEND_AI;
+
+                $out[] = [
+                    'id' => (int) $m->getId(),
+                    'message' => \Security::remove_XSS(nl2br(htmlspecialchars((string) $m->getContent(), ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8'))),
+                    'date' => (int) $m->getCreatedAt()->getTimestamp(),
+                    'recd' => 2,
+                    'from_user_info' => ('user' === $role)
+                        ? api_get_user_info((int) $me, true)
+                        : [
+                            'id' => AiTutorChatService::FRIEND_AI,
+                            'user_id' => AiTutorChatService::FRIEND_AI,
+                            'complete_name' => 'AI Tutor',
+                            'user_is_online_in_chat' => 1,
+                            'user_is_online' => 1,
+                            'online' => 1,
+                            'avatar_small' => '',
+                        ],
+                    'to_user_info' => ('user' === $role)
+                        ? [
+                            'id' => AiTutorChatService::FRIEND_AI,
+                            'user_id' => AiTutorChatService::FRIEND_AI,
+                            'complete_name' => 'AI Tutor',
+                            'user_is_online_in_chat' => 1,
+                            'user_is_online' => 1,
+                            'online' => 1,
+                            'avatar_small' => '',
+                        ]
+                        : api_get_user_info((int) $me, true),
+                    'f' => $fromId,
+                ];
+            }
+
+            return new JsonResponse($out);
+        }
+
         if ($peerId <= 0) {
             return new JsonResponse([]);
         }
@@ -710,7 +930,7 @@ public function globalPreview(Request $req): Response
             return new Response('', 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new Response('', 403);
         }
 
@@ -727,7 +947,7 @@ public function globalPresence(Request $req): JsonResponse
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -740,14 +960,17 @@ public function globalPresence(Request $req): JsonResponse
     }
 
     #[Route(path: '/account/chat/api/ack', name: 'chamilo_core_chat_api_ack', options: ['expose' => true], methods: ['POST'])]
-    public function globalAck(Request $req): JsonResponse
-    {
+    public function globalAck(
+        Request $req,
+        ManagerRegistry $doctrine,
+        AiTutorChatService $aiTutorChatService
+    ): JsonResponse {
         $me = $this->getCurrentUserIdOrNull();
         if (null === $me) {
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
@@ -758,16 +981,24 @@ public function globalAck(Request $req): JsonResponse
             return new JsonResponse(['ok' => false, 'error' => 'bad_params'], 400);
         }
 
-        // AI tutor thread is not a real peer in classic chat ack. No-op.
+        // AI Tutor ack uses session last-seen (course-scoped)
         if (AiTutorChatService::FRIEND_AI === $peerId) {
-            return new JsonResponse(['ok' => true, 'updated' => 0]);
+            $course = $this->resolveCourseFromRequest($req, $doctrine);
+            if (null === $course) {
+                return new JsonResponse(['ok' => false, 'error' => 'ai_requires_course'], 403);
+            }
+
+            $provider = trim((string) $req->request->get('ai_provider', ''));
+            $updated = $aiTutorChatService->ackTutorReadUpTo((int) $me, $course, $provider, $lastSeenId);
+
+            return new JsonResponse(['ok' => true, 'updated' => $updated]);
         }
 
         if ($peerId <= 0) {
             return new JsonResponse(['ok' => false, 'error' => 'bad_params'], 400);
         }
 
-        $chat = new Chat();
+        $chat = new \Chat();
 
         try {
             $n = $chat->ackReadUpTo($peerId, (int) $me, $lastSeenId);
@@ -779,6 +1010,7 @@ public function globalAck(Request $req): JsonResponse
             return new JsonResponse(['ok' => false, 'error' => $e->getMessage()], 500);
         }
     }
+
     #[Route(
         path: '/account/chat/api/tutor_context',
         name: 'chamilo_core_chat_api_tutor_context',
@@ -787,66 +1019,109 @@ public function globalAck(Request $req): JsonResponse
     )]
     public function globalTutorContext(
         Request $req,
-        AiProviderFactory $aiProviderFactory
+        AiProviderFactory $aiProviderFactory,
+        SettingsCourseManager $courseSettingsManager,
+        ManagerRegistry $doctrine
     ): JsonResponse {
         $me = $this->getCurrentUserIdOrNull();
         if (null === $me) {
             return new JsonResponse(['error' => 'unauthorized'], 401);
         }
 
-        if ('true' !== api_get_setting('chat.allow_global_chat')) {
+        if ('true' !== $this->settingsManager->getSetting('chat.allow_global_chat')) {
             return new JsonResponse(['error' => 'disabled'], 403);
         }
 
         $inTest = !empty($_SESSION['is_in_a_test']);
 
-        // Allow showing AI Tutor globally. Also verify at least one text provider exists.
-        $aiEnabledSetting = ('true' === api_get_setting('ai_helpers.tutor_chatbot'));
+        $aiEnabledSetting = ('true' === $this->settingsManager->getSetting('ai_helpers.tutor_chatbot'));
         $providers = $aiProviderFactory->getProvidersForType('text');
         $hasTextProvider = !empty($providers);
 
-        $enabled = $aiEnabledSetting && $hasTextProvider;
+        // Course context is REQUIRED for the tutor.
+        $course = $this->resolveCourseFromRequest($req, $doctrine);
 
-        // Course context depends on cid/cidReq if present.
-        $course = $this->cidReqHelper->getDoctrineCourseEntity();
+        if (!$aiEnabledSetting) {
+            return new JsonResponse([
+                'enabled' => false,
+                'in_test' => $inTest,
+                'course' => null,
+                'mode' => null,
+                'provider' => null,
+                'reason' => 'disabled_by_setting',
+            ]);
+        }
 
-        $coursePayload = null;
-        $ctx = [
-            'mode' => null,
-            'course_id' => 0,
-            'title' => 'Global',
-            'lang' => 'en',
-        ];
+        if (!$hasTextProvider) {
+            return new JsonResponse([
+                'enabled' => false,
+                'in_test' => $inTest,
+                'course' => null,
+                'mode' => null,
+                'provider' => null,
+                'reason' => 'no_text_provider',
+            ]);
+        }
 
-        if (null !== $course) {
-            $courseLang = '';
-            if (method_exists($course, 'getCourseLanguage')) {
-                $courseLang = (string) ($course->getCourseLanguage() ?? '');
-            }
-            if ('' === $courseLang && method_exists($course, 'getLanguage')) {
-                $courseLang = (string) ($course->getLanguage() ?? '');
-            }
-            if ('' === $courseLang) {
-                $courseLang = 'en';
-            }
+        if (null === $course) {
+            return new JsonResponse([
+                'enabled' => false,
+                'in_test' => $inTest,
+                'course' => null,
+                'mode' => null,
+                'provider' => null,
+                'reason' => 'not_in_course',
+            ]);
+        }
 
-            $ctx = [
+        // Check course setting (teacher can disable it per course)
+        $courseSettingsManager->setCourse($course);
+        $courseSettingValue = (string) $courseSettingsManager->getCourseSettingValue('tutor_chatbot');
+
+        $courseTutorEnabled = $this->isCourseTutorEnabled($courseSettingValue);
+        if (!$courseTutorEnabled) {
+            return new JsonResponse([
+                'enabled' => false,
+                'in_test' => $inTest,
+                'course' => [
+                    'id' => (int) $course->getId(),
+                    'title' => (string) $course->getTitle(),
+                    'language' => $this->resolveCourseLanguage($course) ?: 'en',
+                ],
                 'mode' => 'course',
-                'course_id' => (int) $course->getId(),
-                'title' => (string) $course->getTitle(),
-                'lang' => $courseLang,
-            ];
+                'provider' => null,
+                'reason' => 'disabled_by_course_setting',
+            ]);
+        }
 
-            $coursePayload = [
-                'id' => $ctx['course_id'],
-                'title' => $ctx['title'],
-                'language' => $ctx['lang'],
-            ];
-        } else {
-            $ctx['mode'] = 'global';
+        if ($inTest) {
+            return new JsonResponse([
+                'enabled' => false,
+                'in_test' => true,
+                'course' => [
+                    'id' => (int) $course->getId(),
+                    'title' => (string) $course->getTitle(),
+                    'language' => $this->resolveCourseLanguage($course) ?: 'en',
+                ],
+                'mode' => 'course',
+                'provider' => null,
+                'reason' => 'disabled_in_exam',
+            ]);
         }
 
-        // Store context so the AI service can build prompts consistently.
+        // Use course setting as provider if possible, fallback to first available provider.
+        $providerKey = $this->resolveTextProviderKey($courseSettingValue, $aiProviderFactory);
+        if (null === $providerKey) {
+            $providerKey = $providers[0] ?? null;
+        }
+
+        $ctx = [
+            'mode' => 'course',
+            'course_id' => (int) $course->getId(),
+            'title' => (string) $course->getTitle(),
+            'lang' => $this->resolveCourseLanguage($course) ?: 'en',
+        ];
+
         try {
             if ($req->hasSession()) {
                 $req->getSession()->set('ai_tutor_context', $ctx);
@@ -857,11 +1132,16 @@ public function globalTutorContext(
         }
 
         return new JsonResponse([
-            'enabled' => $enabled,
-            'in_test' => $inTest,
-            'course' => $coursePayload,
-            'mode' => $ctx['mode'],
-            'reason' => $enabled ? null : (!$aiEnabledSetting ? 'disabled_by_setting' : 'no_text_provider'),
+            'enabled' => true,
+            'in_test' => false,
+            'course' => [
+                'id' => $ctx['course_id'],
+                'title' => $ctx['title'],
+                'language' => $ctx['lang'],
+            ],
+            'mode' => 'course',
+            'provider' => $providerKey,
+            'reason' => null,
         ]);
     }
 
@@ -967,8 +1247,11 @@ private function buildPresenceMap(array $ids): array
      * - If requested provider is valid for "text", use it.
      * - Otherwise fallback to the first available "text" provider (config order).
      */
-    private function resolveTextProviderKey(string $requestedProvider, AiProviderFactory $aiProviderFactory): ?string
-    {
+    private function resolveTextProviderKey(
+        string $requestedProvider,
+        AiProviderFactory $aiProviderFactory,
+        ?string $defaultProvider = null
+    ): ?string {
         $available = $aiProviderFactory->getProvidersForType('text');
 
         if (empty($available)) {
@@ -979,7 +1262,10 @@ private function resolveTextProviderKey(string $requestedProvider, AiProviderFac
             return $requestedProvider;
         }
 
-        // Fallback: first provider configured for text in ai_helpers.ai_providers JSON.
+        if (null !== $defaultProvider && '' !== trim($defaultProvider) && in_array($defaultProvider, $available, true)) {
+            return $defaultProvider;
+        }
+
         return $available[0] ?? null;
     }
 
@@ -1019,6 +1305,14 @@ private function resolveCourseFromRequest(Request $req, ManagerRegistry $doctrin
             ?? 0
         );
 
+        // Fallback: try Referer like /course/{id}/...
+        if ($cid <= 0) {
+            $ref = (string) $req->headers->get('referer', '');
+            if ('' !== $ref && preg_match('~/course/(\d+)(/|$)~', $ref, $m)) {
+                $cid = (int) ($m[1] ?? 0);
+            }
+        }
+
         if ($cid <= 0) {
             return null;
         }
diff --git a/src/CoreBundle/Repository/AiTutorConversationRepository.php b/src/CoreBundle/Repository/AiTutorConversationRepository.php
index 6fd3ccefc61..22862fcca17 100644
--- a/src/CoreBundle/Repository/AiTutorConversationRepository.php
+++ b/src/CoreBundle/Repository/AiTutorConversationRepository.php
@@ -11,7 +11,7 @@
 use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
 use Doctrine\Persistence\ManagerRegistry;
 
-class AiTutorConversationRepository extends ServiceEntityRepository
+final class AiTutorConversationRepository extends ServiceEntityRepository
 {
     public function __construct(ManagerRegistry $registry)
     {
@@ -50,6 +50,54 @@ public function findMessages(AiTutorConversation $conversation, int $limit = 0):
         return $qb->getQuery()->getResult();
     }
 
+    /**
+     * @return AiTutorMessage[]
+     */
+    public function findMessagesSlice(AiTutorConversation $conversation, int $offset, int $limit): array
+    {
+        return $this->getEntityManager()->createQueryBuilder()
+            ->select('m')
+            ->from(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->setParameter('c', $conversation)
+            ->orderBy('m.createdAt', 'ASC')
+            ->setFirstResult(max(0, $offset))
+            ->setMaxResults(max(0, $limit))
+            ->getQuery()
+            ->getResult();
+    }
+
+    /**
+     * @return AiTutorMessage[]
+     */
+    public function findMessagesSinceId(AiTutorConversation $conversation, int $sinceId, int $limit = 80): array
+    {
+        return $this->getEntityManager()->createQueryBuilder()
+            ->select('m')
+            ->from(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->andWhere('m.id > :sid')
+            ->setParameter('c', $conversation)
+            ->setParameter('sid', $sinceId)
+            ->orderBy('m.id', 'ASC')
+            ->setMaxResults(max(1, $limit))
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function countMessages(AiTutorConversation $conversation): int
+    {
+        $n = $this->getEntityManager()->createQueryBuilder()
+            ->select('COUNT(m.id)')
+            ->from(AiTutorMessage::class, 'm')
+            ->andWhere('m.conversation = :c')
+            ->setParameter('c', $conversation)
+            ->getQuery()
+            ->getSingleScalarResult();
+
+        return (int) ($n ?? 0);
+    }
+
     public function clearMessages(AiTutorConversation $conversation): int
     {
         return (int) $this->getEntityManager()
diff --git a/src/CoreBundle/Settings/SettingsManager.php b/src/CoreBundle/Settings/SettingsManager.php
index ce668c27368..4cfca013777 100644
--- a/src/CoreBundle/Settings/SettingsManager.php
+++ b/src/CoreBundle/Settings/SettingsManager.php
@@ -11,6 +11,7 @@
 use Chamilo\CoreBundle\Entity\SettingsCurrent;
 use Chamilo\CoreBundle\Helpers\SettingsManagerHelper;
 use Chamilo\CoreBundle\Search\SearchEngineFieldSynchronizer;
+use Chamilo\CourseBundle\Entity\CCourseSetting;
 use Doctrine\ORM\EntityManager;
 use Doctrine\ORM\EntityRepository;
 use InvalidArgumentException;
@@ -60,6 +61,29 @@ class SettingsManager implements SettingsManagerInterface
 
     private ?AccessUrl $mainUrlCache = null;
 
+    /**
+     * Platform -> Course settings propagation map.
+     * Add more categories/variables here to scale to other features.
+     *
+     * IMPORTANT:
+     * - Values are stored as strings in legacy course settings ("true"/"false" is common).
+     */
+    private const COURSE_SETTINGS_PROPAGATION = [
+        'ai_helpers' => [
+            // Only propagate "feature flags" (not JSON providers, etc.)
+            'learning_path_generator',
+            'exercise_generator',
+            'open_answers_grader',
+            'tutor_chatbot',
+            'task_grader',
+            'content_analyser',
+            'image_generator',
+            'glossary_terms_generator',
+            'video_generator',
+            'course_analyser',
+        ],
+    ];
+
     public function __construct(
         ServiceRegistryInterface $schemaRegistry,
         EntityManager $manager,
@@ -396,6 +420,7 @@ public function update(SettingsInterface $settings): void
 
         $this->manager->flush();
         $this->clearSessionSchemaCache();
+        $this->propagatePlatformSettingsToCoursesIfNeeded($simpleCategoryName, $parameters);
     }
 
     /**
@@ -483,6 +508,7 @@ public function save(SettingsInterface $settings): void
 
         $this->manager->flush();
         $this->clearSessionSchemaCache();
+        $this->propagatePlatformSettingsToCoursesIfNeeded($simpleCategoryName, $parameters);
     }
 
     /**
@@ -1836,4 +1862,131 @@ private function getCategoryVariants(string $category): array
 
         return array_values(array_unique($variants));
     }
+
+    /**
+     * Propagate selected platform settings to course settings (c_course_setting).
+     * This is designed to scale: add categories/variables to COURSE_SETTINGS_PROPAGATION.
+     *
+     * @param string $category   Simple category name (e.g. "ai_helpers")
+     * @param array  $parameters Persisted platform parameters (already stringified)
+     */
+    private function propagatePlatformSettingsToCoursesIfNeeded(string $category, array $parameters): void
+    {
+        if (!isset(self::COURSE_SETTINGS_PROPAGATION[$category])) {
+            return;
+        }
+
+        // Example gate for AI helpers: if the master switch is off, do nothing.
+        if ('ai_helpers' === $category && ('true' !== (string) ($parameters['enable_ai_helpers'] ?? 'false'))) {
+            return;
+        }
+
+        $vars = self::COURSE_SETTINGS_PROPAGATION[$category];
+
+        // Build list of course settings to enable based on platform values.
+        // Strategy: enable only those set to true at platform-level.
+        $varToValue = [];
+        foreach ($vars as $var) {
+            if ('true' === (string) ($parameters[$var] ?? 'false')) {
+                $varToValue[$var] = 'true';
+            }
+        }
+
+        if (empty($varToValue)) {
+            return;
+        }
+
+        // By default: only insert missing rows, do NOT overwrite existing course choices.
+        // If you want to force overwrite to true across all courses, set $force = true.
+        $force = false;
+
+        $this->upsertCourseSettingsForAllCourses($category, $varToValue, $force);
+    }
+
+    /**
+     * Upsert course settings for all courses in batches.
+     *
+     * @param array<string,string> $varToValue variable => value
+     */
+    private function upsertCourseSettingsForAllCourses(string $category, array $varToValue, bool $force = false): void
+    {
+        // Fetch all course IDs (batch-friendly)
+        $courseIdRows = $this->manager->createQueryBuilder()
+            ->select('c.id')
+            ->from(Course::class, 'c')
+            ->getQuery()
+            ->getScalarResult()
+        ;
+
+        $courseIds = array_map(
+            static fn (array $r): int => (int) ($r['id'] ?? 0),
+            $courseIdRows
+        );
+        $courseIds = array_values(array_filter($courseIds, static fn (int $id): bool => $id > 0));
+
+        if (empty($courseIds)) {
+            return;
+        }
+
+        $vars = array_keys($varToValue);
+        $batchSize = 300;
+
+        for ($offset = 0; $offset < count($courseIds); $offset += $batchSize) {
+            $chunk = array_slice($courseIds, $offset, $batchSize);
+
+            // Load existing settings for this chunk (IMPORTANT: filter by category)
+            $existing = $this->manager->createQueryBuilder()
+                ->select('cs')
+                ->from(CCourseSetting::class, 'cs')
+                ->where('cs.cId IN (:cids)')
+                ->andWhere('cs.variable IN (:vars)')
+                ->andWhere('cs.category = :cat')
+                ->setParameter('cids', $chunk)
+                ->setParameter('vars', $vars)
+                ->setParameter('cat', $category)
+                ->getQuery()
+                ->getResult()
+            ;
+
+            /** @var array<int, array<string, CCourseSetting>> $byCourse */
+            $byCourse = [];
+            foreach ($existing as $row) {
+                if (!$row instanceof CCourseSetting) {
+                    continue;
+                }
+                $cId = (int) $row->getCId();
+                $var = (string) $row->getVariable();
+                $byCourse[$cId][$var] = $row;
+            }
+
+            foreach ($chunk as $cId) {
+                foreach ($varToValue as $var => $value) {
+                    $row = $byCourse[$cId][$var] ?? null;
+
+                    if ($row instanceof CCourseSetting) {
+                        if ($force && (string) $row->getValue() !== $value) {
+                            $row->setValue($value);
+                            $this->manager->persist($row);
+                        }
+                        continue;
+                    }
+
+                    // Insert missing row (category standardized)
+                    $new = new CCourseSetting();
+                    $new
+                        ->setCId($cId)
+                        ->setVariable($var)
+                        ->setTitle($var)
+                        ->setCategory($category) // <-- here
+                        ->setValue($value)
+                    ;
+
+                    $this->manager->persist($new);
+                }
+            }
+
+            $this->manager->flush();
+            $this->manager->clear();
+        }
+    }
 }

From acff39577cba08294fdb3121c09f6ff1e0da9cac Mon Sep 17 00:00:00 2001
From: Christian Beeznest <christian.fasanando@beeznest.com>
Date: Thu, 15 Jan 2026 23:14:14 -0500
Subject: [PATCH 3/3] Chat: Minor: cleaning code with phpcs-fix - refs #7306

---
 .../AiChatCompletionClientInterface.php       |   4 +-
 .../AiProvider/AiImageProviderInterface.php   |  22 +--
 .../AiProvider/AiProviderFactory.php          |  12 +-
 .../AiProvider/AiTutorChatService.php         |  29 ++--
 .../AiProvider/AiVideoProviderInterface.php   |   8 +-
 .../AiProvider/DeepSeekProvider.php           |   3 +
 .../DefaultAiChatCompletionClient.php         |   7 +-
 src/CoreBundle/AiProvider/GeminiProvider.php  |   3 +
 src/CoreBundle/AiProvider/GrokProvider.php    |  12 +-
 src/CoreBundle/AiProvider/MistralProvider.php |   3 +
 src/CoreBundle/AiProvider/OpenAiProvider.php  | 137 +++++++++++-------
 src/CoreBundle/Settings/SettingsManager.php   |  10 +-
 12 files changed, 151 insertions(+), 99 deletions(-)

diff --git a/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php b/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
index d87eb00d2f6..15d1052eada 100644
--- a/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
+++ b/src/CoreBundle/AiProvider/AiChatCompletionClientInterface.php
@@ -10,7 +10,7 @@ interface AiChatCompletionClientInterface
 {
     /**
      * @param array<int, array{role:string,content:string}> $messages
-     * @param array<string,mixed> $options
+     * @param array<string,mixed>                           $options
      */
     public function chat(string $provider, array $messages, array $options = []): string;
 
@@ -18,7 +18,7 @@ public function chat(string $provider, array $messages, array $options = []): st
      * Same as chat() but may also return a provider conversation id (previous_id, conversation_id, etc).
      *
      * @param array<int, array{role:string,content:string}> $messages
-     * @param array<string,mixed> $options
+     * @param array<string,mixed>                           $options
      */
     public function chatWithMeta(string $provider, array $messages, array $options = []): AiChatCompletionResult;
 }
diff --git a/src/CoreBundle/AiProvider/AiImageProviderInterface.php b/src/CoreBundle/AiProvider/AiImageProviderInterface.php
index efcda2e7e9e..3ef8df6e45f 100644
--- a/src/CoreBundle/AiProvider/AiImageProviderInterface.php
+++ b/src/CoreBundle/AiProvider/AiImageProviderInterface.php
@@ -13,18 +13,18 @@ interface AiImageProviderInterface
      *
      * @param string $prompt   The prompt to generate an image from
      * @param string $toolName A tag, e.g. 'document_image_generate'
-     * @param ?array  $options Provider-specific options
+     * @param ?array $options  Provider-specific options
      *
      * @return string|array|null
-     *  - string: legacy mode (base64 or URL)
-     *  - array: structured response for UI (preferred)
-     *      [
-     *          'content' => string (base64),
-     *          'url' => string,
-     *          'is_base64' => bool,
-     *          'content_type' => string,
-     *          'revised_prompt' => ?string
-     *      ]
+     *                           - string: legacy mode (base64 or URL)
+     *                           - array: structured response for UI (preferred)
+     *                           [
+     *                           'content' => string (base64),
+     *                           'url' => string,
+     *                           'is_base64' => bool,
+     *                           'content_type' => string,
+     *                           'revised_prompt' => ?string
+     *                           ]
      */
-    public function generateImage(string $prompt, string $toolName, ?array $options = []): string|array|null;
+    public function generateImage(string $prompt, string $toolName, ?array $options = []): array|string|null;
 }
diff --git a/src/CoreBundle/AiProvider/AiProviderFactory.php b/src/CoreBundle/AiProvider/AiProviderFactory.php
index 5074b70b9a7..d16615fc1a3 100644
--- a/src/CoreBundle/AiProvider/AiProviderFactory.php
+++ b/src/CoreBundle/AiProvider/AiProviderFactory.php
@@ -71,18 +71,20 @@ public function __construct(
         foreach ($config as $providerName => $providerConfig) {
             if (!isset($possibleProviders[$providerName])) {
                 error_log('[AI] Unsupported provider in config: "'.$providerName.'". Skipping.');
+
                 continue;
             }
 
             if (!\is_array($providerConfig)) {
                 error_log('[AI] Provider config for "'.$providerName.'" must be an array. Skipping.');
+
                 continue;
             }
 
             $providerPrefix = $possibleProviders[$providerName];
 
             // Base provider class (e.g. OpenAiProvider)
-            $baseClass = 'Chamilo\\CoreBundle\\AiProvider\\'.$providerPrefix.'Provider';
+            $baseClass = 'Chamilo\CoreBundle\AiProvider\\'.$providerPrefix.'Provider';
             $baseObject = $this->instantiateProvider($baseClass);
 
             // If base class cannot be instantiated, we can still allow type-specific classes.
@@ -94,11 +96,11 @@ public function __construct(
 
             foreach ($typeSuffix as $type => $suffix) {
                 // Only types explicitly present in provider config are considered enabled
-                if (!array_key_exists($type, $providerConfig)) {
+                if (!\array_key_exists($type, $providerConfig)) {
                     continue;
                 }
 
-                $typeClass = 'Chamilo\\CoreBundle\\AiProvider\\'.$providerPrefix.$suffix.'Provider';
+                $typeClass = 'Chamilo\CoreBundle\AiProvider\\'.$providerPrefix.$suffix.'Provider';
 
                 // Known types: we can fallback to base provider if it implements the right interface
                 if (isset($typeInterface[$type])) {
@@ -125,12 +127,14 @@ public function __construct(
                             }
                         } else {
                             error_log('[AI] Provider "'.$providerName.'" is configured for type "'.$type.'" but no usable implementation was found (expected '.$iface.').');
+
                             continue;
                         }
                     }
 
                     $this->providers[$providerName][$type] = $obj;
                     $this->providersByType[$type][$providerName] = $obj;
+
                     continue;
                 }
 
@@ -141,6 +145,7 @@ public function __construct(
 
                     if (!$obj) {
                         error_log('[AI] Provider "'.$providerName.'" is configured for unknown type "'.$type.'" but could not instantiate "'.$typeClass.'".');
+
                         continue;
                     }
 
@@ -232,6 +237,7 @@ private function instantiateProvider(string $fqcn): ?object
             );
         } catch (Exception $e) {
             error_log('[AI] Could not instantiate '.$fqcn.': '.$e->getMessage());
+
             return null;
         }
     }
diff --git a/src/CoreBundle/AiProvider/AiTutorChatService.php b/src/CoreBundle/AiProvider/AiTutorChatService.php
index 4e760764aee..a9b1160cb8e 100644
--- a/src/CoreBundle/AiProvider/AiTutorChatService.php
+++ b/src/CoreBundle/AiProvider/AiTutorChatService.php
@@ -14,17 +14,22 @@
 use Chamilo\CoreBundle\Repository\AiTutorConversationRepository;
 use DateTime;
 use Doctrine\ORM\EntityManagerInterface;
+use InvalidArgumentException;
 use Psr\Log\LoggerInterface;
+use Security;
 use Symfony\Component\HttpFoundation\RequestStack;
 use Throwable;
 
+use const ENT_QUOTES;
+use const ENT_SUBSTITUTE;
+
 final class AiTutorChatService
 {
     /**
      * Special "friend id" used by the course chat UI to represent the AI Tutor.
      * -  0 => course public chat
      * >  0 => private chat with a user
-     * -1 => AI Tutor private conversation (per user)
+     * -1 => AI Tutor private conversation (per user).
      */
     public const FRIEND_AI = -1;
 
@@ -37,8 +42,7 @@ public function __construct(
         private readonly AiTutorConversationRepository $conversationRepo,
         private readonly AiChatCompletionClientInterface $client,
         private readonly LoggerInterface $logger
-    ) {
-    }
+    ) {}
 
     public function getOrCreateConversation(
         int $userId,
@@ -138,6 +142,7 @@ public function handleUserMessage(
     ): bool {
         try {
             $this->handleUserMessageAndGetAssistantText($userId, $course, $session, $provider, $message);
+
             return true;
         } catch (Throwable $e) {
             $this->logger->error('[AiTutorChat] handleUserMessage failed', [
@@ -236,7 +241,7 @@ private function resolveSystemPrompt(string $uiLang): string
                     return $v;
                 }
             }
-        } catch (\Throwable) {
+        } catch (Throwable) {
             // ignore
         }
 
@@ -296,11 +301,11 @@ private function buildSystemPrompt(Course $course, string $courseLanguage = ''):
         $lang = trim($courseLanguage);
 
         return "You are a digital tutor and mentor. You help me understand topics related to my courses, in this case '{$title}'. "
-            .($lang ? "The course is in '{$lang}' but just answer me in whatever language I talk to you. " : "Just answer me in whatever language I talk to you. ")
-            ."This is an educational use, so content that would not be appropriate for children (or minors under any law) is not acceptable. "
+            .($lang ? "The course is in '{$lang}' but just answer me in whatever language I talk to you. " : 'Just answer me in whatever language I talk to you. ')
+            .'This is an educational use, so content that would not be appropriate for children (or minors under any law) is not acceptable. '
             ."You are not available to me when I'm taking an exam, just in case I forget and I ask why you weren't there. "
-            ."You must mention the course title when greeting or when the user asks what you are. "
-            ."If the user asks something unrelated to the course topic, politely redirect to course-related help.";
+            .'You must mention the course title when greeting or when the user asks what you are. '
+            .'If the user asks something unrelated to the course topic, politely redirect to course-related help.';
     }
 
     private function renderEmptyState(): string
@@ -378,7 +383,7 @@ public function handleUserMessageAndGetAssistantText(
         $message = trim($message);
 
         if ('' === $message) {
-            throw new \InvalidArgumentException('Empty message.');
+            throw new InvalidArgumentException('Empty message.');
         }
 
         $conversation = $this->getOrCreateConversation($userId, $course, $session, $provider);
@@ -624,6 +629,7 @@ public function ackTutorReadUpTo(
             $current = (int) $req->getSession()->get($key, 0);
             if ($lastSeenId > $current) {
                 $req->getSession()->set($key, $lastSeenId);
+
                 return 1;
             }
 
@@ -647,6 +653,7 @@ private function getLastSeenFromSession(int $courseId, string $provider): int
             }
 
             $key = $this->buildLastSeenSessionKey($courseId, $provider);
+
             return (int) $req->getSession()->get($key, 0);
         } catch (Throwable) {
             return 0;
@@ -718,7 +725,7 @@ private function toSafeHtml(string $text): string
         $escaped = htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
         $html = nl2br($escaped);
 
-        return \Security::remove_XSS($html);
+        return Security::remove_XSS($html);
     }
 
     public function handleUserMessageForDock(
@@ -732,7 +739,7 @@ public function handleUserMessageForDock(
         $message = trim($message);
 
         if ('' === $message) {
-            throw new \InvalidArgumentException('Empty message.');
+            throw new InvalidArgumentException('Empty message.');
         }
 
         $conversation = $this->getOrCreateConversation($userId, $course, $session, $provider);
diff --git a/src/CoreBundle/AiProvider/AiVideoProviderInterface.php b/src/CoreBundle/AiProvider/AiVideoProviderInterface.php
index b4f433b71b6..4dc3995f1a0 100644
--- a/src/CoreBundle/AiProvider/AiVideoProviderInterface.php
+++ b/src/CoreBundle/AiProvider/AiVideoProviderInterface.php
@@ -13,11 +13,11 @@ interface AiVideoProviderInterface
      *
      * @param string $prompt   The prompt to generate a video from
      * @param string $toolName A tag, e.g. 'document_video_generate'
-     * @param ?array  $options Provider-specific options
+     * @param ?array $options  Provider-specific options
      *
      * @return string|array|null
-     *  - string: legacy mode (base64 or URL)
-     *  - array: structured response for UI (preferred)
+     *                           - string: legacy mode (base64 or URL)
+     *                           - array: structured response for UI (preferred)
      */
-    public function generateVideo(string $prompt, string $toolName, ?array $options = []): string|array|null;
+    public function generateVideo(string $prompt, string $toolName, ?array $options = []): array|string|null;
 }
diff --git a/src/CoreBundle/AiProvider/DeepSeekProvider.php b/src/CoreBundle/AiProvider/DeepSeekProvider.php
index 1d156f519fa..316821b9f2a 100644
--- a/src/CoreBundle/AiProvider/DeepSeekProvider.php
+++ b/src/CoreBundle/AiProvider/DeepSeekProvider.php
@@ -205,6 +205,7 @@ private function requestDeepSeek(string $prompt, string $toolName): ?string
             $generatedContent = $data['choices'][0]['message']['content'] ?? null;
             if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
                 error_log('[AI][DeepSeek] Empty content returned.');
+
                 return null;
             }
 
@@ -221,6 +222,7 @@ private function requestDeepSeek(string $prompt, string $toolName): ?string
             return $generatedContent;
         } catch (Exception $e) {
             error_log('[AI][DeepSeek] Exception: '.$e->getMessage());
+
             return null;
         }
     }
@@ -279,6 +281,7 @@ private function saveAiRequest(
     private function getUserId(): ?int
     {
         $user = $this->security->getUser();
+
         return $user instanceof UserInterface ? $user->getId() : null;
     }
 }
diff --git a/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php b/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
index 3a2320908f1..286274aecac 100644
--- a/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
+++ b/src/CoreBundle/AiProvider/DefaultAiChatCompletionClient.php
@@ -36,7 +36,7 @@ public function chatWithMeta(string $provider, array $messages, array $options =
             if (!\is_object($providerInstance)) {
                 $this->logger->warning('[AiTutorChat] Invalid provider instance', [
                     'provider' => $provider,
-                    'type' => gettype($providerInstance),
+                    'type' => \gettype($providerInstance),
                 ]);
 
                 return new AiChatCompletionResult('AI is temporarily unavailable. Please try again later.', null);
@@ -79,9 +79,6 @@ public function chatWithMeta(string $provider, array $messages, array $options =
         }
     }
 
-    /**
-     * @param mixed $raw
-     */
     private function extractResult(string $provider, mixed $raw): AiChatCompletionResult
     {
         // Already normalized
@@ -136,7 +133,7 @@ private function extractResult(string $provider, mixed $raw): AiChatCompletionRe
         if ('' === $text) {
             $this->logger->warning('[AiTutorChat] Provider returned empty response', [
                 'provider' => $provider,
-                'rawType' => gettype($raw),
+                'rawType' => \gettype($raw),
             ]);
 
             $text = 'I could not generate a response right now. Please try again.';
diff --git a/src/CoreBundle/AiProvider/GeminiProvider.php b/src/CoreBundle/AiProvider/GeminiProvider.php
index dc3374aed34..75deb7685e9 100644
--- a/src/CoreBundle/AiProvider/GeminiProvider.php
+++ b/src/CoreBundle/AiProvider/GeminiProvider.php
@@ -270,6 +270,7 @@ private function requestGemini(string $url, float $temperature, int $maxOutputTo
                 || !isset($data['candidates'][0]['content']['parts'][0]['text'])
             ) {
                 error_log('[AI][Gemini] Invalid response (status='.$statusCode.').');
+
                 return null;
             }
 
@@ -297,6 +298,7 @@ private function requestGemini(string $url, float $temperature, int $maxOutputTo
             return $generatedContent;
         } catch (Exception $e) {
             error_log('[AI][Gemini] Exception: '.$e->getMessage());
+
             return null;
         }
     }
@@ -334,6 +336,7 @@ private function buildUrl(string $template, string $model): string
     private function getUserId(): ?int
     {
         $user = $this->security->getUser();
+
         return $user instanceof UserInterface ? $user->getId() : null;
     }
 
diff --git a/src/CoreBundle/AiProvider/GrokProvider.php b/src/CoreBundle/AiProvider/GrokProvider.php
index acb1829b4c3..ba46bd80a00 100644
--- a/src/CoreBundle/AiProvider/GrokProvider.php
+++ b/src/CoreBundle/AiProvider/GrokProvider.php
@@ -207,10 +207,11 @@ public function gradeOpenAnswer(string $prompt, string $toolName): ?string
         return $this->requestText($this->textApiUrl, $this->textModel, $this->textTemperature, $this->textMaxTokens, $prompt, $toolName);
     }
 
-    public function generateImage(string $prompt, string $toolName, ?array $options = []): string|array|null
+    public function generateImage(string $prompt, string $toolName, ?array $options = []): array|string|null
     {
         if ('' === $this->imageApiUrl || '' === $this->imageModel) {
             error_log('[AI][Grok][Image] Image is not configured for this provider.');
+
             return null;
         }
 
@@ -284,12 +285,14 @@ private function requestText(string $url, string $model, float $temperature, int
 
             if (200 !== $status || !\is_array($data)) {
                 error_log('[AI][Grok][Text] Invalid response (status='.$status.').');
+
                 return null;
             }
 
             $generated = $this->extractTextContent($data);
             if (null === $generated || '' === trim($generated)) {
                 error_log('[AI][Grok][Text] Empty content returned by API.');
+
                 return null;
             }
 
@@ -300,11 +303,12 @@ private function requestText(string $url, string $model, float $temperature, int
             return $generated;
         } catch (Exception $e) {
             error_log('[AI][Grok][Text] Exception: '.$e->getMessage());
+
             return null;
         }
     }
 
-    private function requestImage(string $prompt, string $toolName, array $options = []): string|array|null
+    private function requestImage(string $prompt, string $toolName, array $options = []): array|string|null
     {
         $userId = $this->getUserId();
         if (!$userId) {
@@ -341,6 +345,7 @@ private function requestImage(string $prompt, string $toolName, array $options =
 
             if (200 !== $status || !\is_array($data)) {
                 error_log('[AI][Grok][Image] Invalid response (status='.$status.').');
+
                 return null;
             }
 
@@ -368,9 +373,11 @@ private function requestImage(string $prompt, string $toolName, array $options =
             }
 
             error_log('[AI][Grok][Image] No usable image content found in response.');
+
             return null;
         } catch (Exception $e) {
             error_log('[AI][Grok][Image] Exception: '.$e->getMessage());
+
             return null;
         }
     }
@@ -478,6 +485,7 @@ private function logRequest(int $userId, string $toolName, string $prompt, int $
     private function getUserId(): ?int
     {
         $user = $this->security->getUser();
+
         return $user instanceof UserInterface ? $user->getId() : null;
     }
 
diff --git a/src/CoreBundle/AiProvider/MistralProvider.php b/src/CoreBundle/AiProvider/MistralProvider.php
index 6e15b25eae3..511832fbdde 100644
--- a/src/CoreBundle/AiProvider/MistralProvider.php
+++ b/src/CoreBundle/AiProvider/MistralProvider.php
@@ -231,6 +231,7 @@ private function requestMistral(string $url, string $model, float $temperature,
 
             if (200 !== $statusCode || !isset($data['choices'][0]['message']['content'])) {
                 error_log('[AI][Mistral] Invalid response (status='.$statusCode.').');
+
                 return null;
             }
 
@@ -257,6 +258,7 @@ private function requestMistral(string $url, string $model, float $temperature,
             return $generatedContent;
         } catch (Exception $e) {
             error_log('[AI][Mistral] Exception: '.$e->getMessage());
+
             return null;
         }
     }
@@ -288,6 +290,7 @@ private function filterValidAikenQuestions(string $quizContent): array
     private function getUserId(): ?int
     {
         $user = $this->security->getUser();
+
         return $user instanceof UserInterface ? $user->getId() : null;
     }
 
diff --git a/src/CoreBundle/AiProvider/OpenAiProvider.php b/src/CoreBundle/AiProvider/OpenAiProvider.php
index 342ec2abeb9..a3d081af57d 100644
--- a/src/CoreBundle/AiProvider/OpenAiProvider.php
+++ b/src/CoreBundle/AiProvider/OpenAiProvider.php
@@ -14,7 +14,6 @@
 use Symfony\Component\Mime\Part\Multipart\FormDataPart;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
-use Chamilo\CoreBundle\AiProvider\AiChatCompletionResult;
 use Throwable;
 
 class OpenAiProvider implements AiProviderInterface, AiImageProviderInterface, AiVideoProviderInterface, AiDocumentProviderInterface
@@ -57,19 +56,21 @@ public function __construct(
      * Chat completion entrypoint for AiTutorChatService.
      *
      * @param array<int, array{role:string,content:string}> $messages
-     * @param array<string,mixed> $options
+     * @param array<string,mixed>                           $options
      */
     public function chat(array $messages, array $options = []): string
     {
         $userId = $this->getUserId();
         if (!$userId) {
             error_log('[AI][OpenAI][chat] User not authenticated.');
+
             return 'Error: User is not authenticated.';
         }
 
         $cfg = $this->getTypeConfig('text');
         if (empty($cfg)) {
             error_log('[AI][OpenAI][chat] Missing config for type: text');
+
             return 'Error: OpenAI text configuration is missing.';
         }
 
@@ -81,6 +82,7 @@ public function chat(array $messages, array $options = []): string
         $normalizedMessages = $this->normalizeChatMessages($messages);
         if (empty($normalizedMessages)) {
             error_log('[AI][OpenAI][chat] Empty messages payload.');
+
             return 'Error: Empty chat messages.';
         }
 
@@ -104,7 +106,7 @@ public function chat(array $messages, array $options = []): string
 
         $logPreview = $this->messagesForLog($normalizedMessages, 900);
 
-        error_log(sprintf(
+        error_log(\sprintf(
             '[AI][OpenAI][chat] Request: userId=%d url=%s model=%s temperature=%.2f max_tokens=%d messages="%s"',
             $userId,
             $url,
@@ -134,6 +136,7 @@ public function chat(array $messages, array $options = []): string
             $generatedContent = $data['choices'][0]['message']['content'] ?? null;
             if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
                 error_log('[AI][OpenAI][chat] Empty content returned.');
+
                 return 'Error: Empty response from OpenAI.';
             }
 
@@ -150,6 +153,7 @@ public function chat(array $messages, array $options = []): string
             return trim($generatedContent);
         } catch (Throwable $e) {
             error_log('[AI][OpenAI][chat] Exception: '.$e->getMessage());
+
             return 'Error: '.$e->getMessage();
         }
     }
@@ -168,12 +172,14 @@ public function generateText(string $prompt, array $options = []): string
         $userId = $this->getUserId();
         if (!$userId) {
             error_log('[AI][OpenAI][generateText] User not authenticated.');
+
             return 'Error: User is not authenticated.';
         }
 
         $cfg = $this->getTypeConfig('text');
         if (empty($cfg)) {
             error_log('[AI][OpenAI][generateText] Missing config for type: text');
+
             return 'Error: OpenAI text configuration is missing.';
         }
 
@@ -192,7 +198,7 @@ public function generateText(string $prompt, array $options = []): string
             'max_tokens' => $maxTokens,
         ];
 
-        error_log(sprintf(
+        error_log(\sprintf(
             '[AI][OpenAI][generateText] Request: userId=%d url=%s model=%s temperature=%.2f max_tokens=%d prompt="%s"',
             $userId,
             $url,
@@ -221,6 +227,7 @@ public function generateText(string $prompt, array $options = []): string
             $generatedContent = $data['choices'][0]['message']['content'] ?? null;
             if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
                 error_log('[AI][OpenAI][generateText] Empty content returned.');
+
                 return 'Error: Empty response from OpenAI.';
             }
 
@@ -237,6 +244,7 @@ public function generateText(string $prompt, array $options = []): string
             return trim($generatedContent);
         } catch (Throwable $e) {
             error_log('[AI][OpenAI][generateText] Exception: '.$e->getMessage());
+
             return 'Error: '.$e->getMessage();
         }
     }
@@ -263,7 +271,7 @@ private function normalizeChatMessages(array $messages): array
             }
 
             $role = strtolower($role);
-            if (!in_array($role, ['system', 'user', 'assistant', 'tool'], true)) {
+            if (!\in_array($role, ['system', 'user', 'assistant', 'tool'], true)) {
                 $role = 'user';
             }
 
@@ -295,6 +303,7 @@ private function messagesForLog(array $messages, int $maxChars = 900): string
         }
 
         $s = implode(' | ', $parts);
+
         return mb_substr($s, 0, $maxChars);
     }
 
@@ -418,7 +427,7 @@ public function generateDocument(string $prompt, string $toolName, ?array $optio
         return $this->requestChatCompletion($prompt, $toolName, 'document');
     }
 
-    public function generateImage(string $prompt, string $toolName, ?array $options = []): string|array|null
+    public function generateImage(string $prompt, string $toolName, ?array $options = []): array|string|null
     {
         $userId = $this->getUserId();
         if (!$userId) {
@@ -435,8 +444,8 @@ public function generateImage(string $prompt, string $toolName, ?array $options
         $promptTrimmed = trim($prompt);
         $promptForLog = mb_substr($promptTrimmed, 0, 200);
 
-        if ('dall-e-3' === $model && $n !== 1) {
-            error_log(sprintf('[AI][OpenAI][image] Model "%s" only supports n=1. Forcing n from %d to 1.', $model, $n));
+        if ('dall-e-3' === $model && 1 !== $n) {
+            error_log(\sprintf('[AI][OpenAI][image] Model "%s" only supports n=1. Forcing n from %d to 1.', $model, $n));
             $n = 1;
         }
 
@@ -454,7 +463,7 @@ public function generateImage(string $prompt, string $toolName, ?array $options
             $payload['response_format'] = $responseFormat;
         }
 
-        error_log(sprintf(
+        error_log(\sprintf(
             '[AI][OpenAI][image] Request: userId=%d tool=%s url=%s model=%s size=%s quality=%s n=%d prompt="%s"',
             $userId,
             $toolName,
@@ -487,7 +496,7 @@ public function generateImage(string $prompt, string $toolName, ?array $options
                 $param = $decoded['error']['param'] ?? null;
 
                 $finalMsg = $msg ?: 'OpenAI returned an error response.';
-                error_log(sprintf(
+                error_log(\sprintf(
                     '[AI][OpenAI][image] HTTP %d request_id=%s type=%s code=%s param=%s body=%s',
                     $status,
                     (string) $requestId,
@@ -501,8 +510,8 @@ public function generateImage(string $prompt, string $toolName, ?array $options
             }
 
             $data = json_decode((string) $raw, true);
-            if (!is_array($data)) {
-                error_log(sprintf(
+            if (!\is_array($data)) {
+                error_log(\sprintf(
                     '[AI][OpenAI][image] Invalid JSON response. HTTP %d request_id=%s body=%s',
                     $status,
                     (string) $requestId,
@@ -512,8 +521,8 @@ public function generateImage(string $prompt, string $toolName, ?array $options
                 return 'Error: Invalid JSON response from OpenAI.';
             }
 
-            if (!isset($data['data'][0]) || !is_array($data['data'][0])) {
-                error_log(sprintf(
+            if (!isset($data['data'][0]) || !\is_array($data['data'][0])) {
+                error_log(\sprintf(
                     '[AI][OpenAI][image] Missing image data[0]. HTTP %d request_id=%s keys=%s body=%s',
                     $status,
                     (string) $requestId,
@@ -541,7 +550,7 @@ public function generateImage(string $prompt, string $toolName, ?array $options
                 $result['url'] = $item['url'];
                 $result['is_base64'] = false;
             } else {
-                error_log(sprintf(
+                error_log(\sprintf(
                     '[AI][OpenAI][image] Response did not include b64_json or url. HTTP %d request_id=%s body=%s',
                     $status,
                     (string) $requestId,
@@ -561,7 +570,7 @@ public function generateImage(string $prompt, string $toolName, ?array $options
                 (int) ($data['usage']['total_tokens'] ?? 0)
             );
 
-            error_log(sprintf(
+            error_log(\sprintf(
                 '[AI][OpenAI][image] Success. HTTP %d request_id=%s revised_prompt=%s returned_base64=%s returned_url=%s',
                 $status,
                 (string) $requestId,
@@ -573,11 +582,12 @@ public function generateImage(string $prompt, string $toolName, ?array $options
             return $result;
         } catch (Exception $e) {
             error_log('[AI][OpenAI][image] Exception: '.$e->getMessage());
+
             return 'Error: '.$e->getMessage();
         }
     }
 
-    public function generateVideo(string $prompt, string $toolName, ?array $options = []): string|array|null
+    public function generateVideo(string $prompt, string $toolName, ?array $options = []): array|string|null
     {
         $userId = $this->getUserId();
         if (!$userId) {
@@ -594,22 +604,22 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
         $seconds = trim((string) $seconds);
         $size = trim((string) $size);
 
-        if (!in_array($model, self::ALLOWED_VIDEO_MODELS, true)) {
+        if (!\in_array($model, self::ALLOWED_VIDEO_MODELS, true)) {
             return 'Error: Invalid value for model. Expected one of: '.implode(', ', self::ALLOWED_VIDEO_MODELS).'.';
         }
 
-        if (!in_array($seconds, self::ALLOWED_VIDEO_SECONDS, true)) {
+        if (!\in_array($seconds, self::ALLOWED_VIDEO_SECONDS, true)) {
             return 'Error: Invalid value for seconds. Expected one of: '.implode(', ', self::ALLOWED_VIDEO_SECONDS).'.';
         }
 
-        if (!in_array($size, self::ALLOWED_VIDEO_SIZES, true)) {
+        if (!\in_array($size, self::ALLOWED_VIDEO_SIZES, true)) {
             return 'Error: Invalid value for size. Expected one of: '.implode(', ', self::ALLOWED_VIDEO_SIZES).'.';
         }
 
         $promptTrimmed = trim($prompt);
         $promptForLog = mb_substr($promptTrimmed, 0, 200);
 
-        error_log(sprintf(
+        error_log(\sprintf(
             '[AI][OpenAI][video] Request: userId=%d tool=%s url=%s model=%s seconds=%s size=%s prompt="%s"',
             $userId,
             $toolName,
@@ -630,7 +640,7 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
 
             if (
                 isset($options['input_reference_path'])
-                && is_string($options['input_reference_path'])
+                && \is_string($options['input_reference_path'])
                 && '' !== $options['input_reference_path']
             ) {
                 $path = $options['input_reference_path'];
@@ -668,14 +678,14 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
                 $finalMsg = (string) ($err['message'] ?? '');
 
                 if ('' === trim($finalMsg)) {
-                    $finalMsg = sprintf(
+                    $finalMsg = \sprintf(
                         'OpenAI returned HTTP %d. Ensure your project/org has access to model "%s" and the organization is verified if required.',
                         $status,
                         $model
                     );
                 }
 
-                error_log(sprintf(
+                error_log(\sprintf(
                     '[AI][OpenAI][video] HTTP %d request_id=%s type=%s code=%s param=%s error="%s" body=%s',
                     $status,
                     (string) $requestId,
@@ -683,31 +693,33 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
                     (string) ($err['code'] ?? ''),
                     (string) ($err['param'] ?? ''),
                     $finalMsg,
-                    $rawForLog !== '' ? $rawForLog : '(empty body)'
+                    '' !== $rawForLog ? $rawForLog : '(empty body)'
                 ));
 
                 return 'Error: '.$finalMsg;
             }
 
             $data = json_decode($raw, true);
-            if (!is_array($data)) {
-                error_log(sprintf(
+            if (!\is_array($data)) {
+                error_log(\sprintf(
                     '[AI][OpenAI][video] Invalid JSON response. HTTP %d request_id=%s body=%s',
                     $status,
                     (string) $requestId,
-                    $rawForLog !== '' ? $rawForLog : '(empty body)'
+                    '' !== $rawForLog ? $rawForLog : '(empty body)'
                 ));
+
                 return 'Error: Invalid JSON response from OpenAI.';
             }
 
-            if (!isset($data['id']) || !is_string($data['id']) || '' === trim($data['id'])) {
-                error_log(sprintf(
+            if (!isset($data['id']) || !\is_string($data['id']) || '' === trim($data['id'])) {
+                error_log(\sprintf(
                     '[AI][OpenAI][video] Missing "id" in response. HTTP %d request_id=%s keys=%s body=%s',
                     $status,
                     (string) $requestId,
                     implode(',', array_keys($data)),
                     $rawForLog
                 ));
+
                 return 'Error: OpenAI response missing "id".';
             }
 
@@ -724,7 +736,7 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
 
             $this->saveAiRequest($userId, $toolName, $promptTrimmed, 'openai', 0, 0, 0);
 
-            error_log(sprintf(
+            error_log(\sprintf(
                 '[AI][OpenAI][video] Job created. HTTP %d request_id=%s id=%s status=%s',
                 $status,
                 (string) $requestId,
@@ -735,6 +747,7 @@ public function generateVideo(string $prompt, string $toolName, ?array $options
             return $result;
         } catch (Exception $e) {
             error_log('[AI][OpenAI][video] Exception: '.$e->getMessage());
+
             return 'Error: '.$e->getMessage();
         }
     }
@@ -758,7 +771,7 @@ public function getVideoJobStatus(string $jobId): ?array
 
             if ($status >= 400) {
                 $msg = $this->extractOpenAiErrorMessage($raw);
-                error_log(sprintf(
+                error_log(\sprintf(
                     '[AI][OpenAI][video] Status HTTP %d request_id=%s id=%s error="%s" body=%s',
                     $status,
                     $requestId,
@@ -766,6 +779,7 @@ public function getVideoJobStatus(string $jobId): ?array
                     $msg,
                     $this->safeTruncate($raw, 2000)
                 ));
+
                 return [
                     'id' => $jobId,
                     'status' => 'failed',
@@ -775,7 +789,7 @@ public function getVideoJobStatus(string $jobId): ?array
             }
 
             $data = json_decode($raw, true);
-            if (!is_array($data)) {
+            if (!\is_array($data)) {
                 return [
                     'id' => $jobId,
                     'status' => '',
@@ -792,6 +806,7 @@ public function getVideoJobStatus(string $jobId): ?array
             ];
         } catch (Exception $e) {
             error_log('[AI][OpenAI][video] getVideoJobStatus exception: '.$e->getMessage());
+
             return [
                 'id' => $jobId,
                 'status' => '',
@@ -810,7 +825,7 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
         // Optional query variant (e.g. "preview") if you want smaller payloads for UI previews.
         // Keep empty by default.
         $variant = isset($cfg['content_variant']) ? trim((string) $cfg['content_variant']) : '';
-        if ($variant !== '') {
+        if ('' !== $variant) {
             $separator = (str_contains($contentUrl, '?')) ? '&' : '?';
             $contentUrl .= $separator.'variant='.rawurlencode($variant);
         }
@@ -831,7 +846,7 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
 
             if ($status >= 400) {
                 $msg = $this->extractOpenAiErrorMessage($raw);
-                error_log(sprintf(
+                error_log(\sprintf(
                     '[AI][OpenAI][video] Content HTTP %d request_id=%s id=%s error="%s" body=%s',
                     $status,
                     $requestId,
@@ -839,6 +854,7 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
                     $msg,
                     $this->safeTruncate($raw, 2000)
                 ));
+
                 return [
                     'is_base64' => false,
                     'content' => null,
@@ -849,11 +865,11 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
             }
 
             // Sometimes the content endpoint can return JSON with a URL.
-            if ($raw !== '' && ($raw[0] === '{' || $raw[0] === '[')) {
+            if ('' !== $raw && ('{' === $raw[0] || '[' === $raw[0])) {
                 $json = json_decode($raw, true);
-                if (is_array($json)) {
+                if (\is_array($json)) {
                     $url = $json['url'] ?? ($json['data']['url'] ?? null);
-                    if (is_string($url) && '' !== trim($url)) {
+                    if (\is_string($url) && '' !== trim($url)) {
                         return [
                             'is_base64' => false,
                             'content' => null,
@@ -873,7 +889,7 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
                 ];
             }
 
-            if (strlen($raw) > $maxBytes) {
+            if (\strlen($raw) > $maxBytes) {
                 return [
                     'is_base64' => false,
                     'content' => null,
@@ -892,6 +908,7 @@ public function getVideoJobContentAsBase64(string $jobId, int $maxBytes = 157286
             ];
         } catch (Exception $e) {
             error_log('[AI][OpenAI][video] getVideoJobContentAsBase64 exception: '.$e->getMessage());
+
             return [
                 'is_base64' => false,
                 'content' => null,
@@ -916,6 +933,7 @@ private function requestChatCompletion(string $prompt, string $toolName, string
 
         if (empty($cfg)) {
             error_log('[AI][OpenAI] Missing config for type: '.$type);
+
             return null;
         }
 
@@ -945,6 +963,7 @@ private function requestChatCompletion(string $prompt, string $toolName, string
             $generatedContent = $data['choices'][0]['message']['content'] ?? null;
             if (!\is_string($generatedContent) || '' === trim($generatedContent)) {
                 error_log('[AI][OpenAI] Empty content returned for type: '.$type);
+
                 return null;
             }
 
@@ -961,6 +980,7 @@ private function requestChatCompletion(string $prompt, string $toolName, string
             return $generatedContent;
         } catch (Exception $e) {
             error_log('[AI][OpenAI] Exception: '.$e->getMessage());
+
             return null;
         }
     }
@@ -992,6 +1012,7 @@ private function filterValidAikenQuestions(string $quizContent): array
     private function getTypeConfig(string $type): array
     {
         $cfg = $this->providerConfig[$type] ?? null;
+
         return \is_array($cfg) ? $cfg : [];
     }
 
@@ -1047,6 +1068,7 @@ private function saveAiRequest(
     private function getUserId(): ?int
     {
         $user = $this->security->getUser();
+
         return $user instanceof UserInterface ? $user->getId() : null;
     }
 
@@ -1058,12 +1080,13 @@ private function extractRequestId(array $headers): string
     private function extractOpenAiErrorMessage(string $raw): string
     {
         $decoded = json_decode($raw, true);
-        if (is_array($decoded)) {
+        if (\is_array($decoded)) {
             $msg = $decoded['error']['message'] ?? null;
-            if (is_string($msg) && trim($msg) !== '') {
+            if (\is_string($msg) && '' !== trim($msg)) {
                 return trim($msg);
             }
         }
+
         return 'OpenAI returned an error response.';
     }
 
@@ -1076,7 +1099,7 @@ private function decodeOpenAiError(string $raw): array
     {
         $decoded = json_decode($raw, true);
 
-        if (!is_array($decoded)) {
+        if (!\is_array($decoded)) {
             return [
                 'message' => null,
                 'type' => null,
@@ -1086,7 +1109,7 @@ private function decodeOpenAiError(string $raw): array
         }
 
         $err = $decoded['error'] ?? null;
-        if (!is_array($err)) {
+        if (!\is_array($err)) {
             return [
                 'message' => null,
                 'type' => null,
@@ -1096,10 +1119,10 @@ private function decodeOpenAiError(string $raw): array
         }
 
         return [
-            'message' => isset($err['message']) && is_string($err['message']) ? $err['message'] : null,
-            'type' => isset($err['type']) && is_string($err['type']) ? $err['type'] : null,
-            'code' => isset($err['code']) && is_string($err['code']) ? $err['code'] : null,
-            'param' => isset($err['param']) && is_string($err['param']) ? $err['param'] : null,
+            'message' => isset($err['message']) && \is_string($err['message']) ? $err['message'] : null,
+            'type' => isset($err['type']) && \is_string($err['type']) ? $err['type'] : null,
+            'code' => isset($err['code']) && \is_string($err['code']) ? $err['code'] : null,
+            'param' => isset($err['param']) && \is_string($err['param']) ? $err['param'] : null,
         ];
     }
 
@@ -1107,11 +1130,12 @@ private function decodeOpenAiError(string $raw): array
      * Chat completion with conversation state (Responses API).
      *
      * @param array<int, array{role:string,content:string}> $messages
-     * @param array<string,mixed> $options
+     * @param array<string,mixed>                           $options
      */
     public function chatWithMeta(array $messages, array $options = []): AiChatCompletionResult
     {
         $text = $this->chat($messages, $options);
+
         return new AiChatCompletionResult((string) $text, null);
     }
 
@@ -1133,12 +1157,13 @@ private function splitInstructionsAndInput(array $messages): array
             $role = $m['role'] ?? 'user';
             $content = trim((string) ($m['content'] ?? ''));
 
-            if ($content === '') {
+            if ('' === $content) {
                 continue;
             }
 
-            if ($role === 'system') {
+            if ('system' === $role) {
                 $instructions[] = $content;
+
                 continue;
             }
 
@@ -1157,32 +1182,32 @@ private function splitInstructionsAndInput(array $messages): array
     private function extractResponsesApiText(array $data): string
     {
         // Many responses include output_text directly in the response object. :contentReference[oaicite:4]{index=4}
-        if (isset($data['output_text']) && is_string($data['output_text'])) {
+        if (isset($data['output_text']) && \is_string($data['output_text'])) {
             return $data['output_text'];
         }
 
         // Fallback: walk through output[] -> content[] -> text.
-        if (!isset($data['output']) || !is_array($data['output'])) {
+        if (!isset($data['output']) || !\is_array($data['output'])) {
             return '';
         }
 
         $parts = [];
 
         foreach ($data['output'] as $item) {
-            if (!is_array($item)) {
+            if (!\is_array($item)) {
                 continue;
             }
-            if (!isset($item['content']) || !is_array($item['content'])) {
+            if (!isset($item['content']) || !\is_array($item['content'])) {
                 continue;
             }
 
             foreach ($item['content'] as $c) {
-                if (!is_array($c)) {
+                if (!\is_array($c)) {
                     continue;
                 }
 
                 // Typical shape: { "type": "output_text", "text": "..." }
-                if (isset($c['type']) && $c['type'] === 'output_text' && isset($c['text']) && is_string($c['text'])) {
+                if (isset($c['type']) && 'output_text' === $c['type'] && isset($c['text']) && \is_string($c['text'])) {
                     $parts[] = $c['text'];
                 }
             }
diff --git a/src/CoreBundle/Settings/SettingsManager.php b/src/CoreBundle/Settings/SettingsManager.php
index 4cfca013777..d8bad5b4ffb 100644
--- a/src/CoreBundle/Settings/SettingsManager.php
+++ b/src/CoreBundle/Settings/SettingsManager.php
@@ -1931,10 +1931,10 @@ private function upsertCourseSettingsForAllCourses(string $category, array $varT
         $vars = array_keys($varToValue);
         $batchSize = 300;
 
-        for ($offset = 0; $offset < count($courseIds); $offset += $batchSize) {
-            $chunk = array_slice($courseIds, $offset, $batchSize);
+        for ($offset = 0; $offset < \count($courseIds); $offset += $batchSize) {
+            $chunk = \array_slice($courseIds, $offset, $batchSize);
 
-            // Load existing settings for this chunk (IMPORTANT: filter by category)
+            // Load existing settings for this chunk
             $existing = $this->manager->createQueryBuilder()
                 ->select('cs')
                 ->from(CCourseSetting::class, 'cs')
@@ -1968,16 +1968,16 @@ private function upsertCourseSettingsForAllCourses(string $category, array $varT
                             $row->setValue($value);
                             $this->manager->persist($row);
                         }
+
                         continue;
                     }
 
-                    // Insert missing row (category standardized)
                     $new = new CCourseSetting();
                     $new
                         ->setCId($cId)
                         ->setVariable($var)
                         ->setTitle($var)
-                        ->setCategory($category) // <-- here
+                        ->setCategory($category)
                         ->setValue($value)
                     ;