# HCIs y resultados

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](/docs/es/guides/show-results/).

## 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](/docs/es/access/account/#tu-integración)); un indicador que llega en un ejemplo y no en tu captura es [esta trampa](/docs/es/resources/pitfalls/#pf-hci-not-in-your-context). 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](#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

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

`GET /results/{userProtocolId}/{protocolMechanicId}` devuelve, por step:

```json
{
  "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, `rawResults` y `aggResults` vienen vacíos: consulta en bucle.
- `GET /results/{userProtocolId}` devuelve todas las posiciones como `{ userProtocolId, mechanics[] }`: un elemento por mecánica, cada uno con sus `rawResults`, `aggResults` y `speech`. `…/{stepOrder}` devuelve un solo step, con su `stepOrder`.
- 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](/docs/es/concepts/capture/)). 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](/playground#results).

Antes de que la captura se complete:

```json
{ "rawResults": {}, "aggResults": {} }
```

### `speech`

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:

```json at="body"
{
  "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 tiene `questionText` o `transcript`, nunca `""` ni `null`; sin nada, `speech` es `{}`.
- `questionText` es 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 recibe `questionText`.
- `transcript` es lo dicho que tu app mandó para ese step (`sttByStep`, ver [Envía la transcripción](/docs/es/api/#envía-la-transcripción)), guardado tal cual. Lo que no se pudo situar en un step no está aquí, así que unir los `transcript` no 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`), `questionText` llega en el step de la pregunta y `transcript` en 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`

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[]`.

```json
{ "session": { "effective_active_attention": { "v": 83.33, "n": 1247 } } }
```

- `v` va de 0 a 100: el porcentaje de los frames medidos de la sesión con `Attention = 1`, y no es la media de 0 a 1 de `aggResults.mean.Attention`.
- `n` es 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.
- `null` significa que no se midió (que no es 0) o que tu contexto no lo incluye. En la ruta de interrupción es `null`.
- También puede llegar `null` en la lectura justo tras el Final, aunque se midiera (visto en el Engine de pruebas, por la vía del SDK): vuelve a leer `/results` un poco después antes de darlo por ausente.

### 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[]`](#campos-en-preview), con interpretación) y [`session`](#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

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.

> La lista de indicadores públicos es provisional: qué HCIs son públicos se está confirmando con Engine. Cuáles recibes depende del contexto y del acuerdo de tu organización, que puede cambiar. Que tu código tolere un indicador que aparece o desaparece.

## 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](/docs/es/resources/migration/)). Nunca lo trates como la interpretación.

## 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](/docs/es/guides/show-results/#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](/docs/es/guides/show-results/#qué-enseñar-primero)). |
| `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](/docs/es/guides/show-results/#qué-enseñar-primero)).

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](/docs/es/resources/pitfalls/#pf-two-interpretations). `/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.

```json
{
  "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.

```json
{
  "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](/docs/es/sdk/errors/#en-el-dispositivo) 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

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](/docs/es/guides/show-results/#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](/docs/es/guides/show-results/#por-step-o-por-pregunta).

### 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.

```json
{
  "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`. Si `label` es `null` y la quieres, pide una interpretación nueva desde tu backend (`reAnalyze`).
- **No llega** en las interpretaciones guardadas antes de que el índice existiera (un `/analyze` que sirve una, `from_cache: true`, llega sin él; un `reAnalyze` lo trae, salvo que Engine conserve la anterior, `re_analyze_kept_previous: true`), ni en `GET /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

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:

```json
{ "userProtocolId": "<UP>", "protocolMechanicId": "<PM>", "reAnalyze": true }
```

- La respuesta lleva `from_cache: false` y 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 sin `reAnalyze` la devuelve, con `from_cache: true`.
- Solo afecta a la audiencia que pides, la `audience` de 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: `REANALYZE` o `ReAnalyze` reciben un `400` (`Unknown key 'REANALYZE': the field is 'reAnalyze', with that exact casing.`).
- **Cada `reAnalyze` genera 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 antes `from_cache`: con `true`, es la misma interpretación que ya tenías.
- Solo desde tu backend. El [proxy](/docs/es/api/proxy/) lo quita de los cuerpos de `/analyze` del 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](/docs/es/guides/show-results/#qué-guardar-y-cómo-releer-sin-pagar)).

## Qué no devuelve Engine

No hay agregado de todo un protocolo, ni webhooks, ni audio.

## 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`):

```json
{
  "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](/docs/es/sdk/errors/#avisos-que-conviene-mostrar).
