Score

Shape

{  "type": "score",  "instructions": "…",         // optional: the question  "criteria": [                // required: 1 to 10 levels, lowest first    "description of level 0",    "description of level 1",    "…"  ]}

{  "type": "score",  "score": 2.91,  "legend": { "0": "No action needed", "1": "Can wait a few days", "2": "Handle today", "3": "Drop everything" },  "probabilities": { "0": 0.0, "1": 0.01, "2": 0.07, "3": 0.92 },  "confidence": 0.91,  "stats": {}}

• score is the expected level: the sum of each level times its probability. It can fall between levels (2.91 above), which is useful for sorting and averaging.
• probabilities are keyed "0" to "n-1", one per level. The most likely level is the key with the highest probability.
• legend repeats your level descriptions under the same keys, exactly as you sent them (strings stay strings, objects stay objects).
• confidence is high when probability is packed around one level; see Confidence.

Example

curl -s "https://api.vakyn.com/v1/systemone" \  -H "Authorization: Bearer $TYPESAFE_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "jev-latest",    "state": "Our checkout page returns an error for every customer. We are losing orders right now.",    "questions": {      "urgency": {        "type": "score",        "instructions": "How urgent is this message?",        "criteria": [          "No action needed",          "Can wait a few days",          "Handle today",          "Drop everything"        ]      }    }  }'

{  "model": "vakyn-fake",  "answers": {    "urgency": {      "type": "score",      "score": 2.91,      "legend": {        "0": "No action needed",        "1": "Can wait a few days",        "2": "Handle today",        "3": "Drop everything"      },      "probabilities": {        "0": 0,        "1": 0.01,        "2": 0.07,        "3": 0.92      },      "confidence": 0.91,      "stats": {}    }  },  "usage": {    "input_tokens": 41,    "output_tokens": 0  },  "assets_used": null}

Writing levels

• List levels from lowest to highest. The order is the meaning: the expected score only makes sense if level 3 is "more" than level 2.
• Describe each level by what you would observe, not only by a word: "Handle today" beats "Medium". A level may be a string, an object or an array.
• Use as few levels as you need. Three to five well-described levels usually beat ten vague ones; the maximum is 10.
• If the levels are not really ordered (colors, departments), use a choice instead.

Rounding: the expected score is computed from the unrounded probabilities and then rounded, so recomputing it from the rounded probabilities can differ by a hundredth or two.