Help Widget — Toggle IT Tutor (modo tutor de IT/Networking)

Help Widget — Toggle IT Tutor (modo tutor de IT/Networking)

Resumen

El Help Widget de CreaRack Pro incorpora desde el commit 42ecb08 (s53) un toggle IT Tutor que cambia el rol del asistente de IA integrado. En modo activo, el widget deja de buscar en la wiki de la app y responde como senior IT engineer & teacher, con conocimiento general de Cisco, Juniper, Linux, IEEE/RFC, SNMP y hardware vendors.

Esta feature se introdujo en dos commits parejos:

• 42ecb08 (este repo, CreaRack Pro): frontend + backend Django.
• 86c9ac4 (workspace Biblioteca): handler bib_ask con soporte del parámetro mode.

Comportamiento por modo

Arquitectura del flujo

[Usuario activa toggle]
       │
       ▼
alpine-components.js · toggleTutor()
  • tutorMode = !tutorMode
  • localStorage.setItem('helpTutorMode', ...)
  • answer = null  (limpia respuesta previa)
       │
       ▼
[Usuario envía pregunta]
       │
       ▼
alpine-components.js · ask()
  if tutorMode → payload = { question, mode: 'tutor' }
  else         → payload = { question, app: <inferido de URL> }
       │
       ▼
POST /api/help/ask  (core/api_help.py · help_ask)
  mode = 'tutor' | 'help'  (sanitizado)
  _mcp_call('bib_ask', { question, mode, archive: False, ... })
       │
       ▼
Workspace · handler bib_ask (commit 86c9ac4)
  if mode == 'tutor' → skipea vector search → responde con knowledge general
  else               → RAG normal sobre wiki chunks

Implementación técnica

Backend — core/api_help.py

# s53: extrae mode del payload y lo reenvía al MCP
mode = "tutor" if payload.get("mode") == "tutor" else "help"

raw = _mcp_call("bib_ask", {
    "question": question,
    "source_type": payload.get("source_type"),
    "app": payload.get("app"),
    "mode": mode,
    "archive": False,   # El cron del Curator se encarga del archivado
})

El sanitizado "tutor" if ... == "tutor" else "help" es intencional: valores desconocidos caen silenciosamente a "help", evitando que el frontend pueda inyectar modos no definidos.

Frontend — static/js/alpine-components.js

Estado y persistencia:

// Carga inicial desde localStorage (resistente a errores de acceso)
tutorMode: (function () {
    try { return localStorage.getItem('helpTutorMode') === 'true'; }
    catch (_) { return false; }
})(),

Toggle:

toggleTutor() {
    this.tutorMode = !this.tutorMode;
    try { localStorage.setItem('helpTutorMode', String(this.tutorMode)); } catch (_) {}
    this.answer = null;  // Limpia respuesta: cambio de rol → respuesta anterior confunde
},

Getters CSP-safe:

get tutorActiveClass() { return this.tutorMode ? 'active' : ''; },
get askPlaceholder() {
    return this.tutorMode
        ? 'Ask any IT question (Cisco, Linux, networking...)'
        : 'Ask anything about CreaRack...';
},

Construcción del payload en ask():

if (this.tutorMode) {
    payload.mode = 'tutor';
    // NO se añade payload.app: en modo tutor la app activa es irrelevante
} else {
    // Context-aware retrieval (s52): inferencia de app desde pathname
    var app = null;
    if (path.indexOf('/monitoring/') === 0 ...) app = 'monitoring';
    // ... resto de reglas s52
    if (app) payload.app = app;
}

Template — templates/base.html

El bloque help-mode-bar se inserta sobre el formulario help-ask-form existente:

<div class="help-mode-bar" data-stop-propagation>
    <button type="button"
        class="help-mode-toggle"
        :class="tutorActiveClass"
        @click="toggleTutor"
        :title="...mensaje contextual...">
        <span class="help-mode-dot"></span>
        <span class="help-mode-label">IT Tutor</span>
    </button>
    <span class="help-mode-hint" x-show="tutorMode">
        General IT, networking, datacenter ops
    </span>
</div>

CSS — static/css/pages/help.css

Añade el sistema de estilos help-mode-bar / help-mode-toggle / .active:

• Pill button compacto con border-radius: 999px.
• Dot indicador (.help-mode-dot): gris en OFF → blanco sobre fondo accent en ON.
• Transiciones 0.15s en background, color y border-color.
• .help-mode-hint: texto secundario en itálica, visible solo cuando tutorMode es true (gestionado por Alpine x-show).

Decisiones de diseño notables

1. Default OFF

El modo tutor está desactivado por defecto. El asistente base (help) sigue siendo el comportamiento principal: grounded en la wiki de la app, con sources. IT Tutor es un modo opt-in explícito.

2. Limpieza de respuesta al toggle

toggleTutor() hace this.answer = null. Esto es intencional: si el usuario tenía una respuesta del modo Help y activa IT Tutor (o viceversa), mostrar esa respuesta bajo el nuevo modo es confuso. Se limpia para que el contexto visual coincida con el rol activo.

3. Sin app context en modo tutor

Cuando tutorMode es true, el frontend omite la lógica de inferencia de app (s52). Una pregunta sobre VLANs o comandos Cisco no tiene contexto de app relevante. Enviarlo sería ruido para el workspace.

4. Persistencia defensiva con try/catch

Tanto la lectura como la escritura en localStorage están envueltas en try/catch. Algunos navegadores o contextos de iframe bloquean el acceso a localStorage; el fallback es simplemente false (modo Help por defecto).

5. archive: False en MCP call

El helper _mcp_call ya incluía archive: False desde s52. En modo tutor esto es doblemente correcto: no hay chunks de wiki que archivar, y el Curator cron diario se encarga del archivado si fuera necesario.

Dominios de conocimiento en modo tutor

Según la descripción del commit y los comentarios del código, el workspace en modo tutor opera con conocimiento de:

• Cisco (IOS, NX-OS, comandos, configuración de switches/routers)
• Juniper (JunOS)
• Linux (administración de sistemas, redes, comandos)
• IEEE / RFC (estándares de redes, protocolos)
• SNMP (gestión de dispositivos de red)
• Hardware vendors (knowledge general de fabricantes de datacenter)

Relación con features anteriores

El modo IT Tutor es un bypass deliberado del RAG introducido en s52: mientras s52 mejora la precisión del Help en contexto de la app, s53 permite salir del contexto de la app completamente.

Véase también

• [[crearack—monitoring—cns-sentinel]]