Esquema de decisión

El documento JSON detrás de cada decisión — el estado que acepta, las preguntas que responde, los compuestos, las políticas que eligen la acción, la configuración de runtime y los destinos.

Una decisión se define con un único documento JSON, el esquema de decisión. El editor y el constructor visual lo editan por ti (el panel de la derecha lo muestra en Schema de la decisión), la CLI lo genera y lo valida sin conexión, y cada versión desplegada guarda un snapshot completo de él.

El esquema es neutral respecto al motor: nada en él es específico de Jev ni de ningún otro motor.

Un ejemplo completo

Esta es la plantilla Calificación de leads tal como se guarda, con todos los valores predeterminados completados:

decision.json
{
  "stateSchema": {
    "kind": "object",
    "fields": [
      { "key": "message", "type": "string", "required": true, "description": "Inbound lead message" },
      { "key": "company_size", "type": "number", "required": false, "description": "Employee count" },
      { "key": "source", "type": "string", "required": false, "description": "website, referral, ads…" }
    ]
  },
  "questions": [
    {
      "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"
      }
    },
    {
      "key": "priority",
      "type": "score",
      "instructions": "How urgent is it to answer this lead?",
      "scale": ["low", "medium", "high", "critical"]
    },
    {
      "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" },
        { "value": "spam", "description": "spam, vendor pitch or irrelevant" },
        { "value": "other", "description": "none of the options above" }
      ]
    }
  ],
  "composites": [
    {
      "key": "lead_score",
      "description": "0–1 ranking: intent counts double, priority adds, spam-like routes don't count",
      "terms": [
        { "question": "purchase_intent", "weight": 2 },
        { "question": "priority", "weight": 1 },
        { "question": "route", "option": "sales", "weight": 1 }
      ]
    }
  ],
  "policies": [
    { "field": "route", "on": "output", "operator": "eq", "value": "spam", "action": "block" },
    { "field": "purchase_intent", "on": "confidence", "operator": "lt", "value": 0.6, "action": "escalate" }
  ],
  "settings": {
    "storeInput": true,
    "storeOutput": true,
    "timeoutMs": 5000,
    "fallbackAction": "escalate",
    "onEngineError": "error"
  }
}

Campos de nivel superior

CampoTipoObligatorioDescripción
stateSchemaobjectSíLa entrada que acepta la decisión — consulta Esquema del estado.
questionsarraySíDe 1 a 64 preguntas — consulta Preguntas.
compositesarrayNoHasta 20 combinaciones ponderadas de respuestas. Predeterminado [] — consulta Compuestos.
policiesarrayNoHasta 50 reglas, evaluadas en orden. Predeterminado [] — consulta Políticas y acciones.
contextstringNoHasta 8,000 caracteres de contexto de negocio enviados con cada estado — consulta Contexto.
settingsobjectNoMotor, almacenamiento, presupuesto de tiempo, acción de fallback y comportamiento ante errores del motor — consulta Configuración de la decisión.
destinationsarrayNoHasta 20 destinos — qué pasa después de la decisión, por opción, nivel, umbral o acción final. Predeterminado [] — consulta Destinos.

Claves

Los campos del estado, las claves de las preguntas, las claves de los compuestos y los valores de las opciones de choice comparten una misma regla, porque se convierten en claves y valores JSON en la respuesta de la API:

  • snake_case: empiezan con una letra minúscula, seguida de letras minúsculas, dígitos o _;
  • como máximo 48 caracteres (patrón ^[a-z][a-z0-9_]{0,47}$);
  • únicas: las claves de preguntas y compuestos dentro de la decisión, las claves de campo dentro del estado, los valores de opción dentro de una pregunta.

Esquema del estado

El estado es lo que tu aplicación envía en el body de la solicitud como { "state": … }. Elige uno de tres tipos — las mismas tres formas que Jev evalúa de forma nativa:

TipoEnvíaAdecuado para
objectun objeto JSON con campos tipadosla mayoría de las decisiones: los campos con nombre mantienen clara cada parte de la entrada
textun string no vacíoun mensaje, comentario o fragmento
listun array no vacío de strings u objetosla transcripción de un chat, un lote de registros

Estado de objeto

{ "kind": "object", "fields": [{ "key": "message", "type": "string", "required": true }] }

fields contiene hasta 50 definiciones de campo:

PropiedadTipoPredeterminadoDescripción
keystring—La clave JSON en el estado.
typestring—Uno de string, number, integer, boolean, array, object — o un archivo: image, audio, file (consulta Entradas).
requiredbooleanfalseRechaza los estados que no tienen este campo.
descriptionstring—Hasta 255 caracteres. Documenta el campo en el contrato de la API que muestra el editor.

Cómo se valida el estado antes de que se ejecute el motor:

  • el estado debe ser un objeto JSON (no un array, un string ni null);
  • un campo required debe estar presente y no ser null; un campo opcional puede faltar o ser null;
  • los tipos son estrictos: number es cualquier número finito, integer un número entero, object un objeto no nulo que no es un array — "500" no es un number; image, audio y file aceptan una URL data:, una URL https:// o { "data" | "url", "filename" };
  • los campos no declarados se aceptan y se reenvían al motor, así que puedes enviar contexto adicional sin cambiar el esquema;
  • se informa el primer campo que falla, por ejemplo 422 INVALID_STATE con "Field company_size must be a number.".

Las descripciones de campo son documentación

El motor recibe las claves y los valores de tu estado, el context de la decisión y las preguntas — no las descripciones de los campos. Dale al motor lo que necesita mediante nombres de campo descriptivos, context e instrucciones precisas, y refiérete a los campos por su nombre en las instrucciones: "Does `message` ask for a demo?".

Estado de texto

{ "kind": "text" }

El estado debe ser un string no vacío: { "state": "Congratulations! You won a $1000 gift card…" }. El motor recibe el propio string.

Estado de lista

{ "kind": "list", "items": "string" }

El estado debe ser un array no vacío de hasta 500 elementos. items define qué es cada elemento:

itemsCada elemento debe serEstado de ejemplo
string (predeterminado)un string["Hi!", "My card was charged twice.", "Can you refund one?"]
objectun objeto JSON (no null, no un array)[{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }]

El motor recibe el propio array. Los errores nombran el problema: "Field state must be a non-empty array.", "Field state has too many items (612, max 500)." o "Item 2 of state must be an object.".

Una lista es un solo estado: cada pregunta se responde sobre la lista en su conjunto — "¿esta conversación pide un reembolso?" — no una vez por elemento. Para clasificar elementos de forma independiente, envía una decisión por elemento, o usa un estado de objeto como { "messages": [ … ] } con una pregunta por posición ("Is `messages[2]` a complaint?").

Límites de tamaño

El estado serializado debe caber en 128 KB y en unos 32,000 tokens (estimados como caracteres ÷ 4) — sin contar sus archivos, que tienen sus propios límites (20 MB cada uno; su texto se recorta para que quepa — consulta Entradas).

Jev también tiene un presupuesto de tokens para toda la llamada: unos 32,000 tokens para el estado más la pregunta más larga y 64,000 tokens para el estado más todas las preguntas. Dcision comprueba ambos antes de llamar al motor; un estado que supera los límites falla con 422 INVALID_STATE y un mensaje que indica qué límite se alcanzó — por ejemplo "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." Consulta Límites.

Contexto

context es texto libre, de hasta 8,000 caracteres, enviado con cada estado bajo la clave reservada decision_context — por ejemplo "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." Describe el negocio, no la respuesta esperada.

Cómo lo recibe el motor:

Tipo de estadoQué evalúa el motor cuando context está definido
objecttu objeto más un campo decision_context
text, list{ "decision_context": "<context>", "input": <your state> }

Sin context, el motor recibe tu estado sin cambios.

decision_context está reservado: cuando la decisión tiene un context, este reemplaza un campo decision_context que tu aplicación envíe en un estado de objeto. Cualquier otro campo — incluido uno llamado context — se reenvía tal cual.

Entradas estructuradas

Las instrucciones, las descripciones de las opciones de choice, los niveles de score y los criterios de probability aceptan objetos o arrays JSON además de texto — Jev lee estructuras de forma nativa. Úsalo para etiquetar las partes de una pregunta larga, para pasar datos de apoyo o para dar a cada opción una rúbrica. Consulta Instrucciones y criterios estructurados.

Validación

Las mismas reglas se aplican en todas partes:

  • Editor — valida mientras escribes, muestra cada problema con un enlace Ir al error y solo guarda automáticamente los borradores válidos.

  • API — guardar o desplegar un esquema no válido falla con 422 INVALID_SCHEMA; details lista cada problema con su ruta:

    {
      "error": {
        "code": "INVALID_SCHEMA",
        "message": "The decision schema is invalid.",
        "request_id": "req_7Gm2xPq9Lk4sVt1RbN8w",
        "details": [
          { "path": "questions.0.options", "message": "Add at least 2 options (besides \"other\")." },
          { "path": "policies.1.field", "message": "Unknown question \"intent\"." },
          { "path": "composites.0.terms.2.option", "message": "Pick the option whose probability counts." }
        ]
      }
    }
  • CLI — dcision validate decision.json comprueba un archivo sin conexión, y dcision check-state comprueba un estado contra él.

Las reglas de validación pueden volverse más estrictas con el tiempo — desde la v0.3, por ejemplo, los valores de las reglas se comprueban contra las opciones, los niveles y los rangos con los que se comparan ("Use a number between 0 and 1 (e.g. 0.7, not 70)."). Las reglas más estrictas se aplican cuando guardas o despliegas; las versiones ya desplegadas siguen ejecutándose sin cambios, así que una regla endurecida nunca convierte un endpoint en vivo en un error.

El contrato de la API

La vista Contrato de la API del editor muestra aquello con lo que pueden contar los clientes de la decisión: el estado como JSON Schema, la forma de la respuesta de cada pregunta y los compuestos.

{
  "name": "lead-qualification",
  "state": {
    "type": "object",
    "required": ["message"],
    "properties": {
      "message": { "type": "string", "description": "Inbound lead message" },
      "company_size": { "type": "number", "description": "Employee count" },
      "source": { "type": "string", "description": "website, referral, ads…" }
    }
  },
  "questions": {
    "purchase_intent": { "type": "probability", "range": [0, 1] },
    "priority": { "type": "score", "scale": ["low", "medium", "high", "critical"] },
    "route": { "type": "choice", "options": ["sales", "sdr", "nurture", "spam", "other"] }
  },
  "composites": {
    "lead_score": { "type": "number" }
  }
}

Un estado de texto se muestra como { "type": "string" } y un estado de lista como { "type": "array", "items": { "type": "string" } } (o "object"). Las escalas de score listan las etiquetas de los niveles, también para los niveles estructurados. composites solo aparece cuando la decisión tiene alguno.

En esta página