Preguntas

Preguntas de choice, score y probability — instrucciones y criterios estructurados, qué devuelve la API para cada una, niveles ponderados, la opción reservada other y la confianza mínima.

Las preguntas son lo que una decisión responde sobre el estado. Una decisión tiene de 1 a 64 preguntas, todas respondidas en una sola llamada al motor: Jev evalúa cada una de forma independiente y en paralelo sobre el mismo estado. Cada pregunta se convierte en una clave de los objetos result y confidence de la respuesta, en el orden en que las defines.

TipoÚsala pararesult[key]Ejemplo
choiceElegir una opción: un equipo, una categoría, una herramientaUno de tus valores de opción (string)"sales"
scoreUbicar el estado en una escala ordenadaLa etiqueta del nivel más probable (string)"high"
probabilityUna pregunta de sí/noProbabilidad de sí, de 0 a 10.9412

Propiedades comunes

PropiedadTipoObligatoriaDescripción
keystringSísnake_case, única en la decisión. Se convierte en la clave JSON de la respuesta.
typestringSíchoice, score o probability.
instructionsstring, object o arraySíLa pregunta que responde el motor: texto o JSON estructurado. Hasta 8,000 caracteres (el JSON cuenta su longitud serializada).
minConfidencenumberNoDe 0 a 1. Por debajo, la decisión aplica la acción de fallback — consulta más abajo.

Choice

{
  "key": "route",
  "type": "choice",
  "instructions": "Which team should receive this lead?",
  "options": [
    { "value": "sales", "description": "high intent, ready to talk to sales" },
    { "value": "sdr", "description": "some intent, needs qualification" },
    { "value": "nurture", "description": "early stage, send content" }
  ]
}
  • options necesita al menos 2 y como máximo 254 opciones, más other — 255 en total, el máximo de Jev.
  • value sigue las reglas de las claves y debe ser único dentro de la pregunta.
  • description le dice al motor cuándo aplica la opción: texto o JSON, hasta 2,000 caracteres. Es opcional — omítela, o ponla en null, cuando el valor lo dice todo ("yes_refund"). Las descripciones definen la precisión: contrasta las opciones parecidas y agrega exclusiones como "no para clientes existentes".
  • El orden importa. Jev puede inclinarse hacia la opción que aparece primero. Prueba las preguntas importantes con las opciones reordenadas en el Playground y verifica que la respuesta no cambie.

La opción reservada other

Toda pregunta de choice tiene una opción other. Dcision la agrega automáticamente como la última opción, con la descripción none of the options above. No se puede quitar, pero puedes describirla tú mismo incluyéndola en options — donde sea que la pongas, se mueve al final:

{ "value": "other", "description": "not about our product, or a language we don't support" }

Sin other, un motor se ve obligado a elegir la opción menos equivocada. Con ella, "ninguna de estas" se convierte en una respuesta explícita: cuando una pregunta de choice responde other y ninguna política coincidió antes, la decisión aplica su acción de fallback con action_reason.type = "other_option". Consulta Políticas y acciones.

Qué devuelve la API

  • result.route — la opción elegida, por ejemplo "sales" (o "other").
  • confidence.route — cuánto se destaca la opción elegida por encima de un reparto parejo entre todas las opciones, de 0 a 1 — consulta Confianza.
  • Con ?include=probabilities, probabilities.route contiene una probabilidad por opción, other incluida.

Las políticas sobre una respuesta de choice solo pueden usar eq y neq. La comparación ignora mayúsculas/minúsculas y los espacios alrededor.

Score

{
  "key": "priority",
  "type": "score",
  "instructions": "How urgent is it to answer this lead?",
  "scale": ["low", "medium", "high", "critical"]
}
  • scale lista de 2 a 10 niveles, del más bajo al más alto. Un nivel es una etiqueta (hasta 2,000 caracteres) o una rúbrica estructurada con un label. Las etiquetas deben ser únicas.
  • result.priority es la etiqueta del nivel más probable — no un promedio — y confidence.priority indica qué tan concentrada está la distribución a su alrededor.
  • scores.priority es el nivel ponderado: el promedio de los niveles ponderado por probabilidad, contando desde 1. En la escala de arriba, 2.81 queda entre medium (2) y high (3), más cerca de high. Úsalo para actuar entre niveles.
  • Con ?include=probabilities, probabilities.priority contiene una probabilidad por etiqueta, en el orden de la escala.

Las políticas comparan niveles, numerados desde 1: en la escala de arriba low es 1 y critical es 4.

  • Sobre la respuesta ("on": "output"), una regla usa el número de nivel ("value": 3) o la etiqueta ("value": "high"), con cualquier operador: { "field": "priority", "operator": "gte", "value": "high", "action": "escalate" } coincide con high y critical. Una etiqueta que no está en la escala nunca coincide.
  • Sobre el nivel ponderado ("on": "score"), una regla compara scores.priority con un número: { "field": "priority", "on": "score", "operator": "gte", "value": 3.5, "action": "escalate" } se activa cuando el peso se inclina hacia critical, aunque high sea el nivel más probable.

Probability

{
  "key": "purchase_intent",
  "type": "probability",
  "instructions": "Does this lead have real intent to buy in the next 30 days?",
  "criteria": {
    "yes": "asks for pricing, a demo, a quote or a start date",
    "no": "just browsing, student, vendor or spam"
  }
}
  • criteria.yes y criteria.no son opcionales — texto o JSON, hasta 2,000 caracteres cada uno — e indican qué cuenta como sí y como no. Mantenlos alineados con las instrucciones: yes debe describir el caso del sí.
  • result.purchase_intent es la probabilidad de sí, entre 0 y 1, redondeada a 4 decimales.
  • confidence.purchase_intent es |2p − 1|: la distancia a un cara o cruz. 0.03 (un no seguro) y 0.97 (un sí seguro) tienen ambos confianza 0.94; 0.5 tiene confianza 0.
  • Con ?include=probabilities, probabilities.purchase_intent es { "yes": p, "no": 1 − p }.

Las políticas comparan la probabilidad con un número, por ejemplo { "field": "purchase_intent", "operator": "gte", "value": 0.8, "action": "continue" }.

Instrucciones y criterios estructurados

Jev lee estructura de forma nativa. Dondequiera que una pregunta tenga texto — instructions, la description de una opción, los niveles de score, criteria.yes y criteria.no — puedes enviar en su lugar un objeto o array JSON. La estructura ayuda cuando una pregunta tiene varias partes, o cuando necesita datos de apoyo como una taxonomía, un schema o una fila de base de datos: las claves etiquetan cada parte.

{
  "key": "duplicate_candidate",
  "type": "probability",
  "instructions": {
    "potential_duplicate": { "name": "John Smith", "location": "Oakland, California", "last_employer": "Google" },
    "question": "Is the resume in `resume` for the same person as `potential_duplicate`?"
  }
}
  • Señala los datos con backticks. Nombra los campos del estado y las claves de la instrucción entre backticks — `resume`, `ticket.messages[0].text` — para decirle al motor exactamente qué mirar.
  • Dale una rúbrica a las opciones. Una descripción de opción como { "what": "Charges, invoices, refunds", "not_for": "Order tracking", "examples": ["I was charged twice"] } afina el límite entre opciones vecinas.
  • Los límites son los mismos que para el texto, medidos sobre el JSON serializado: 8,000 caracteres para las instrucciones, 2,000 para una descripción de opción, un nivel de score o un criterio. Los objetos y arrays no pueden estar vacíos.
  • En el editor, pega un objeto o array JSON en el campo: se guarda como estructura y se marca como estructurada. Cualquier cosa que no sea JSON válido sigue siendo texto.

Niveles de score estructurados

Un nivel de score puede ser un objeto con un label — la etiqueta es lo que devuelve result y lo que comparan las políticas; el objeto completo es lo que lee el motor:

{
  "key": "bug_severity",
  "type": "score",
  "instructions": "If this describes a bug, how severe is it for the customer?",
  "scale": ["cosmetic", "minor", "major", { "label": "critical", "rubric": "outage, data loss, security issue or money at risk" }]
}

La etiqueta tiene de 1 a 255 caracteres; el nivel completo, serializado, hasta 2,000. Los niveles simples y estructurados se pueden mezclar en una misma escala. El editor agrega los niveles como etiquetas simples y muestra los estructurados con un ícono de llaves — la plantilla Support Ticket Triage empieza con uno.

Confianza mínima

Cualquier pregunta puede definir minConfidence entre 0 y 1. Cuando la confianza de la respuesta está por debajo y ninguna política coincidió antes, la decisión aplica su acción de fallback con action_reason.type = "low_confidence":

{ "type": "low_confidence", "question": "route", "confidence": 0.52, "minConfidence": 0.8 }

En el editor, el interruptor Confianza mínima empieza en 80%. Sin él, las respuestas de baja confianza siguen con continue.

Para una pregunta de probability, la confianza es |2p − 1|, así que una confianza mínima marca una franja de probabilidades alrededor de 0.5: 0.8 marca todo p entre 0.1 y 0.9, 0.6 todo p entre 0.2 y 0.8. El editor muestra la franja junto al control deslizante. Consulta Confianza y probabilidades y Manejar la baja confianza y other.

Consejos

  • Pregunta una sola cosa por pregunta. Divide "¿es spam urgente?" en una probability (spam) y un score (urgency) — cuestan una sola llamada de cualquier forma.
  • Formula las instrucciones como una pregunta literal sobre el estado: "¿Qué equipo debe recibir este lead?".
  • Prefiere probability para sí/no — es más fácil poner un umbral a un número que a un choice de dos opciones.
  • Prefiere score para niveles ordenados — así las políticas pueden usar gte/lte sobre el nivel y umbrales sobre el nivel ponderado.
  • Escribe las descripciones de las opciones como criterios, no como etiquetas, y haz que las vecinas sean mutuamente excluyentes. Si el Playground señala un casi empate, las descripciones se superponen.
  • Pon los hechos del negocio en context, no en cada instrucción.
  • Deja las cuentas, los conteos y las fechas en el código y envía los resultados en el estado.
  • El orden importa: cuando varias preguntas responden other o quedan por debajo de su confianza mínima, la primera en el orden de las preguntas es la que se informa en action_reason.

Más en Escribir buenas preguntas.

En esta página