Perguntas

Perguntas de choice, score e probability — instruções e critérios estruturados, o que a API devolve para cada uma, níveis ponderados, a opção reservada other e a confiança mínima.

Perguntas são o que uma decisão responde sobre o estado. Uma decisão tem de 1 a 64 perguntas, todas respondidas em uma única chamada ao engine: o Jev avalia cada uma delas de forma independente e em paralelo sobre o mesmo estado. Cada pergunta vira uma chave nos objetos result e confidence da resposta, na ordem em que você as define.

TipoUse pararesult[key]Exemplo
choiceEscolher uma opção: um time, uma categoria, uma ferramentaUm dos valores das suas opções (string)"sales"
scorePosicionar o estado numa escala ordenadaO rótulo do nível mais provável (string)"high"
probabilityUma pergunta de sim/nãoProbabilidade de sim, de 0 a 10.9412

Propriedades comuns

PropriedadeTipoObrigatóriaDescrição
keystringSimsnake_case, única na decisão. Vira a chave JSON na resposta.
typestringSimchoice, score ou probability.
instructionsstring, objeto ou arraySimA pergunta que o engine responde: texto ou JSON estruturado. Até 8.000 caracteres (no JSON conta o tamanho serializado).
minConfidencenumberNãoDe 0 a 1. Abaixo dela, a decisão aplica a ação de fallback — veja abaixo.

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 precisa de pelo menos 2 e no máximo 254 opções, mais other — 255 no total, o máximo do Jev.
  • value segue as regras de chaves e precisa ser único dentro da pergunta.
  • description diz ao engine quando a opção se aplica: texto ou JSON, até 2.000 caracteres. É opcional — omita-a, ou defina como null, quando o valor já diz tudo ("yes_refund"). As descrições decidem a precisão: contraste opções parecidas e acrescente exclusões como "não para clientes atuais".
  • A ordem importa. O Jev pode tender para a opção listada primeiro. Teste as perguntas importantes com as opções reordenadas no Playground e confira se a resposta continua a mesma.

A opção reservada other

Toda pergunta de choice tem uma opção other. A Dcision a adiciona automaticamente como a última opção, com a descrição none of the options above. Ela não pode ser removida, mas você pode descrevê-la incluindo-a em options — onde quer que você a coloque, ela é movida para o final:

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

Sem other, o engine é forçado a escolher a opção menos errada. Com ela, "nenhuma destas" vira uma resposta explícita: quando uma pergunta de choice responde other e nenhuma política casou antes, a decisão aplica a sua ação de fallback com action_reason.type = "other_option". Veja Políticas e ações.

O que a API devolve

  • result.route — a opção escolhida, por exemplo "sales" (ou "other").
  • confidence.route — o quanto a opção escolhida fica acima de uma divisão igual entre todas as opções, de 0 a 1 — veja Confiança.
  • Com ?include=probabilities, probabilities.route traz uma probabilidade por opção, other incluída.

Políticas sobre uma resposta de choice só podem usar eq e neq. A comparação ignora maiúsculas/minúsculas e espaços nas pontas.

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 níveis, do mais baixo ao mais alto. Um nível é um rótulo (até 2.000 caracteres) ou uma rubrica estruturada com um label. Os rótulos precisam ser únicos.
  • result.priority é o rótulo do nível mais provável — não uma média — e confidence.priority diz o quanto a distribuição está concentrada em torno dele.
  • scores.priority é o nível ponderado: a média dos níveis ponderada pelas probabilidades, contando a partir de 1. Na escala acima, 2.81 fica entre medium (2) e high (3), mais perto de high. Use-o para agir entre níveis.
  • Com ?include=probabilities, probabilities.priority traz uma probabilidade por rótulo, na ordem da escala.

Políticas comparam níveis, numerados a partir de 1: na escala acima, low é 1 e critical é 4.

  • Sobre a resposta ("on": "output"), uma regra usa o número do nível ("value": 3) ou o rótulo ("value": "high"), com qualquer operador: { "field": "priority", "operator": "gte", "value": "high", "action": "escalate" } casa com high e critical. Um rótulo que não está na escala nunca casa.
  • Sobre o nível ponderado ("on": "score"), uma regra compara scores.priority com um número: { "field": "priority", "on": "score", "operator": "gte", "value": 3.5, "action": "escalate" } dispara quando o peso pende para critical, mesmo que high seja o nível mais provável.

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 e criteria.no são opcionais — texto ou JSON, até 2.000 caracteres cada — e dizem o que conta como sim e como não. Mantenha-os alinhados com as instruções: yes deve descrever o caso do sim.
  • result.purchase_intent é a probabilidade de sim, entre 0 e 1, arredondada para 4 casas decimais.
  • confidence.purchase_intent é |2p − 1|: a distância de um cara ou coroa. 0.03 (um não confiante) e 0.97 (um sim confiante) têm ambos confiança 0.94; 0.5 tem confiança 0.
  • Com ?include=probabilities, probabilities.purchase_intent é { "yes": p, "no": 1 − p }.

Políticas comparam a probabilidade com um número, por exemplo { "field": "purchase_intent", "operator": "gte", "value": 0.8, "action": "continue" }.

Instruções e critérios estruturados

O Jev lê estrutura nativamente. Onde quer que uma pergunta tenha texto — instructions, description das opções, níveis de score, criteria.yes e criteria.no — você pode enviar um objeto ou array JSON no lugar. A estrutura ajuda quando uma pergunta tem várias partes, ou quando precisa de dados de apoio como uma taxonomia, um schema ou uma linha de banco de dados: as chaves rotulam 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`?"
  }
}
  • Aponte para os dados com crases. Cite campos do estado e chaves da instrução entre crases — `resume`, `ticket.messages[0].text` — para dizer ao engine exatamente o que olhar.
  • Dê uma rubrica às opções. Uma descrição de opção como { "what": "Charges, invoices, refunds", "not_for": "Order tracking", "examples": ["I was charged twice"] } deixa mais nítida a fronteira entre opções vizinhas.
  • Os limites são os mesmos do texto, medidos sobre o JSON serializado: 8.000 caracteres para instruções, 2.000 para uma descrição de opção, um nível de score ou um critério. Objetos e arrays não podem ser vazios.
  • No editor, cole um objeto ou array JSON no campo: ele é guardado como estrutura e marcado como estruturada. Qualquer coisa que não seja JSON válido continua sendo texto.

Níveis de score estruturados

Um nível de score pode ser um objeto com um label — o rótulo é o que result devolve e o que as políticas comparam; o objeto inteiro é o que o engine lê:

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

O rótulo tem de 1 a 255 caracteres; o nível inteiro, serializado, até 2.000. Níveis simples e estruturados podem ser misturados numa mesma escala. O editor adiciona níveis como rótulos simples e mostra os estruturados com um ícone de chaves — o template Support Ticket Triage começa com um.

Confiança mínima

Qualquer pergunta pode definir minConfidence entre 0 e 1. Quando a confiança da resposta fica abaixo dela e nenhuma política casou antes, a decisão aplica a sua ação de fallback com action_reason.type = "low_confidence":

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

No editor, a chave Confiança mínima começa em 80%. Sem ela, respostas de baixa confiança continuam dando continue.

Para uma pergunta de probability, a confiança é |2p − 1|, então uma confiança mínima sinaliza uma faixa de probabilidades em torno de 0,5: 0.8 sinaliza todo p entre 0,1 e 0,9; 0.6, todo p entre 0,2 e 0,8. O editor mostra a faixa ao lado do controle deslizante. Veja Confiança e probabilidades e Lidando com baixa confiança e other.

Dicas

  • Pergunte uma coisa por pergunta. Divida "isto é spam urgente?" numa probability (spam) e num score (urgency) — custam uma chamada do mesmo jeito.
  • Formule as instruções como uma pergunta literal sobre o estado: "Qual time deve receber este lead?".
  • Prefira probability para sim/não — é mais fácil aplicar um limiar ao número do que a uma choice de duas opções.
  • Prefira score para níveis ordenados — assim as políticas podem usar gte/lte sobre o nível e limiares sobre o nível ponderado.
  • Escreva as descrições das opções como critérios, não como rótulos, e torne as vizinhas mutuamente exclusivas. Se o Playground sinalizar um quase empate, as descrições se sobrepõem.
  • Coloque os fatos do negócio em context, não em cada instrução.
  • Deixe contas, contagens e datas no código e envie os resultados no estado.
  • A ordem importa: quando várias perguntas respondem other ou ficam abaixo da sua confiança mínima, a primeira na ordem das perguntas é a informada em action_reason.

Mais em Escrevendo boas perguntas.

Nesta página