POST /api/v1/clasificar

Clasifica un tamizaje SENA en uno de los 5 tipos de caso y asigna un semáforo de riesgo de 4 niveles. Cuando el modelo modelo.pkl está cargado, utiliza un clasificador Random Forest entrenado sobre respuestas históricas. Si el modelo no está disponible, aplica el motor de reglas heurísticas basado en los criterios del SENA.

POST http://localhost:8000/api/v1/clasificar
Content-Type: application/json

Cuerpo de la solicitud

Todos los campos de escala son obligatorios excepto respuestas, edad y sexo. Cuando el modelo ML está activo, el campo respuestas es necesario para calcular los features internos; sin él, el sistema aplica las reglas heurísticas como fallback.

Identificación

estudiante_id

string

required

Identificador único del estudiante (CUID generado por Prisma).

Escalas de control

inc

float

required

Inconsistencia. Puntuación directa de la escala INC. Si inc >= 1.2, el caso se clasifica como INCONSISTENCIA.

neg

float

required

Impresión negativa. Puntuación directa de la escala NEG. Combinada con glo_t >= 70 activa el tipo IMPRESION_NEGATIVA.

pos

float

required

Impresión positiva. Puntuación directa de la escala POS. Si pos >= 8, el caso se clasifica como IMPRESION_POSITIVA.

Índices globales (puntuación T)

glo_t

integer

required

Índice global general (GLO). Valor T — media 50, DE 10.

emo_t

integer

required

Índice de problemas emocionales (EMO).

con_t

integer

required

Índice de problemas conductuales (CON).

eje_t

integer

required

Índice de problemas de ejecución (EJE).

ctx_t

integer

required

Índice de problemas contextuales (CTX).

rec_t

integer

required

Índice de recursos personales (REC).

Problemas interiorizados (T)

dep_t

integer

required

Depresión (DEP).

ans_t

integer

required

Ansiedad (ANS).

asc_t

integer

required

Aislamiento social (ASC).

som_t

integer

required

Quejas somáticas (SOM).

pst_t

integer

required

Sintomatología postraumática (PST).

obs_t

integer

required

Obsesión-compulsión (OBS).

Problemas exteriorizados (T)

ate_t

integer

required

Problemas de atención (ATE).

hip_t

integer

required

Hiperactividad-impulsividad (HIP).

ira_t

integer

required

Problemas de ira (IRA).

agr_t

integer

required

Agresión (AGR).

des_t

integer

required

Conducta desafiante (DES).

ant_t

integer

required

Conducta antisocial (ANT).

Otros problemas (T)

sus_t

integer

required

Consumo de sustancias (SUS).

esq_t

integer

required

Esquizotipia (ESQ).

ali_t

integer

required

Problemas de alimentación (ALI).

Problemas contextuales (T)

fam_t

integer

required

Problemas familiares (FAM).

esc_t

integer

required

Problemas escolares (ESC).

com_t

integer

required

Problemas con los compañeros (COM).

Vulnerabilidades (T)

reg_t

integer

required

Desregulación emocional (REG).

bus_t

integer

required

Búsqueda de sensaciones (BUS).

Recursos personales (T)

aut_t

integer

required

Autoestima (AUT).

soc_t

integer

required

Integración y competencia social (SOC).

cnc_t

integer

required

Conciencia de los problemas (CNC).

Campos adicionales

items_criticos_count

integer

default:"0"

Número de ítems críticos activos en el cuestionario. Si items_criticos_count >= 15 (junto con glo_t >= 65 y dep_t >= 80), el semáforo se eleva a ROJO_URGENTE.

respuestas

string

Cadena de 188 dígitos (valores 1–5) correspondiente a las respuestas brutas del cuestionario SENA. Requerida cuando el modelo ML está activo; sin este campo, el sistema aplica las reglas heurísticas.

edad

integer

Edad del estudiante en años. Mejora la predicción del modelo ML. Valor por defecto interno: 15.

sexo

string

Sexo del estudiante. Valores aceptados: MASCULINO, FEMENINO, OTRO. Mejora la predicción del modelo ML.

Respuesta

estudiante_id

string

El mismo estudiante_id recibido en la solicitud.

tipo_caso

string

Clasificación del tamizaje. Uno de los siguientes valores:

Show Valores de tipo_caso

Valor	Semáforo	Criterio
`INCONSISTENCIA`	`AMARILLO`	`inc >= 1.2` — cuestionario con inconsistencias
`SIN_RIESGO`	`VERDE`	Índices normales, sin sesgos detectados
`IMPRESION_POSITIVA`	`AMARILLO`	`pos >= 8` — sesgo de presentación positiva
`IMPRESION_NEGATIVA`	`ROJO`	`neg >= 5` y `glo_t >= 70` — impresión negativa con índices elevados
`CON_RIESGO`	`ROJO` o `ROJO_URGENTE`	Índices clínicamente elevados sin sesgo

semaforo

string

Nivel de riesgo visual de cuatro niveles:

Show Valores de semaforo

Valor	Significado	Acción recomendada
`VERDE`	Sin indicadores de riesgo	Seguimiento periódico normal
`AMARILLO`	Atención preventiva recomendada	Revisión con orientador o psicólogo
`ROJO`	Riesgo emocional detectado	Programar cita con psicólogo
`ROJO_URGENTE`	Riesgo emocional alto confirmado	Atención inmediata

confianza

float

Probabilidad de la clase predicha en el rango [0, 1], redondeada a 3 decimales. Solo se incluye cuando el modelo ML Random Forest está activo; null en modo de reglas.

observaciones

string

Texto descriptivo sobre el resultado. Generado por las reglas heurísticas o por el post-procesamiento del modelo. Puede ser null.

Ejemplos

curl -X POST http://localhost:8000/api/v1/clasificar \
  -H "Content-Type: application/json" \
  -d '{
    "estudiante_id": "est-5",
    "inc": 0.9,
    "neg": 1,
    "pos": 0,
    "glo_t": 66,
    "emo_t": 70,
    "con_t": 55,
    "eje_t": 60,
    "ctx_t": 58,
    "rec_t": 45,
    "dep_t": 86,
    "ans_t": 72,
    "asc_t": 60,
    "som_t": 65,
    "pst_t": 68,
    "obs_t": 55,
    "ate_t": 58,
    "hip_t": 52,
    "ira_t": 60,
    "agr_t": 55,
    "des_t": 50,
    "ant_t": 48,
    "sus_t": 50,
    "esq_t": 52,
    "ali_t": 50,
    "fam_t": 65,
    "esc_t": 60,
    "com_t": 58,
    "reg_t": 50,
    "bus_t": 50,
    "aut_t": 42,
    "soc_t": 45,
    "cnc_t": 50,
    "items_criticos_count": 19
  }'

Respuesta — CON_RIESGO urgente

{
  "estudiante_id": "est-5",
  "tipo_caso": "CON_RIESGO",
  "semaforo": "ROJO_URGENTE",
  "confianza": null,
  "observaciones": "Riesgo emocional alto confirmado. Atencion URGENTE e inmediata."
}

Respuesta — SIN_RIESGO

{
  "estudiante_id": "est-1",
  "tipo_caso": "SIN_RIESGO",
  "semaforo": "VERDE",
  "confianza": null,
  "observaciones": "Sin indicadores de riesgo. Seguimiento periodico normal."
}

Respuesta — modelo ML activo (con confianza)

{
  "estudiante_id": "est-5",
  "tipo_caso": "CON_RIESGO",
  "semaforo": "ROJO_URGENTE",
  "confianza": 0.892,
  "observaciones": null
}

Errores

Código HTTP	Descripción
`422 Unprocessable Entity`	El cuerpo de la solicitud no cumple el esquema Pydantic (campo faltante o tipo incorrecto).
`500 Internal Server Error`	Error interno durante la clasificación. El campo `detail` contiene el mensaje de la excepción.

{
  "detail": "El mensaje de error específico aquí"
}

Lógica de clasificación

El servicio primero verifica si existe ml-api/models/modelo.pkl. Si el archivo está presente, usa el Random Forest; de lo contrario aplica las reglas heurísticas. Con el modelo activo, si respuestas no se proporciona, también cae de vuelta a las reglas.

Motor de reglas (fallback)

Las reglas se evalúan en este orden de prioridad:

inc >= 1.2 → INCONSISTENCIA / AMARILLO
pos >= 8 → IMPRESION_POSITIVA / AMARILLO
neg >= 5 y glo_t >= 70 → IMPRESION_NEGATIVA / ROJO
(glo_t >= 65 y dep_t >= 80) o items_criticos_count >= 15 → CON_RIESGO / ROJO_URGENTE
glo_t >= 60 o emo_t >= 65 o dep_t >= 70 o items_criticos_count >= 10 → CON_RIESGO / ROJO
Ninguna condición anterior → SIN_RIESGO / VERDE

Modelo ML (cuando está cargado)

El modelo recibe un vector de 25 features calculados a partir de la cadena de 188 respuestas: 21 sumas de ítems por escala, 1 contador de respuestas altas (valor ≥ 4), 1 contador de ítems críticos (valor ≥ 3), edad y sexo numérico.

ML API

Acciones del Sistema

POST /api/v1/clasificar

Cuerpo de la solicitud

Identificación

Escalas de control

Índices globales (puntuación T)

Problemas interiorizados (T)

Problemas exteriorizados (T)

Otros problemas (T)

Problemas contextuales (T)

Vulnerabilidades (T)

Recursos personales (T)

Campos adicionales

Respuesta

Ejemplos

Respuesta — CON_RIESGO urgente

Respuesta — SIN_RIESGO

Respuesta — modelo ML activo (con confianza)

Errores

Lógica de clasificación

Motor de reglas (fallback)

Modelo ML (cuando está cargado)

Build docs developers (and LLMs) love

ML API

Acciones del Sistema

​Cuerpo de la solicitud

​Identificación

​Escalas de control

​Índices globales (puntuación T)

​Problemas interiorizados (T)

​Problemas exteriorizados (T)

​Otros problemas (T)

​Problemas contextuales (T)

​Vulnerabilidades (T)

​Recursos personales (T)

​Campos adicionales

​Respuesta

​Ejemplos

​Respuesta — CON_RIESGO urgente

​Respuesta — SIN_RIESGO

​Respuesta — modelo ML activo (con confianza)

​Errores

​Lógica de clasificación

​Motor de reglas (fallback)

​Modelo ML (cuando está cargado)

Build docs developers (and LLMs) love

Cuerpo de la solicitud

Identificación

Escalas de control

Índices globales (puntuación T)

Problemas interiorizados (T)

Problemas exteriorizados (T)

Otros problemas (T)

Problemas contextuales (T)

Vulnerabilidades (T)

Recursos personales (T)

Campos adicionales

Respuesta

Ejemplos

Respuesta — CON_RIESGO urgente

Respuesta — SIN_RIESGO

Respuesta — modelo ML activo (con confianza)

Errores

Lógica de clasificación

Motor de reglas (fallback)

Modelo ML (cuando está cargado)