HCIs y resultados
Qué es un Human Context Indicator, la forma de los resultados, los eventos en vivo y la interpretación para una audiencia.
En esta página
Esta página dice qué es cada campo. Qué enseñar primero, qué llega en cada caso y cómo releer sin pagar: Mostrar y aprovechar los resultados.
Human Context Indicators
Sección titulada «Human Context Indicators»Un HCI es un indicador de la interacción, trazable hasta la señal. El catálogo de Neurologyca tiene tres niveles: HCIs, meta-indicadores (MCI) e indicadores crudos (RCI). Ningún contexto usa todos los indicadores, y estar en el catálogo no significa que todos tengan el mismo nivel de validación.
El catálogo y lo que recibes. La tabla de abajo es el catálogo público, y es provisional. Qué indicadores recibes depende del contexto y del acuerdo de tu organización; hoy puede ser todo el catálogo público. Todo contexto interpretado incluye los que su interpretación necesita. La lista de cada protocolo está en Tu integración › Protocolos (Tu integración); un indicador que llega en un ejemplo y no en tu captura es esta trampa. Para recibir más, pídeselo a Neurologyca.
El catálogo público los agrupa según lo que describen. Si tu contexto los incluye, cada uno llega con el nombre de la columna Clave en /results, tal como llega en rawResults y aggResults (por ejemplo, Workload llega como workload_model), para que encuentres cada indicador en tus datos. Cuatro de ellos, Disengagement, Mental Fatigue Load, Emotional Mental Control y Facial Muscle Tension, no llegan en /results. Las Emociones complejas (Anticipation, Trust, Awe y el resto de su grupo) llegan en cada frame, como las básicas: Engine calcula cada una con dos emociones básicas, así que varias nunca llegan a 100; la columna Escala da el rango que puede tomar cada una.
| Indicador | Grupo | Clave en /results | Cuándo llega | Escala |
|---|---|---|---|---|
| Attention | Atención | Attention | En cada frame, desde el primero | 0/1 por frame; su media en /results es la fracción de frames con atención, 0–1 |
| Effective Active Attention Preview | Atención | effective_active_attention | Un valor por sesión, en session ({ v, n }: v es el porcentaje 0–100 de los frames medidos con Attention = 1 y n su denominador); nunca por frame | 0..100 |
| Disengagement Preview | Atención | no llega en /results | Calentamiento: 5 sesiones. Desde la 6.ª sesión, en un step con al menos 60 s de cara válida (en la práctica, unos 66–76 s seguidos). Por step o por sesión, solo se usa para la interpretación (/analyze); hoy ninguna ruta devuelve su valor; aún no en la producción de Engine | 0..100 |
| Workload | Cognición | workload_model | Tras ~5 s del inicio del step, luego 1 de cada ~6 frames; en un step de menos de ~5 s no llega. Si el step sigue sin pausa al anterior, desde el frame 1 | 0..100 |
| Coherence | Cognición | Coherence | En cada frame, desde el primero | 0..100 |
| Comprehension | Cognición | Comprehension | En cada frame, desde el primero; Engine lo calcula sobre una ventana de sesión, así que cada valor depende de todo el step | 0..100 |
| Confusion | Cognición | Confusion | En cada frame, desde el primero; Engine lo calcula sobre una ventana de sesión, así que cada valor depende de todo el step | 0..100 |
| Mental Fatigue Load Preview | Cognición | no llega en /results | Calentamiento: 5 sesiones. Desde la 6.ª sesión de la persona en ese contexto: necesita 5 sesiones previas completadas, y el baseline no cuenta. Por step o por sesión, solo se usa para la interpretación (/analyze); hoy ninguna ruta devuelve su valor; aún no en la producción de Engine | 0..100 |
| Joy | Emociones | Joy | En cada frame, desde el primero | 0..100 |
| Sadness | Emociones | Sadness | En cada frame, desde el primero | 0..100 |
| Surprise | Emociones | Surprise | En cada frame, desde el primero | 0..100 |
| Anger | Emociones | Anger | En cada frame, desde el primero | 0..100 |
| Disgust | Emociones | Disgust | En cada frame, desde el primero | 0..100 |
| Fear | Emociones | Fear | En cada frame, desde el primero | 0..100 |
| Neutral | Emociones | Neutral | En cada frame, desde el primero | 0..100 |
| Anticipation | Emociones complejas | Anticipation | En cada frame, desde el primero | 0 o 50 |
| Anxiety | Emociones complejas | Anxiety | En cada frame, desde el primero | 0..75 |
| Awe | Emociones complejas | Awe | En cada frame, desde el primero | 0..100 |
| Contempt | Emociones complejas | Contempt | En cada frame, desde el primero | 0..100 |
| Curiosity | Emociones complejas | Curiosity | En cada frame, desde el primero | 0..87,5 |
| Cynicism | Emociones complejas | Cynicism | En cada frame, desde el primero | 0..75 |
| Delight | Emociones complejas | Delight | En cada frame, desde el primero | 0..100 |
| Despair | Emociones complejas | Despair | En cada frame, desde el primero | 0..100 |
| Disapproval | Emociones complejas | Disapproval | En cada frame, desde el primero | 0..100 |
| Envy | Emociones complejas | Envy | En cada frame, desde el primero | 0..100 |
| Guilt | Emociones complejas | Guilt | En cada frame, desde el primero | 0..100 |
| Hope | Emociones complejas | Hope | En cada frame, desde el primero | 0..62,5 |
| Love | Emociones complejas | Love | En cada frame, desde el primero | 0..87,5 |
| Morbidness | Emociones complejas | Morbidness | En cada frame, desde el primero | 0..100 |
| Outrage | Emociones complejas | Outrage | En cada frame, desde el primero | 0..100 |
| Pessimism | Emociones complejas | Pessimism | En cada frame, desde el primero | 0..75 |
| Pride | Emociones complejas | Pride | En cada frame, desde el primero | 0..100 |
| Remorse | Emociones complejas | Remorse | En cada frame, desde el primero | 0..100 |
| Shame | Emociones complejas | Shame | En cada frame, desde el primero | 0..100 |
| Submission | Emociones complejas | Submission | En cada frame, desde el primero | 0..87,5 |
| Trust | Emociones complejas | Trust | En cada frame, desde el primero | 0..75 |
| Unbelief | Emociones complejas | Unbelief | En cada frame, desde el primero | 0..100 |
| Valence | Circumplejo | valence | En cada frame, desde el primero | −100..100 |
| Arousal | Circumplejo | arousal | En cada frame, desde el primero | 0..100 |
| Interest | Ánimo y regulación | Interest | En cada frame, desde el primero; Engine lo calcula sobre una ventana de sesión, así que cada valor depende de todo el step | 0..100 |
| Frustration | Ánimo y regulación | Frustration | En cada frame, desde el primero; Engine lo calcula sobre una ventana de sesión, así que cada valor depende de todo el step | 0..100. Engine está revisando su escala. |
| Rejection | Ánimo y regulación | Rejection | En cada frame, desde el primero; Engine lo calcula sobre una ventana de sesión, así que cada valor depende de todo el step | 0..100 |
| Stress intensity | Ánimo y regulación | Stress_intens | En cada frame, desde el primero; cada valor se escala sobre toda la sesión (mín-máx), así que depende de todo el step | 0..100 |
| Motivation | Ánimo y regulación | faa | Tras ~5 s del inicio del step, luego 1 de cada ~6 frames; en un step de menos de ~5 s no llega. Si el step sigue sin pausa al anterior, desde el frame 1 | −100..100. No válido, no lo uses: llega fuera de su rango y Engine va a sustituir su modelo. |
| Emotional Mental Control Preview | Ánimo y regulación | no llega en /results | Calentamiento: 5 sesiones. Desde la 6.ª sesión, en bloques de 3 min seguidos (una sesión más corta no tiene valor); el modelo de Engine es provisional. Por step o por sesión, solo se usa para la interpretación (/analyze); hoy ninguna ruta devuelve su valor; aún no en la producción de Engine | 0..100 |
| Facial Muscle Tension Preview | Ánimo y regulación | no llega en /results | Calentamiento: 0 o 5 sesiones. Desde la 1.ª sesión si el contexto ya tiene datos de calibración de Neurologyca; si no, desde la 6.ª. Por step o por sesión, solo se usa para la interpretación (/analyze); hoy ninguna ruta devuelve su valor; aún no en la producción de Engine | 0..100 |
Cuándo llega cada uno. La mayoría llega en cada frame desde el primero. Stress intensity, Comprehension, Confusion, Interest, Frustration y Rejection también tienen valor desde el primer frame, pero Engine los calcula sobre toda la sesión, así que cada valor depende de todo el step. Workload (workload_model) y Motivation (faa) necesitan un calentamiento: nada durante unos 5 primeros segundos de cada step (o tras una pausa), después un valor cada unos 6 frames y null en el resto; un step de menos de unos 5 segundos no trae la clave, y un step que sigue sin pausa al anterior tiene valores desde el primer frame. Disengagement, Mental Fatigue Load, Emotional Mental Control y Facial Muscle Tension se calculan por step o por sesión, no por frame, y solo se usan para la interpretación (/analyze); hoy ninguna ruta devuelve sus valores. Necesitan sesiones previas de la persona: consulta Indicadores que necesitan sesiones previas.
Lee los modelos como lo que son: emoción mostrada, no sentida; la valencia tal como la percibiría un observador; el arousal como intensidad expresiva, no como activación fisiológica (en el playground se enseña junto a Valence, como intensidad expresiva); workload como un indicador facial de carga cognitiva.
Escalas. Los indicadores van de 0 a 100, salvo Valence y Motivation, de −100 a 100, y Attention: vale 0 o 1 por frame, y su media en /results es la fracción de frames con atención (de 0 a 1). Motivation (faa) no es válida: no la uses. Llega, pero fuera del rango que Engine declara para ella (de 0 a 100), y Engine va a sustituir su modelo.
Indicadores que necesitan sesiones previas
Sección titulada «Indicadores que necesitan sesiones previas»Cuatro indicadores comparan la sesión actual con el historial de la persona, así que no tienen valor hasta que ese historial existe. Cada entrada del historial es una sesión de protocolo completada de la misma persona en el mismo contexto; el baseline no cuenta, y Engine guarda las 20 últimas.
- Mental Fatigue Load: 5 sesiones previas, así que tiene valor desde la 6.ª sesión de la persona en ese contexto.
- Facial Muscle Tension: desde la 1.ª sesión si el contexto ya tiene datos de calibración de Neurologyca; si no, desde la 6.ª.
- Disengagement: 5 sesiones previas y un step con al menos 60 s de cara válida.
- Emotional Mental Control: 5 sesiones previas y bloques de 3 min seguidos; una sesión más corta no tiene valor.
Aun desde la 6.ª sesión, no llegan en /results: Engine solo los usa dentro de la interpretación (/analyze), y aún no los calcula en producción. Los cuatro son Preview. En DevLab (Resultados, el modo diferido y los ejemplos grabados) aparecen como Bloqueados, con su calentamiento, porque ninguna ruta devuelve su valor.
La forma de los resultados
Sección titulada «La forma de los resultados»GET /results/{userProtocolId}/{protocolMechanicId} devuelve, por step:
{ "rawResults": { "1": { "<frameId-1>": { "hcis": { "valence": -0.343, "arousal": 64.313, "Confusion": 14.326, "Stress_intens": 64.183, "…": "64 signals in total; this example shows 4" }, "timestamp": 1767225600000 } } }, "aggResults": { "1": { "mean": { "valence": 6.751, "arousal": 69.775, "Confusion": 14.618, "Stress_intens": 54.195, "…": "64 signals in total; this example shows 4" } } }}rawResults: por step y por frame, los indicadores y el momento de la captura.aggResults: por step, la media.- Siempre de la última captura completada de esa posición. Hasta que la captura se completa,
rawResultsyaggResultsvienen vacíos: consulta en bucle. GET /results/{userProtocolId}devuelve todas las posiciones como{ userProtocolId, mechanics[] }: un elemento por mecánica, cada uno con susrawResults,aggResultsyspeech.…/{stepOrder}devuelve un solo step, con sustepOrder.- Las señales de los ejemplos de esta página salen de una captura de prueba hecha antes de que los indicadores dependieran del contexto: con tu contexto puedes recibir menos.
- El playground enseña Workload (
workload_model) cuando llega; no enseña Motivation (faa), que no es válida.
Lee rawResults como una fila por frame: ordénala por timestamp y trata una clave ausente como un hueco, nunca como un cero. Los frames enviados sin featuresMeta se cuentan en framesWithoutFeaturesMeta de cada 202 (ver Cómo capturar para la máxima precisión). Un salto de tiempo entre frames seguidos suele indicar frames que no llegaron, como una pausa de la cámara o de la pestaña. Abre una captura real en el playground.
Antes de que la captura se complete:
{ "rawResults": {}, "aggResults": {} }Las tres rutas de /results devuelven también speech: lo que se preguntó y lo que se dijo en cada step. Existe solo en el Engine del entorno de pruebas. En GET /results/{userProtocolId} va dentro de cada elemento de mechanics[]. Una captura de Measurement con voz, que no muestra pregunta:
{ "speech": { "1": { "transcript": "I usually start the day by checking my plan for the morning." } }}- Usa las mismas claves que
aggResults, el orden del step. Un step sale solo si tienequestionTextotranscript, nunca""ninull; sin nada,speeches{}. questionTextes la pregunta del step, en el idioma de la narrativa de la persona (narrative.language), no en el que se mostró ni en el que se habló. Una persona sin ese idioma no recibequestionText.transcriptes lo dicho que tu app mandó para ese step (sttByStep, ver Envía la transcripción), guardado tal cual. Lo que no se pudo situar en un step no está aquí, así que unir lostranscriptno es la transcripción entera.- Cuando un protocolo muestra la pregunta en un step y la respuesta en el siguiente (el step de respuesta lleva
media_from: previous_step),questionTextllega en el step de la pregunta ytranscripten el de la respuesta. - Es igual en tiempo real y en diferido, y no depende de qué indicadores incluye tu contexto. La ruta de interrupción no lo lleva.
session
Sección titulada «session»Las tres rutas de /results devuelven también session: valores de toda la sesión, por indicador, ni por frame como rawResults ni por step como aggResults. Hoy solo lleva Effective Active Attention (effective_active_attention), y es Preview. En GET /results/{userProtocolId} va dentro de cada elemento de mechanics[].
{ "session": { "effective_active_attention": { "v": 83.33, "n": 1247 } } }vva de 0 a 100: el porcentaje de los frames medidos de la sesión conAttention = 1, y no es la media de 0 a 1 deaggResults.mean.Attention.nes su denominador, los frames medidos: 100 sobre 30 frames no es la misma evidencia que 100 sobre 20 000.- La ruta de un solo step también lo lleva, de toda la sesión.
nullsignifica que no se midió (que no es 0) o que tu contexto no lo incluye. En la ruta de interrupción esnull.- También puede llegar
nullen la lectura justo tras el Final, aunque se midiera (visto en el Engine de pruebas, por la vía del SDK): vuelve a leer/resultsun poco después antes de darlo por ausente.
Medias entre steps
Sección titulada «Medias entre steps»aggResults da una media por step. Engine no da la media de una pregunta que ocupa dos steps ni la de toda la sesión, salvo el valor de sesión de los indicadores relevantes (measured_value de selected_ehcis[], con interpretación) y session, que hoy solo lleva Effective Active Attention. Para la media de varios steps, suma los valores de todos los frames de rawResults de esos steps y divide entre cuántos frames traen la clave; nunca hagas la media de las medias por step, que pesa igual un step corto que uno largo. Con el SDK ya lo tienes hecho: hcis es la media de todos los frames de la sesión y hcisByStep la de los frames de cada step (de retrieveResults o del resultado de stop()).
Claves en las que apoyarte
Sección titulada «Claves en las que apoyarte»El payload trae más claves que el catálogo público, las claves distinguen mayúsculas y su grafía no siempre es el nombre del catálogo (Stress_intens para Stress intensity). Construye solo sobre los indicadores documentados.
Eventos en vivo
Sección titulada «Eventos en vivo»GET /stream/{userProtocolId} es un stream de Server-Sent Events de una inscripción. Envía el token como Authorization: Bearer.
| Evento | Cuándo |
|---|---|
connected |
Se abre el stream |
processing.error |
Algo falló al procesar una captura: { errorCategory, stage, final, message } |
hci.warning |
Un aviso sobre un indicador, una vez por lote y solo de un indicador que tu contexto incluye. No es una alerta; DevLab no enseña el nivel que lo dispara (threshold), así que no construyas sobre él. Que se envíe depende del entorno |
session.abandoned |
Se abandonó una captura |
interruption.offered |
Se ofrece una microintervención |
results.ready |
La captura de la posición está completa y sus indicadores están listos, sin interpretación que esperar; payload lleva analysis (false), reason y results, la ruta que leer |
constellation.complete |
Hay una interpretación lista, cuando la pediste en el último lote. Lleva el análisis sin structured_data.temporal_profile.trajectory (una entrada por frame): léela con POST /analyze, que sirve la guardada |
stream.end |
El servidor cierra el stream; reason dice por qué |
En una captura de la muestra, el stream envió connected, hci.warning y results.ready; una captura abandonada envió además session.abandoned.
results.ready llega una vez por posición, cuando su captura está completa: es entonces cuando /results devuelve sus datos. No esperes un stepOrder concreto: no siempre es el del último step. En una posición que pidió la interpretación normalmente no llega; llega constellation.complete. En casos raros puede llegar dos veces, o junto a constellation.complete. reason dice por qué no hay interpretación: analysis_not_requested (ningún lote la pidió, como con el kit de Measurement, triggerAnalysis: false) o protocol_not_interpreted (un lote la pidió, pero el protocolo nunca se interpreta, como Measurement). Si la interpretación falla, el stream envía processing.error: los indicadores ya se pueden leer, y constellation.complete aún puede llegar tras los reintentos de Engine. Sigue consultando /results como respaldo.
processing.error dice en stage qué parte falló (emotion_analysis, hci_calculation, step_aggregation, interpretation o processing) y en final si ha terminado: con final: false Engine reintenta por su cuenta, así que aún pueden llegar los indicadores o un constellation.complete; con final: true ya no se intenta nada más para esa captura. message va en inglés y sin ids.
Puede que también veas lite.complete en el stream: un análisis preliminar que no forma parte del API público de Engine 2 (ver Migración). Nunca lo trates como la interpretación.
Interpretación para una audiencia
Sección titulada «Interpretación para una audiencia»Cuando el contexto tiene taxonomía, POST /analyze devuelve una interpretación escrita para una audience, la de la petición o la del perfil del usuario; sin ninguna de las dos, la lectura por defecto. La misma captura se puede narrar para audiencias distintas sin volver a medir, y cada una queda en caché.
Apóyate en estos campos: interpretation, structured_data.insight, structured_data.headline, structured_data.sections[], warnings, from_cache y audience_applied. Cómo salió el análisis lo dice metadata.status, uno de complete, degraded o failed; degraded también puede significar que a la lectura le faltó un indicador que tu contexto no incluye. Qué enseñar en cada caso: Qué enseñar primero.
| Campo | Qué es |
|---|---|
structured_data.insight |
Un resumen breve de la interpretación. Puede llegar null, y algunas interpretaciones no traen headline, por diseño (cuál enseñar). |
structured_data.headline |
Una frase que abre la interpretación. |
structured_data.sections[] |
Los apartados de la interpretación, cada uno con key, title, body (Markdown) y severity (info, watch, alert o null). |
interpretation |
La interpretación entera en Markdown: el titular seguido de los apartados. |
Una audiencia que no se resuelve cae a la lectura por defecto sin ningún error: compara audience_applied con la que pediste. Con el SDK, lo dice el aviso audience.not-applied; no hay ninguna ruta para listar las audiencias.
La key es la identidad estable de un apartado (por ejemplo reading, strength, risk, recommendation): casa los apartados por key, nunca por title. El title se escribe para la audiencia y puede repetirse: dos apartados con keys distintas pueden llegar con el mismo título.
interpretation y sections traen el mismo contenido (enseña uno de los dos).
Con el SDK en tiempo real hay una interpretación por sesión desde 0.38.0: la guardada, el mismo texto que tu backend lee después con POST /analyze (from_cache: true). Si dejas triggerAnalysis activo, el Final hace que Engine la genere y la guarde; stop() espera el aviso de Engine (constellation.complete) y, si no llega a tiempo, llama una vez a POST /analyze, que sirve la guardada. SessionReport.interpretationSource dice de dónde salió la de la página ('sse', 'analyze-cache', 'analyze-generated', 'analyze' o 'stream'); con 'analyze-generated' (aviso analysis.regenerated), /analyze tuvo que generar una nueva y la sesión pudo interpretarse dos veces. Hasta 0.37 el SDK abría además /analyze/stream en stop(), así que había dos interpretaciones de una misma sesión, con textos distintos, y las dos se cobraban: ve dos interpretaciones. /analyze/stream sigue generando una interpretación nueva en cada llamada y Engine no la guarda: quien lo llama directamente por la API HTTP paga un texto que el backend no leerá después, y el SDK solo lo usa si pides interpretation: 'stream'.
Cómo salió el análisis lo dice metadata.status; el resto de metadata (modelo, recuento de tokens, ids, tiempos) es interno de Engine. Esta documentación no promete esos campos: no te apoyes en ellos ni los enseñes a tus usuarios, porque pueden cambiar o desaparecer sin aviso.
Una captura de Measurement no tiene interpretación, así que no llames a POST /analyze para ella: si lo haces, Engine responde 409 con reason: PROTOCOL_NOT_ANALYSED, incluso antes de capturar. POST /analyze/stream y GET /analyze/lite/{userProtocolId}/{protocolMechanicId} responden lo mismo.
{ "code": 409, "reason": "PROTOCOL_NOT_ANALYSED", "hint": "Its indicators are computed and available through GET /results. There is no narrative analysis for this protocol, and retrying will not produce one."}Mientras Engine analiza la sesión (normalmente el análisis que lanza solo tras la captura, o uno que forzaste con reAnalyze), POST /analyze no arranca otro: responde 202 con reason: ANALYSIS_IN_PROGRESS, la cabecera Retry-After y retryAfterSeconds en el cuerpo. Las llamadas de un solo step nunca lo reciben, y la marca caduca a los 10 minutos.
{ "code": 202, "reason": "ANALYSIS_IN_PROGRESS", "message": "An analysis of this session is already running. Wait for constellation.complete on the stream, or call again later.", "retryAfterSeconds": 30}No es un error: espera constellation.complete en el stream o vuelve a llamar pasados retryAfterSeconds. El SDK aún no lo maneja: en Errores está lo que hace hoy.
Cuando el servicio de interpretación rechaza el análisis, Engine responde con el mismo estado (por ejemplo 422) y un cuerpo con code y un message genérico, sin el detalle interno del servicio; un 502 tampoco lleva texto interno. Hoy un 422 no dice si la causa es la taxonomía o el registro de tu organización: compara los ids de la taxonomía con los del protocolo antes de recapturar y, si coinciden, consulta con Neurologyca.
Campos en Preview
Sección titulada «Campos en Preview»Algunas interpretaciones traen además estos campos dentro de structured_data. Están en Preview: hasta que Neurologyca confirme que forman parte del contrato pueden cambiar o desaparecer, así que léelos solo cuando lleguen y haz que tu página funcione sin ellos. Hasta ahora solo se han visto en el Engine del entorno de pruebas. Como con metadata, apóyate solo en lo que lista esta tabla: el resto de structured_data, y de cada par, no se promete.
| Campo | Qué es |
|---|---|
structured_data.primary_emotion.term |
La emoción principal de la sesión, como término del catálogo en inglés (por ejemplo Determined), sea cual sea el idioma de la narrativa. |
structured_data.selected_ehcis[] |
Los indicadores que el contexto declara relevantes para su lectura, en el orden en que los declara (no ordenados por valor), cada uno con su id y measured_value: el valor de toda la sesión, calculado por Engine. El id no es la clave de /results (stress_intensity aquí, Stress_intens en aggResults). Para encontrar su indicador, compara el id con el nombre o la clave de cada indicador de la tabla de arriba, sin mayúsculas y sin nada que no sea letra o cifra: stress_intensity casa con Stress intensity, cuya clave es Stress_intens. Motivation y los cuatro que necesitan sesiones previas también casan: cuáles enseñar, en Qué enseñar primero. |
structured_data.pairs[] |
Cómo se agrupan los steps en preguntas. Cada par trae index, status (complete; con la pregunta en un step y la respuesta en el siguiente, incomplete con la nota question_from_preceding_step en notes, cuya pregunta es el step anterior al cierre, y el step de la pregunta unpaired, sin órdenes) y windows.opening.order y windows.closing.order: los órdenes de step, las mismas claves que aggResults, donde la pregunta se abre y donde se cierra. Ignora un par cuyos órdenes no estén en tus resultados o cuyo status no conozcas. |
Para agrupar los steps por pregunta, con pairs[] o sin ellos: Por step o por pregunta.
Un índice de 0 a 100
Sección titulada «Un índice de 0 a 100»En algunos dominios el servicio de interpretación calcula además un índice de 0 a 100 y lo publica dentro de structured_data, con su propia clave. Cada dominio que lo tiene usa su propia clave con la misma forma; wellness_index es una de ellas. No hay que configurar nada: llega en el mismo structured_data que ya lees.
{ "wellness_index": { "value": 47, "band": "medium", "status": "degraded", "indicators_used": ["stress_intensity", "arousal", "valence", "workload"], "degraded_signals": ["tens"], "label": "<la frase que se enseña, en el idioma de la narrativa>" }}| Campo | Qué es |
|---|---|
value |
Un entero de 0 a 100, ya redondeado. Enséñalo tal como llega; nunca lo recalcules. null con not_shown. |
band |
La clave del tramo en el que cae el valor. Cada índice define los suyos; para wellness_index son low (0 a 39), medium (40 a 59) y high (60 a 100). Es una clave, no texto para mostrar: la frase es label. null con not_shown. |
status |
ok (estaban todos los indicadores), degraded (faltaba uno o más y el valor se calculó con los demás: enséñalo como una lectura menos fiable) o not_shown (faltaban demasiados: no enseñes ningún número). |
indicators_used, degraded_signals |
Qué indicadores entraron en el valor y cuáles faltaron. |
label |
La frase que se enseña junto al número, completa y en el idioma de la narrativa, escrita por el servicio de interpretación; con degraded ya dice que la lectura es menos fiable. Enséñala tal como llega: no la compongas, traduzcas ni amplíes, y no la compares en tus tests, porque su redacción puede cambiar sin una versión nueva del SDK. null con not_shown y en las interpretaciones guardadas antes de que existiera. |
- La narrativa no cita el número. El texto de la interpretación nunca lo recibe; la frase que acompaña al número es
label. Silabelesnully la quieres, pide una interpretación nueva desde tu backend (reAnalyze). - No llega en las interpretaciones guardadas antes de que el índice existiera (un
/analyzeque sirve una,from_cache: true, llega sin él; unreAnalyzelo trae, salvo que Engine conserve la anterior,re_analyze_kept_previous: true), ni enGET /analyze/lite, que no lo calcula. Como la interpretación se guarda por audiencia, una audiencia de una sesión puede tenerlo y otra no.
Con el SDK (0.39.0 o posterior; label desde 0.40.0 y capture-server 0.17.0), readScoreIndex(structured, key = 'wellness_index'), en @neurologyca/capture (también /helpers) y en @neurologyca/capture-server, lo lee y comprueba su forma: devuelve { value, band, indicatorsUsed, degradedSignals, status, label }, o null si la clave no está, si la interpretación es anterior al índice o si la forma no cuadra (entonces, el aviso score-index.malformed). Nunca lanza, y nunca rechaza un índice por label (si no es una cadena, se lee como null). En vivo, structured llega en onInterpretation, en onInterpretationDetails y en CaptureOutcome.structured cuando stop() se resuelve (con interpretation: 'stream' llega en onInterpretationDetails, y CaptureOutcome.structured es null salvo que la entregue el /analyze de respaldo); en tu backend, en AnalyzeResult.structured de admin.analyze(), el camino de una captura diferida.
Pedir una interpretación nueva
Sección titulada «Pedir una interpretación nueva»Engine guarda la interpretación por sesión y audiencia. Una vez existe y su análisis salió completo, POST /analyze la devuelve (from_cache: true, en menos de un segundo). Con metadata.status degraded o failed, o sin una guardada, cada llamada la regenera, y eso cuesta tokens del modelo de lenguaje y tiempo (generar una interpretación suele tardar decenas de segundos y puede tardar unos dos minutos de punta a punta). Pídela una vez, nunca en bucle. Para obtener una nueva de la misma sesión y audiencia, envía reAnalyze: true desde tu backend:
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "reAnalyze": true }- La respuesta lleva
from_cache: falsey tarda lo que una primera interpretación (normalmente decenas de segundos, hasta unos dos minutos de punta a punta). La interpretación nueva sustituye a la guardada: la siguiente petición sinreAnalyzela devuelve, confrom_cache: true. - Solo afecta a la audiencia que pides, la
audiencede la petición o la de la persona: la interpretación guardada de otra audiencia se queda como estaba. - Si el análisis nuevo falla o sale peor, Engine conserva el guardado y lo devuelve con
re_analyze_kept_previous: true. - El nombre se compara exacto:
REANALYZEoReAnalyzereciben un400(Unknown key 'REANALYZE': the field is 'reAnalyze', with that exact casing.). - Cada
reAnalyzegenera una interpretación nueva, que cuesta tokens del modelo de lenguaje. Envíalo por una decisión deliberada, nunca en bucle ni en cada lectura. Para comparar dos lecturas, mira antesfrom_cache: contrue, es la misma interpretación que ya tenías. - Solo desde tu backend. El proxy lo quita de los cuerpos de
/analyzedel navegador, así que una página no puede forzarlo.
Con el SDK, desde tu backend: admin.analyze(pair, { reAnalyze: true }) de createEngineAdmin (AnalyzeOptions.reAnalyze). AnalyzeResult.fromCache es el from_cache de Engine y AnalyzeResult.keptPrevious su re_analyze_kept_previous. admin.analyzeForAudiences nunca la fuerza: volver a pedir una audiencia devuelve la interpretación guardada.
Releer una sesión más tarde, sin pagar otra: solo una complete, con la audiencia para la que se escribió y sin reAnalyze (cómo).
Qué no devuelve Engine
Sección titulada «Qué no devuelve Engine»No hay agregado de todo un protocolo, ni webhooks, ni audio.
En el SDK
Sección titulada «En el SDK»El SDK te da los mismos resultados, ya leídos: stop() se resuelve con un CaptureOutcome (status, hcis, hcisByStep, frameCount, interpretation y, desde 0.39.0, structured):
{ "status": "complete", "hcis": { "valence": "<number>", "arousal": "<number>", "Confusion": "<number>", "Stress_intens": "<number>", "…": "65 signals in total; this example shows 4" }, "hcisByStep": { "1": { "valence": "<number>", "arousal": "<number>", "Confusion": "<number>", "Stress_intens": "<number>", "…": "65 signals in total; this example shows 4" } }, "frameCount": 450, "interpretation": null, "structured": null}Los valores salen de la cara de una persona, así que aquí van sin ellos; los nombres son los indicadores públicos que recibes, y el recuento es de una captura con Measurement posterior a los ejemplos de arriba.
Durante la captura, onResult trae un ProtocolResultEvent:
| Campo | Qué es |
|---|---|
ProtocolResultEvent.hcis |
Las medias de los indicadores |
ProtocolResultEvent.hcisByStep |
Las medias, por step |
ProtocolResultEvent.frameCount |
Los frames que las respaldan |
ProtocolResultEvent.raw |
El cuerpo entero de GET /results: dibuja de él la serie por frame, sin otra llamada |
Las escalas son las de arriba: de 0 a 100, Valence de −100 a 100, Attention 0 o 1 por frame y su media como la fracción de frames con atención. Si pediste una interpretación, onInterpretationDetails trae sus detalles estructurados justo después de onInterpretation, con los mismos structured y metadata (desde 0.38.0). Solo con interpretation: 'stream' llegan más tarde, normalmente cuando stop() ya ha resuelto: entonces espéralos con un plazo propio.
Cómo fue la captura llega en el SessionReport que recibe onReport al acabar. Desde la 0.43.0 (kodec 5.0.0-rc.14) dos de sus contadores cuentan distinto: codecErrors ya no cuenta la recarga de la cara de face.context-lost y prepare.face-lost, ni un hueco capture-stalled que caiga dentro de ella, y sigue contando una cámara perdida (track-ended); transcription.lostOnClose cuenta también una frase cortada por un abort() o un stop() a mitad de un step, donde antes podía leer 0. Dos avisos dicen lo que no llegó al resultado: baseline.framesLost (el servidor confirmó menos frames del baseline de los que se mandaron, y nada los reintenta) y audience.not-applied (la interpretación llegó con la lectura por defecto). Todos los avisos: Errores, avisos y reintentos.