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

# Configuración de Modelos

> Guía paso a paso para configurar un modelo de análisis completo

## Introducción

Esta guía te llevará a través del proceso completo de configuración de un modelo de análisis, desde la planificación inicial hasta tu primer análisis de prueba.

<Info>
  Un modelo bien configurado es la base para obtener análisis precisos y relevantes de tus llamadas.
</Info>

## Flujo de Configuración

```mermaid theme={null}
flowchart LR
    A[Planificar] --> B[Crear Modelo]
    B --> C[Agregar Categorías]
    C --> D[Definir Variables]
    D --> E[Configurar Metadata]
    E --> F[Verificar]
    F --> G[Probar]

    style A fill:#4A90D9,stroke:#333,color:#fff
    style B fill:#5B6EE1,stroke:#333,color:#fff
    style C fill:#5B6EE1,stroke:#333,color:#fff
    style D fill:#5B6EE1,stroke:#333,color:#fff
    style E fill:#5B6EE1,stroke:#333,color:#fff
    style F fill:#00D4FF,stroke:#333
    style G fill:#00D4FF,stroke:#333
```

***

## 1. Planificación del Modelo

Antes de crear tu modelo, define claramente:

<CardGroup cols={2}>
  <Card title="Objetivo" icon="bullseye">
    ¿Qué quieres medir? ¿Calidad de servicio, cumplimiento de script, habilidades de venta?
  </Card>

  <Card title="Tipo de Llamadas" icon="phone">
    ¿Servicio al cliente, ventas, soporte técnico, cobranza?
  </Card>

  <Card title="Criterios Clave" icon="list-check">
    ¿Cuáles son los comportamientos críticos que deben evaluarse?
  </Card>

  <Card title="Segmentación" icon="filter">
    ¿Cómo querrás filtrar y agrupar los análisis? ¿Por campaña, producto, región?
  </Card>
</CardGroup>

### Ejemplo de Planificación

Para un modelo de **Evaluación de Ventas**:

| Aspecto         | Definición                                                  |
| --------------- | ----------------------------------------------------------- |
| Objetivo        | Evaluar habilidades de venta y cumplimiento de protocolo    |
| Categorías      | Apertura, Descubrimiento, Presentación, Cierre              |
| Variables clave | Saludo, identificación de necesidades, manejo de objeciones |
| Metadata        | Campaña, producto, región                                   |

***

## 2. Crear el Modelo Base

### Desde la Aplicación Web

1. Navega a **Configuración** > **Modelos**
2. Haz clic en **+ Nuevo Modelo**
3. Completa la información básica:
   * **Nombre**: Identificador único (ej: "Evaluación Ventas Q1")
   * **Descripción**: Propósito del modelo
   * **Prompt**: Instrucciones para el análisis de IA

### Vía API

```bash theme={null}
POST /v1/models
```

```json theme={null}
{
  "name": "Evaluación Ventas Q1",
  "description": "Modelo para evaluar llamadas del equipo de ventas durante Q1",
  "prompt": "Evalúa esta llamada de ventas considerando: saludo profesional, identificación de necesidades del cliente, presentación de beneficios, manejo de objeciones y cierre efectivo."
}
```

**Respuesta:**

```json theme={null}
{
  "id": 15,
  "name": "Evaluación Ventas Q1",
  "description": "Modelo para evaluar llamadas del equipo de ventas durante Q1",
  "prompt": "...",
  "created_at": "2025-01-20T10:00:00Z"
}
```

<Tip>
  Guarda el `id` del modelo (15 en este ejemplo) — lo necesitarás para los siguientes pasos.
</Tip>

***

## 3. Definir Categorías

Las categorías organizan tu evaluación en fases lógicas de la llamada.

### Estructura Recomendada

| Categoría      | Descripción                     | Peso Sugerido |
| -------------- | ------------------------------- | ------------- |
| Apertura       | Saludo e identificación         | 15-20%        |
| Descubrimiento | Identificación de necesidades   | 20-25%        |
| Presentación   | Exposición de solución/producto | 25-30%        |
| Cierre         | Confirmación y próximos pasos   | 25-30%        |

### Crear Categoría vía API

```bash theme={null}
POST /v1/models/15/categories
```

```json theme={null}
{
  "name": "Apertura",
  "description": "Evaluación del saludo e identificación inicial",
  "order_number": 1
}
```

**Respuesta:**

```json theme={null}
{
  "id": 42,
  "model_id": 15,
  "name": "Apertura",
  "description": "Evaluación del saludo e identificación inicial",
  "order_number": 1
}
```

<Note>
  Repite este proceso para cada categoría. El `order_number` determina el orden de aparición en los reportes.
</Note>

### Ejemplo Completo de Categorías

```python theme={null}
categories = [
    {"name": "Apertura", "description": "Saludo e identificación", "order_number": 1},
    {"name": "Descubrimiento", "description": "Identificación de necesidades", "order_number": 2},
    {"name": "Presentación", "description": "Exposición de la solución", "order_number": 3},
    {"name": "Cierre", "description": "Confirmación y siguientes pasos", "order_number": 4}
]

for cat in categories:
    response = requests.post(
        f"{base_url}/v1/models/15/categories",
        headers=headers,
        json=cat
    )
    print(f"Creada categoría: {response.json()['name']} (ID: {response.json()['id']})")
```

***

## 4. Agregar Variables

Las variables son los criterios específicos de evaluación dentro de cada categoría.

### Tipos de Variables

| Tipo      | Uso                        | Ejemplo                          |
| --------- | -------------------------- | -------------------------------- |
| `INTEGER` | Puntuación numérica (0-10) | Calidad del saludo               |
| `BOOLEAN` | Sí/No                      | ¿Mencionó el nombre del cliente? |
| `STRING`  | Texto extraído             | Producto de interés              |
| `DECIMAL` | Puntuación con decimales   | Score de empatía                 |

### Crear Variable vía API

```bash theme={null}
POST /v1/models/15/variables
```

```json theme={null}
{
  "key": "greeting_quality",
  "readable_name": "Calidad del Saludo",
  "description": "Evalúa si el agente saludó de forma profesional y cordial",
  "type": "INTEGER",
  "weight": 10,
  "category_id": 42,
  "required": true
}
```

**Respuesta:**

```json theme={null}
{
  "id": 101,
  "model_id": 15,
  "category_id": 42,
  "key": "greeting_quality",
  "readable_name": "Calidad del Saludo",
  "description": "Evalúa si el agente saludó de forma profesional y cordial",
  "type": "INTEGER",
  "weight": 10,
  "required": true
}
```

### Distribución de Pesos

<Warning>
  La suma de los pesos de todas las variables debe ser coherente con tu escala de evaluación (típicamente 100 puntos total).
</Warning>

**Ejemplo de distribución:**

<Tree>
  <Tree.Folder name="Total: 100 puntos" defaultOpen>
    <Tree.Folder name="Apertura: 20 puntos" defaultOpen>
      <Tree.File name="Calidad del saludo: 10" />

      <Tree.File name="Identificación correcta: 10" />
    </Tree.Folder>

    <Tree.Folder name="Descubrimiento: 25 puntos" defaultOpen>
      <Tree.File name="Preguntas abiertas: 10" />

      <Tree.File name="Escucha activa: 10" />

      <Tree.File name="Resumen de necesidades: 5" />
    </Tree.Folder>

    <Tree.Folder name="Presentación: 30 puntos" defaultOpen>
      <Tree.File name="Presentación de beneficios: 15" />

      <Tree.File name="Manejo de objeciones: 15" />
    </Tree.Folder>

    <Tree.Folder name="Cierre: 25 puntos" defaultOpen>
      <Tree.File name="Propuesta clara: 10" />

      <Tree.File name="Confirmación de próximos pasos: 15" />
    </Tree.Folder>
  </Tree.Folder>
</Tree>

### Variables de Extracción

Además de variables de puntuación, puedes extraer información:

```json theme={null}
{
  "key": "product_interest",
  "readable_name": "Producto de Interés",
  "description": "El producto principal que el cliente mencionó o mostró interés",
  "type": "STRING",
  "weight": 0,
  "category_id": 43,
  "required": false
}
```

<Info>
  Las variables con `weight: 0` no afectan el NeuraScore pero capturan información valiosa.
</Info>

***

## 5. Configurar Metadata

La metadata permite segmentar y filtrar análisis en dashboards.

### Campos Comunes de Metadata

| Campo    | Descripción          | Uso                                 |
| -------- | -------------------- | ----------------------------------- |
| campaign | Nombre de la campaña | Comparar rendimiento entre campañas |
| product  | Producto o servicio  | Análisis por línea de producto      |
| region   | Región geográfica    | Comparativas regionales             |
| team     | Equipo o supervisor  | Métricas por equipo                 |

### Crear Campo de Metadata vía API

```bash theme={null}
POST /v1/models/15/metadata
```

```json theme={null}
{
  "key": "campaign",
  "readable_name": "Campaña",
  "type": "STRING",
  "grouping_field": true
}
```

**Respuesta:**

```json theme={null}
{
  "id": 201,
  "model_id": 15,
  "key": "campaign",
  "readable_name": "Campaña",
  "type": "STRING",
  "grouping_field": true
}
```

<Tip>
  Los campos con `grouping_field: true` aparecerán como opciones de filtro en los dashboards.
</Tip>

***

## 6. Verificar la Configuración

Antes de usar el modelo, verifica que todo esté correcto.

### Obtener Modelo Completo

```bash theme={null}
GET /v1/models/15
```

Esto devuelve el modelo con todas sus categorías, variables y metadata.

### Checklist de Verificación

<Steps>
  <Step title="Información del Modelo">
    ✓ Nombre descriptivo y único

    ✓ Descripción clara del propósito

    ✓ Prompt con instrucciones específicas
  </Step>

  <Step title="Categorías">
    ✓ Cubren todas las fases de la llamada

    ✓ Orden lógico establecido

    ✓ Descripciones claras
  </Step>

  <Step title="Variables">
    ✓ Cada categoría tiene variables asignadas

    ✓ Los pesos suman el total esperado

    ✓ Tipos correctos (INTEGER, BOOLEAN, STRING)

    ✓ Variables requeridas marcadas
  </Step>

  <Step title="Metadata">
    ✓ Campos de segmentación necesarios

    ✓ Campos de agrupación habilitados
  </Step>
</Steps>

***

## 7. Primer Análisis de Prueba

Una vez verificado el modelo, realiza un análisis de prueba.

### Crear Análisis de Prueba

```bash theme={null}
POST /v1/call-analysis
```

Con los parámetros:

* `audio_file`: Archivo de audio de una llamada representativa
* `model_name`: "Evaluación Ventas Q1"
* `agent_id` y `agent_name`: Datos del agente
* `additional_parameters`: Metadata (campaña, producto, etc.)

### Evaluar Resultados

Revisa el análisis generado:

1. **NeuraScore**: ¿El puntaje refleja la calidad real de la llamada?
2. **Variables**: ¿Los valores capturados son correctos?
3. **Insights**: ¿Las observaciones son relevantes?

<Warning>
  Si los resultados no son los esperados, ajusta las descripciones de las variables o el prompt del modelo.
</Warning>

***

## Errores Comunes

### Error 409: Modelo con Análisis Existentes

```json theme={null}
{
  "detail": "Cannot modify model with existing analyses"
}
```

**Solución**: Una vez que un modelo tiene análisis asociados, no se pueden modificar sus variables ni categorías. Crea una nueva versión del modelo si necesitas hacer cambios estructurales.

### Variables sin Categoría

Las variables **deben** estar asociadas a una categoría válida del modelo.

### Pesos Desbalanceados

Si los pesos no suman 100, el NeuraScore podría no reflejar correctamente la evaluación.

***

## Recursos Relacionados

<CardGroup cols={2}>
  <Card title="API de Modelos" icon="code" href="/api-reference/models/create">
    Referencia completa de la API
  </Card>

  <Card title="Conceptos: Modelos" icon="book" href="/concepts/analysis-models">
    Fundamentos de los modelos de análisis
  </Card>

  <Card title="Categorías" icon="folder-tree" href="/concepts/model-categories">
    Guía detallada de categorías
  </Card>

  <Card title="Variables" icon="list-check" href="/concepts/model-variables">
    Tipos y configuración de variables
  </Card>
</CardGroup>