undefined — vista limpia

Qué es

El Informante del estado es una capa de enriquecimiento de contexto que se activa en el Help Widget de CreaRack Pro cuando el usuario formula una pregunta operativa (ej. “¿hay alertas?”, “¿cuántos racks tengo?”, “¿qué devices están caídos?”).

Sin ninguna llamada LLM adicional y sin HTTP externo, el sistema detecta la intención de la pregunta mediante regex locales, consulta datos en vivo de la base de datos (filtrados por organización vía RLS), y prepend un bloque [CONTEXTO] al prompt que llega al MCP bib_ask. El modelo recibe datos factuales reales y puede responder con cifras precisas en lugar de declinar o inventar.

Motivación

Antes de s56, el Help Widget en modo help reenviaba la pregunta del usuario al MCP tal cual. Si el usuario preguntaba “¿hay alertas activas?”, el modelo solo podía responder desde su conocimiento estático de la wiki, no desde el estado real del sistema.

El Informante resuelve esto con coste cero cuando no hay match (el bloque if solo se ejecuta si algún regex del catálogo dispara) y ~30-80 tokens extra cuando sí hay match.

Arquitectura

Usuario → /api/help/ask (mode=help)
              │
              ▼
    detect_state_intent(question)     ← help_intent.py
         │ regex, sin DB, sin LLM
         │ → lista de items activados (o [] si ninguno)
         │
    build_state_context(items, user)  ← help_state.py
         │ queries SQL por org (RLS)
         │ → bloque [CONTEXTO: datos en vivo...]
         │
    question = f"{ctx}\n\n{question}"
         │
         ▼
    _mcp_call("bib_ask", {...})       ← MCP Biblioteca

Modo Tutor (mode=tutor) NO recibe inyección de contexto — el Informante solo opera en mode=help.

Catálogo de items (MVP s56)

Item	Ejemplos de keywords que disparan	Builder SQL
`alerts`	alerta, alarma, problema, incidencia	`AlertEvent` (unresolved)
`racks`	rack, armario, sala técnica	`Rack` por org
`devices`	device, switch, router, AP, caído, offline	`MonitoringTarget`
`health`	salud, uptime, sano, DB	DB ping + disco + uptime proc
`signage`	pantalla, display, playlist, cartel	`SignagePlayer`
`provision`	auto-provision, discovery, scan	`DeviceProfile` (24h)
`capacity`	espacio, U libres, lleno, capacidad	`Rack` + `devices__u_height`

Items NO incluidos en MVP (decisión Edu s56): sesiones SSH (agente local, no multi-tenant) y ancho de banda de red (requiere VictoriaMetrics).

Granularidad por rol

El builder recibe is_admin: bool. Se considera admin si el rol es admin, operator, is_superuser o is_staff. Solo readonly recibe vista reducida.

Vista	Roles	Diferencia
Reducida	`readonly`	Counts y resumen básico
Extendida	`admin`, `operator`, superuser, staff	Nombres concretos, top-N, disco, uptime

Decisión Edu s56: operator opera, no es solo lector → vista extendida.

Seguridad y aislamiento multi-tenant

Todos los builders filtran explícitamente por organization=user.organization.
El TenantRLSMiddleware aplica RLS en Postgres como segunda capa.
Si el usuario no tiene organization asignada, los builders devuelven cadena vacía (sin datos).
El bloque completo está en try/except: un fallo del Informante nunca rompe el Help Widget.

Archivos clave

Archivo	Rol
`core/api_help.py`	Punto de entrada — llama a detect + build y prepend el contexto
`core/services/help_intent.py`	Detector de intención (regex puro, sin DB)
`core/services/help_state.py`	Builders SQL por item — produce el bloque `[CONTEXTO]`
`tests/api/test_help.py`	Tests unitarios (intent), de integración (DB) y E2E (mock MCP)

Cobertura de tests

Nivel 1 — detect_state_intent: 17 parametrize cases + 5 casos negativos (conceptuales no disparan).
Nivel 2 — build_state_context: fixtures DB por item (rack, device, alert, signage, provision, capacity) + multi-tenant isolation + operator vs reader.
Nivel 3 — Integración /api/help/ask: query operativa inyecta [CONTEXTO], query conceptual pasa limpia, modo Tutor no inyecta.

Limitaciones conocidas

El uptime del proceso en health es una heurística basada en os.path.getmtime(__file__), no un valor exacto.
Los falsos positivos de regex son aceptables (p.ej., “¿cómo crear un rack?” activa racks). Coste extra ~50 tokens y el modelo responde correctamente igual.
El catálogo no es configurable en runtime: cambios requieren código + redeploy.

Véase también

[[entity—core—service—help-intent]] — Detector de intención operativa: catálogo regex sin DB ni LLM
[[entity—core—service—help-state]] — Builders SQL que producen el bloque [CONTEXTO] con datos en vivo
[[workspace—que-es-workspace]] — Contexto general del workspace y módulos de CreaRack Pro

Help Widget · Informante del Estado (MVP s56)