> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuracall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables de Modelo

> Criterios de evaluación y extracción de datos dentro de modelos de análisis

## ¿Qué son las Variables?

Las variables son los **criterios específicos que el sistema evalúa** durante el análisis de una llamada. Cada variable representa un aspecto medible del desempeño del agente o un dato a extraer de la conversación.

Existen dos tipos principales de variables:

<CardGroup cols={2}>
  <Card title="Variables de Puntuación" icon="star">
    Evalúan el desempeño del agente con un valor numérico que contribuye al NeuraScore
  </Card>

  <Card title="Variables de Extracción" icon="database">
    Capturan información específica mencionada durante la llamada
  </Card>
</CardGroup>

## Tipos de Datos Soportados

| Tipo       | Descripción           | Ejemplo de Uso                               |
| ---------- | --------------------- | -------------------------------------------- |
| `INTEGER`  | Números enteros       | Puntuación 0-10, cantidad de productos       |
| `DECIMAL`  | Números con decimales | Porcentaje de cumplimiento, monto en dólares |
| `BOOLEAN`  | Verdadero/Falso       | ¿Mencionó promoción?, ¿Cliente satisfecho?   |
| `STRING`   | Texto libre           | Nombre del producto, motivo de llamada       |
| `DATE`     | Fecha                 | Fecha de próximo contacto                    |
| `TIME`     | Hora                  | Hora preferida de contacto                   |
| `DATETIME` | Fecha y hora          | Momento del compromiso de pago               |

## Variables de Puntuación

Las variables de puntuación miden aspectos cualitativos del desempeño y contribuyen al **NeuraScore** final de la llamada.

### Estructura de una Variable de Puntuación

| Campo           | Tipo    | Descripción                              | Requerido |
| --------------- | ------- | ---------------------------------------- | --------- |
| `key`           | string  | Identificador único (snake\_case)        | Sí        |
| `readable_name` | string  | Nombre legible para reportes             | Sí        |
| `description`   | string  | Instrucciones para el evaluador IA       | Sí        |
| `type`          | string  | Tipo de dato (INTEGER, DECIMAL, BOOLEAN) | Sí        |
| `weight`        | decimal | Peso en el cálculo del NeuraScore        | Sí        |
| `category_id`   | uuid    | Categoría a la que pertenece             | Sí        |
| `required`      | boolean | Si debe evaluarse siempre                | No        |

### Ejemplo: Variables de Apertura

<Tree>
  <Tree.Folder name="Categoría: Apertura" defaultOpen>
    <Tree.File name="saludo_corporativo (peso: 2.0)" />

    <Tree.File name="identificacion_agente (peso: 1.5)" />

    <Tree.File name="deteccion_necesidad (peso: 2.5)" />

    <Tree.File name="tono_amable (peso: 1.0)" />
  </Tree.Folder>
</Tree>

### El Campo `description`

La descripción es **crucial** porque instruye a la IA sobre cómo evaluar. Debe ser:

<Steps>
  <Step title="Observable">
    Basada en comportamientos que se pueden escuchar en la llamada.
  </Step>

  <Step title="Específica">
    Clara sobre qué constituye cumplimiento total, parcial o nulo.
  </Step>

  <Step title="Medible">
    Con criterios objetivos que no dependan de interpretación subjetiva.
  </Step>
</Steps>

**Ejemplo de buena descripción:**

```
Evalúa si el agente utilizó el saludo corporativo completo.
- Puntuación 10: Dijo "Bienvenido a [Empresa], mi nombre es [Nombre], ¿en qué puedo ayudarle?"
- Puntuación 5: Saludó pero omitió algún elemento del script
- Puntuación 0: No realizó saludo o fue informal
```

## Variables de Extracción

Las variables de extracción capturan **datos específicos** mencionados durante la conversación. No contribuyen al NeuraScore pero son valiosas para análisis y reportes.

### Casos de Uso

<CardGroup cols={2}>
  <Card title="Intención del Cliente" icon="lightbulb">
    Capturar el motivo principal de la llamada
  </Card>

  <Card title="Productos Mencionados" icon="box">
    Registrar productos o servicios discutidos
  </Card>

  <Card title="Compromisos" icon="handshake">
    Extraer fechas de seguimiento o pagos prometidos
  </Card>

  <Card title="Datos de Contacto" icon="phone">
    Capturar información actualizada del cliente
  </Card>
</CardGroup>

### Ejemplo: Variables de Extracción para Cobranza

<Tree>
  <Tree.Folder name="Modelo: Cobranza" defaultOpen>
    <Tree.File name="motivo_no_pago (STRING)" />

    <Tree.File name="fecha_compromiso_pago (DATE)" />

    <Tree.File name="monto_prometido (DECIMAL)" />

    <Tree.File name="cliente_confirmo_datos (BOOLEAN)" />
  </Tree.Folder>
</Tree>

## Gestión vía API

### Listar Variables de un Modelo

```bash theme={null}
GET /v1/models/{model_id}/variables
Authorization: Bearer <token>
```

### Crear una Variable de Puntuación

```bash theme={null}
POST /v1/models/{model_id}/variables
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "saludo_corporativo",
  "readable_name": "Saludo Corporativo",
  "description": "Evalúa si el agente utilizó el saludo corporativo completo según el script establecido. Puntuación 10 si es completo, 5 si es parcial, 0 si no lo realiza.",
  "type": "INTEGER",
  "weight": 2.0,
  "category_id": "uuid-de-categoria-apertura",
  "required": true
}
```

### Crear una Variable de Extracción

```bash theme={null}
POST /v1/models/{model_id}/variables
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "fecha_compromiso_pago",
  "readable_name": "Fecha de Compromiso de Pago",
  "description": "Extrae la fecha en que el cliente se comprometió a realizar el pago, si la mencionó durante la llamada.",
  "type": "DATE",
  "weight": 0,
  "category_id": "uuid-de-categoria-cierre",
  "required": false
}
```

<Note>
  Las variables de extracción típicamente tienen `weight: 0` ya que no contribuyen al NeuraScore.
</Note>

### Actualizar una Variable

```bash theme={null}
PUT /v1/models/{model_id}/variables/{variable_id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "key": "saludo_corporativo",
  "readable_name": "Saludo Corporativo Completo",
  "description": "Descripción actualizada con nuevos criterios...",
  "type": "INTEGER",
  "weight": 2.5,
  "category_id": "uuid-de-categoria-apertura",
  "required": true
}
```

## Restricciones Importantes

<Warning>
  **No se puede modificar ni eliminar una variable si el modelo tiene análisis existentes.**

  Esta restricción garantiza la integridad de los datos históricos. Los análisis completados
  mantienen su estructura original para que los reportes comparativos sean consistentes.
</Warning>

### ¿Qué hacer si necesitas modificar variables?

1. **Crear un nuevo modelo**: Duplica el modelo con las variables actualizadas
2. **Agregar variables**: Puedes agregar nuevas variables a modelos existentes
3. **Desactivar el modelo**: Desactiva el modelo actual y crea uno nuevo con la estructura deseada

## Distribución de Pesos

El `weight` determina cuánto impacta cada variable en el NeuraScore final. Considera:

<Steps>
  <Step title="Identifica variables críticas">
    ¿Cuáles son los comportamientos más importantes para el éxito de la llamada?
  </Step>

  <Step title="Asigna pesos proporcionales">
    Variables críticas: peso 2.0-3.0. Variables importantes: peso 1.0-2.0. Variables secundarias: peso 0.5-1.0.
  </Step>

  <Step title="Valida el balance">
    Ninguna variable debería dominar completamente el score. Revisa que la suma total refleje tus prioridades.
  </Step>

  <Step title="Ajusta por categoría">
    Considera si el peso total de cada categoría refleja su importancia relativa en la llamada.
  </Step>
</Steps>

## Mejores Prácticas

<CardGroup cols={2}>
  <Card title="Usa keys descriptivos" icon="key">
    `verifico_identidad` es mejor que `var_001`
  </Card>

  <Card title="Descripciones detalladas" icon="file-lines">
    Incluye ejemplos concretos de qué constituye cada nivel de puntuación
  </Card>

  <Card title="Agrupa lógicamente" icon="layer-group">
    Asigna cada variable a la categoría que corresponde a esa fase de la llamada
  </Card>

  <Card title="Limita la cantidad" icon="list-ol">
    5-15 variables por modelo es ideal. Demasiadas dificultan el análisis
  </Card>
</CardGroup>

## Relación con Otros Recursos

<CardGroup cols={2}>
  <Card title="Categorías de Modelo" icon="folder-tree" href="/concepts/model-categories">
    Agrupaciones que contienen las variables
  </Card>

  <Card title="API de Variables" icon="code" href="/api-reference/models/variables/list">
    Referencia completa de endpoints
  </Card>
</CardGroup>