Servicio help_intent · Detector de Intención Operativa (Help Widget)

Servicio `help_intent` · Detector de Intención Operativa

Módulo: core/services/help_intent.py
App Django: core
Tipo: servicio puro (sin DB, sin LLM)
Sprint: s56 — PR #24

Responsabilidad

help_intent.py analiza la pregunta del usuario en el Help Widget y decide si contiene intención operativa — es decir, si el usuario está preguntando sobre el estado actual del sistema en lugar de pedir documentación o conceptos.

La detección se hace exclusivamente con expresiones regulares compiladas. No hay llamadas a base de datos, no hay llamadas LLM, no hay HTTP externo. Si la pregunta no hace match con ningún patrón, el coste es exactamente cero.

API pública

`detect_state_intent(question: str) -> list[str]`

Recibe la pregunta del usuario y devuelve la lista de items del catálogo que han disparado al menos un regex.

from core.services.help_intent import detect_state_intent

items = detect_state_intent("¿hay alertas activas?")
# → ["alerts"]

items = detect_state_intent("¿qué racks tengo y cuánto espacio libre?")
# → ["racks", "capacity"]

items = detect_state_intent("explícame qué es VLAN trunking")
# → []  (query conceptual, sin inyección)

Lista vacía → no es query operativa → no inyectar contexto.
Lista con items → pasar a build_state_context en help_state.py.

Catálogo `STATE_INTENT_CATALOG`

Diccionario {item: [regex_patterns]} con 7 items en el MVP:

Item	Nº patrones	Ejemplos de keywords
`alerts`	7	alerta(s), alarma(s), problema(s), incidencia(s), “todo bien”, “qué tal va”
`racks`	3	rack(s), armario(s), sala técnica
`devices`	11	device(s), switch, router, AP(s), UPS, online, offline, caído(a)(s), down
`health`	5	salud, estado general, sano, uptime, servicio(s) arriba/abajo
`signage`	6	signage, pantalla(s), display(s), playlist(s), cartel(es), cartelera(s)
`provision`	5	auto-provision, descubrimiento, discovery, scan(s/eo/ner), dispositivos nuevos
`capacity`	7	espacio, U libres, lleno(s), capacidad, ocupación, disponible

Los patrones se compilan una sola vez al importar el módulo (_COMPILED) con flag re.IGNORECASE.

Filosofía de diseño

Falsos negativos aceptables. Falsos positivos evitar.

Si un regex no dispara en una pregunta operativa real, el flujo cae al Help normal sin inyección. Coste 0, respuesta menos precisa pero correcta.

Si un regex dispara en una pregunta no operativa (falso positivo), se gastan ~50-80 tokens extra y el bloque [CONTEXTO] llega al modelo — que lo ignora sin daño. También aceptable.

Lo que se evita: patrones demasiado genéricos que disparen en cualquier pregunta.

Extensión del catálogo

Para añadir un item nuevo:

Añadir entrada en STATE_INTENT_CATALOG en help_intent.py.
Implementar el builder correspondiente en help_state.py y registrarlo en _BUILDERS.
Añadir tests en tests/api/test_help.py.

No hay interfaz de configuración en runtime. Cambios requieren redeploy.

Véase también

[[feature—core—help-informante-estado]]
[[entity—core—service—help-state]]
[[workspace—que-es-workspace]]