Decision schema

O documento JSON por trás de toda decisão — o estado que ela aceita, as perguntas que responde, composites, as políticas que escolhem a ação, as configurações de runtime e os destinos.

Uma decisão é definida por um único documento JSON, o decision schema. O editor e o construtor visual o editam por você (o painel da direita o mostra em Schema da decisão), a CLI gera o esqueleto e o valida offline, e cada versão publicada guarda um snapshot completo dele.

O schema é neutro em relação ao engine: nada nele é específico do Jev ou de qualquer outro engine.

Um exemplo completo

Este é o template Qualificação de leads como ele fica guardado, com todos os padrões preenchidos:

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 primeiro nível

CampoTipoObrigatórioDescrição
stateSchemaobjectSimA entrada que a decisão aceita — veja State schema.
questionsarraySimDe 1 a 64 perguntas — veja Perguntas.
compositesarrayNãoAté 20 combinações ponderadas de respostas. Padrão [] — veja Composites.
policiesarrayNãoAté 50 regras, avaliadas em ordem. Padrão [] — veja Políticas e ações.
contextstringNãoAté 8.000 caracteres de contexto de negócio enviados com todo estado — veja Contexto.
settingsobjectNãoEngine, armazenamento, orçamento de tempo, ação de fallback e comportamento em erros de engine — veja Configurações da decisão.
destinationsarrayNãoAté 20 destinos — o que acontece depois da decisão, por opção, nível, limiar ou ação final. Padrão [] — veja Destinos.

Chaves

Os campos do estado, as chaves das perguntas, as chaves dos composites e os valores das opções de choice seguem uma mesma regra, porque viram chaves e valores JSON na resposta da API:

  • snake_case: começam com uma letra minúscula, seguida de letras minúsculas, dígitos ou _;
  • no máximo 48 caracteres (padrão ^[a-z][a-z0-9_]{0,47}$);
  • únicos: chaves de perguntas e de composites dentro da decisão, chaves de campos dentro do estado, valores de opções dentro de uma pergunta.

State schema

O estado é o que a sua aplicação envia no body da requisição como { "state": … }. Escolha um de três tipos — as mesmas três formas que o Jev avalia nativamente:

TipoEnvieBom para
objectum objeto JSON com campos tipadosa maioria das decisões: campos nomeados deixam cada parte da entrada clara
textuma string não vaziauma mensagem, um comentário ou um trecho
listum array não vazio de strings ou objetosa transcrição de um chat, um lote de registros

Estado de objeto

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

fields contém até 50 definições de campo:

PropriedadeTipoPadrãoDescrição
keystring—A chave JSON no estado.
typestring—Um de string, number, integer, boolean, array, object — ou um arquivo: image, audio, file (veja Entradas).
requiredbooleanfalseRejeita estados que não têm este campo.
descriptionstring—Até 255 caracteres. Documenta o campo no contrato da API mostrado pelo editor.

Como o estado é validado antes de o engine rodar:

  • o estado precisa ser um objeto JSON (não um array, uma string ou null);
  • um campo required precisa estar presente e não ser null; um campo opcional pode faltar ou ser null;
  • os tipos são estritos: number é qualquer número finito, integer um número inteiro, object um objeto não nulo que não é array — "500" não é um number; image, audio e file aceitam uma URL data:, uma URL https:// ou { "data" | "url", "filename" };
  • campos não declarados são aceitos e repassados ao engine, então você pode enviar contexto extra sem mudar o schema;
  • o primeiro campo que falhar é informado, por exemplo 422 INVALID_STATE com "Field company_size must be a number.".

As descrições dos campos são documentação

O engine recebe as chaves e os valores do seu estado, o context da decisão e as perguntas — não as descrições dos campos. Dê ao engine o que ele precisa por meio de nomes de campos descritivos, context e instruções precisas, e cite os campos nas instruções pelo nome: "Does `message` ask for a demo?".

Estado de texto

{ "kind": "text" }

O estado precisa ser uma string não vazia: { "state": "Congratulations! You won a $1000 gift card…" }. O engine recebe a própria string.

Estado de lista

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

O estado precisa ser um array não vazio de até 500 itens. items define o que cada item é:

itemsCada item precisa serExemplo de estado
string (padrão)uma string["Hi!", "My card was charged twice.", "Can you refund one?"]
objectum objeto JSON (não null, não um array)[{ "role": "customer", "text": "My card was charged twice." }, { "role": "agent", "text": "Let me check." }]

O engine recebe o próprio array. Os erros dizem qual é o problema: "Field state must be a non-empty array.", "Field state has too many items (612, max 500)." ou "Item 2 of state must be an object.".

Uma lista é um estado: cada pergunta é respondida sobre a lista como um todo — "esta conversa pede um reembolso?" — e não uma vez por item. Para classificar os itens de forma independente, envie uma decisão por item, ou use um estado de objeto como { "messages": [ … ] } com uma pergunta por posição ("Is `messages[2]` a complaint?").

Limites de tamanho

O estado serializado precisa caber em 128 KB e em cerca de 32.000 tokens (estimados como caracteres ÷ 4) — sem contar os arquivos dele, que têm limites próprios (20 MB cada; o texto deles é cortado para caber — veja Entradas).

O Jev também tem um orçamento de tokens para a chamada inteira: cerca de 32.000 tokens para o estado mais a pergunta mais longa e 64.000 tokens para o estado mais todas as perguntas. A Dcision confere os dois antes de chamar o engine; um estado acima dos limites falha com 422 INVALID_STATE e uma mensagem que diz qual limite foi atingido — por exemplo "The state plus all questions is too large for one engine call (~65210 tokens, max 64000). Shorten the state or split the decision." Veja Limites.

Contexto

context é texto livre, de até 8.000 caracteres, enviado com todo estado sob a chave reservada decision_context — por exemplo "Inbound messages from the pricing page of a B2B SaaS. Prices start at $29/month." Descreva o negócio, não a resposta esperada.

Como o engine o recebe:

Tipo de estadoO que o engine avalia quando context está definido
objecto seu objeto mais um campo decision_context
text, list{ "decision_context": "<context>", "input": <your state> }

Sem context, o engine recebe o seu estado sem alterações.

decision_context é reservado: quando a decisão tem um context, ele substitui um campo decision_context que a sua aplicação envie num estado de objeto. Qualquer outro campo — inclusive um chamado context — é repassado como está.

Entradas estruturadas

As instruções, as descrições das opções de choice, os níveis de score e os critérios de probability aceitam objetos ou arrays JSON além de texto — o Jev lê estrutura nativamente. Use isso para rotular as partes de uma pergunta longa, para passar dados de apoio ou para dar uma rubrica a cada opção. Veja Instruções e critérios estruturados.

Validação

As mesmas regras rodam em todo lugar:

  • Editor — valida enquanto você digita, mostra cada problema com um link Ir para o erro e só salva automaticamente rascunhos válidos.

  • API — salvar ou publicar um schema inválido falha com 422 INVALID_SCHEMA; details lista cada problema com o caminho dele:

    {
      "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 confere um arquivo offline, e dcision check-state confere um estado contra ele.

As regras de validação podem ficar mais rígidas com o tempo — desde a v0.3, por exemplo, os valores das regras são conferidos contra as opções, os níveis e os intervalos com que eles são comparados ("Use a number between 0 and 1 (e.g. 0.7, not 70)."). Regras mais rígidas valem quando você salva ou publica; as versões já publicadas continuam rodando sem mudanças, então uma regra endurecida nunca transforma um endpoint no ar num erro.

O contrato da API

A visão Contrato da API do editor mostra no que os clientes da decisão podem confiar: o estado como JSON Schema, o formato da resposta de cada pergunta e os composites.

{
  "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" }
  }
}

Um estado de texto aparece como { "type": "string" } e um estado de lista como { "type": "array", "items": { "type": "string" } } (ou "object"). As escalas de score listam os rótulos dos níveis, também para níveis estruturados. composites só aparece quando a decisão tem algum.

Nesta página