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_contextenhelp_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_CATALOGenhelp_intent.py. - Implementar el builder correspondiente en
help_state.pyy 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]]