> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqwish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Decision types

> Yes or no, one of several, or a level on a scale. When to use each kind, how to write it and what it returns.

Every decision has a `kind`. The kind sets how you list the outcomes and what the answer holds.

| Kind | Use it to | You list | The answer |
| - | - | - | - |
| `binary` | Answer a yes or no question | Nothing, or a description of `yes` and of `no` | `probabilities`, `top`, `p_top` |
| `single` | Pick one of several named outcomes | 2 to 255 outcomes, as names or with descriptions | `probabilities`, `top`, `p_top` |
| `ordinal` | Place something on an ordered scale | 2 to 255 levels, lowest first, and a `rubric` line for each | Also `expected_level` |

A decision with no `kind` is `single`.

The examples below are the three decisions of the [quickstart](https://docs.sqwish.ai/quickstart.md)'s request, each with the
answer `kettei-core` gave to it, rounded to three places.

## Binary

Use `binary` for a question whose answer is yes or no.

```json theme={null}
{"id": "urgent", "kind": "binary", "question": "Does the ticket state a deadline within one day?",
 "outcomes": {"yes": "An explicit deadline is today or within the next 24 hours.",
              "no": "The deadline is later, absent, or unclear."}}
```

```json theme={null}
"urgent": {
  "kind": "binary",
  "probabilities": {"yes": 0.912, "no": 0.088},
  "top": "yes",
  "p_top": 0.912
}
```

* `outcomes` is optional. When you send it, its keys are `yes` and `no`, each with a description of when
  it applies.
* `probabilities.yes` is the probability that the answer is yes.
* Ask the question the positive way round. "Does the ticket state a deadline?" is easier to answer and to
  label than "Is this not urgent?".

## Single

Use `single` to pick one of several outcomes that exclude each other, such as a team, a category or a
tool.

```json theme={null}
{"id": "team", "kind": "single", "question": "Which team should handle this ticket?",
 "outcomes": {"billing": "Charges, invoices, and financial exports.",
              "technical": "Other application failures.",
              "sales": "New purchases."}}
```

```json theme={null}
"team": {
  "kind": "single",
  "probabilities": {"billing": 0.927, "technical": 0.054, "sales": 0.019},
  "top": "billing",
  "p_top": 0.927
}
```

* List the outcomes as names, such as `["billing", "technical", "sales"]`, or as a map from each name to a
  description of when it applies. Descriptions help most where two outcomes meet.
* A decision has 2 to 255 outcomes, and their names differ. `abstain` is reserved for the
  [abstain policy](https://docs.sqwish.ai/guides/actions.md#abstain-below-a-threshold).
* If none of your outcomes might fit, add one such as `other` or `none`.

## Ordinal

Use `ordinal` for a level on an ordered scale, such as severity or quality.

```json theme={null}
{"id": "impact", "kind": "ordinal",
 "question": "How severe is the reported impact on the customer's work?",
 "outcomes": ["0", "1", "2"],
 "rubric": ["Minor inconvenience; the task can still be completed.",
            "The task is impaired, but a workable alternative is stated.",
            "An important task is blocked and no workable alternative is stated."]}
```

```json theme={null}
"impact": {
  "kind": "ordinal",
  "probabilities": {"0": 0.051, "1": 0.106, "2": 0.844},
  "top": "2",
  "p_top": 0.844,
  "expected_level": 1.793
}
```

* `outcomes` lists the levels in order, lowest first. `rubric` describes each level, in the same order.
  An ordinal decision needs both.
* `expected_level` is the average level, weighted by the probabilities. It counts positions from 0, not
  the values of your labels: on a `low`, `medium`, `high` scale it runs from 0 to 2.
* Sort a queue by `expected_level`, or use `top` as a label.

## Mix kinds in one request

One request can ask decisions of every kind about the same context, as the quickstart does. Each
decision gets its own probabilities, and its own action if you give it a
[policy](https://docs.sqwish.ai/guides/actions.md). The answers come back keyed by `id`.

## Rules every decision follows

| Field | Rule |
| - | - |
| `id` | 1 to 128 characters, different for each decision in the request |
| `question` | A non-empty string, or JSON |
| `outcomes` | By kind, as above. Names are different and not empty, and `abstain` is reserved |
| `rubric` | Ordinal decisions only: one line for each level, in order |
| `policy` | Optional: `abstain_below`, `action_costs` or both ([act on the answer](https://docs.sqwish.ai/guides/actions.md)) |

* A request asks 1 to 128 decisions. A model may take fewer: `max_questions` in
  [`/v1/models`](https://docs.sqwish.ai/api-reference/models/list-models), which a fine-tuned model shares with the model it
  was trained from.
* Keep outcome names short and put the detail in descriptions. If several decisions in a request have an
  outcome name over 500 characters, they must all list the same outcomes in the same order. Send other
  decisions in a request of their own.
* Keep the order of the outcomes fixed when you reword a decision, and when you
  [fine-tune a model](https://docs.sqwish.ai/guides/fine-tuning.md) on it.
* A decision that breaks a rule is refused with `422 invalid_request`, and `error.details` names the field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.