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

# Concepts

> State, questions, the three answer types, and how to read probabilities.

## The request

A request has exactly three fields. Any other field is rejected with a `400`.

| Field | Type | Meaning |
| - | - | - |
| `model` | string | A model id: the `torchcast-decider-latest` alias or a pinned id. See [Models](/models). |
| `state` | string, object or array | The input every question is about. Must not be empty. Objects and arrays are read as their JSON. |
| `questions` | object | 1 to 128 questions, keyed by question name. |

### Question names

Question names are the keys of `questions` and of `answers` in the response. A name is 1 to 64 characters of letters, digits, `_` and `-`. Use stable, descriptive names (`refund_request`, `severity`): your code reads answers by them.

### Instructions and criteria

Every question has a `type` and an optional `instructions` field. `instructions` is the question itself, in plain language. It can be a string, an object, an array or `null`.

`criteria` describes the possible answers, and its shape depends on the type:

| Type | `criteria` | Required? |
| - | - | - |
| `noul` | Object with optional `true` and `false` descriptions | A `noul` question needs `instructions` or `criteria` |
| `choice` | Object mapping 1 to 255 option names to descriptions | Yes |
| `score` | Array of 1 to 10 level labels, lowest first | Yes |

Descriptions can be strings, objects, arrays or `null`. Score level labels can be strings, objects or arrays.

## The three question types

### `noul`: yes or no

The answer is the probability that the answer to the question is yes. Use `criteria` to say what counts as yes (`true`) and no (`false`) when the instructions alone leave room for doubt.

```json Request theme={null}
{
  "model": "torchcast-decider-latest",
  "state": "Order 4417 arrived with a cracked screen. The box was crushed on one corner.",
  "questions": {
    "shipping_damage": {
      "type": "noul",
      "instructions": "Was the product damaged in transit?",
      "criteria": {
        "true": "The damage happened during shipping or delivery.",
        "false": "The product was faulty before shipping, or there is no damage."
      }
    }
  }
}
```

```json Response theme={null}
{
  "model": "torchcast-decider-4b-v1-1-api-1",
  "answers": {
    "shipping_damage": { "type": "noul", "noul": 0.88 }
  },
  "usage": { "input_tokens": 52, "output_tokens": 1 }
}
```

`noul` is between 0 and 1. Here the model puts the chance of shipping damage at 0.88.

### `choice`: one of your options

`criteria` maps each option name to a description. Option names are 1 to 128 characters and must be unique. The answer names the most likely option in `choice`, the model's `confidence` in it, and the probability of every option in `probabilities`, keyed by option name. The probabilities add up to 1, up to rounding.

```json Request theme={null}
{
  "model": "torchcast-decider-latest",
  "state": "Can I add five more seats to our team plan before the next billing date?",
  "questions": {
    "intent": {
      "type": "choice",
      "instructions": "What does the customer want?",
      "criteria": {
        "upgrade": "Buy more of the product or a bigger plan.",
        "cancel": "Stop using the product or downgrade.",
        "support": "Get help with a problem."
      }
    }
  }
}
```

```json Response theme={null}
{
  "model": "torchcast-decider-4b-v1-1-api-1",
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "upgrade",
      "confidence": 0.94,
      "probabilities": { "upgrade": 0.94, "cancel": 0.01, "support": 0.05 }
    }
  },
  "usage": { "input_tokens": 48, "output_tokens": 1 }
}
```

### `score`: a level on your scale

`criteria` is an ordered list of level labels, lowest first. A level's index is its 0-based position in the list. Use at least two levels; up to 10 are allowed.

The answer has:

* `score`: the probability-weighted average of the level indexes, a number from 0 to the highest index.
* `confidence`: the model's confidence in the result, between 0 and 1.
* `legend`: your level labels, keyed by index as a string (`"0"`, `"1"`, ...).
* `probabilities`: the probability of each level, keyed the same way.

```json Request theme={null}
{
  "model": "torchcast-decider-latest",
  "state": "The export button does nothing on Safari. Chrome works fine.",
  "questions": {
    "severity": {
      "type": "score",
      "instructions": "How severe is the issue for the customer?",
      "criteria": ["Cosmetic", "Inconvenient", "Product unusable"]
    }
  }
}
```

```json Response theme={null}
{
  "model": "torchcast-decider-4b-v1-1-api-1",
  "answers": {
    "severity": {
      "type": "score",
      "score": 1.06,
      "confidence": 0.85,
      "legend": { "0": "Cosmetic", "1": "Inconvenient", "2": "Product unusable" },
      "probabilities": { "0": 0.05, "1": 0.84, "2": 0.11 }
    }
  },
  "usage": { "input_tokens": 41, "output_tokens": 1 }
}
```

Use `score` to rank items against each other, and `probabilities` when you need the chance of a specific level, such as "Product unusable".

## Several questions at once

Questions of all three types can share one request. The model reads the `state` once for all of them, and the `state` is billed once. The [API reference](/api-reference/create-a-decision) shows a request with one question of each type.

## Thresholds and confidence

The answers are probabilities, so the decision rule is yours. Pick a threshold from the cost of each kind of mistake:

* If acting wrongly is expensive (refunding automatically, closing an account), act only on a high probability, such as `noul >= 0.9`, and send the rest to a person.
* If missing a case is expensive (flagging a possible safety issue), act on a lower one, such as `noul >= 0.3`.

For `choice`, compare `probabilities` instead of looking at `choice` alone: two close options (0.48 and 0.46) mean the input is ambiguous. `confidence` is a quick summary of how sure the model is; when it is low, fall back to a default or a human review.

Calibrate thresholds on a sample of your own data before relying on them in production.


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