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

# Decision outputs

> Learn when and how to use decision models: Ask typed questions about an input and get calibrated probabilities back.

The Decisions API evaluates one input against a list of typed questions and
returns a probability-backed answer for each. No text is generated.
Instead the model returns a probability on each question, in one
round trip. Use it to quickly classify content,
route requests, gate actions, and score against rubrics.

The [decision models](/models/decisions) come in three sizes —
`decision-4b`, `decision-9b`, and `decision-27b` —  all reachable through the same
OpenAI-compatible `/v1/decisions` endpoint.

## Anatomy of a request

A request has three parts:

* `model` — which [decision model](/models/decisions) answers, for example `decision-9b`
* `input` — the text the questions are about
* `questions` — up to 64 of them, all asked about the same input

Each question has a `name` (an identifier you choose, echoed back in the
answer), `instructions` (the question itself), and a `type`. Types are built
into the model so it reports its probability over
**the type's fixed set of answers.**

| Type | Ask it to | You get back |
| - | - | - |
| `predicate` | Check a condition | `probability` that it's true, 0 to 1 |
| `choice` | Pick one of your options (up to 26) | `choice`, plus a probability per option |
| `score` | Rate against ordered levels | `score`: the probability-weighted average of the level indices |

Use `choice` for unordered categories (departments, topics) and `score` for
ordered ones (severity, urgency, quality). A score of 1.4 over levels
`["routine", "elevated", "critical"]` reads as "elevated, leaning critical."

## Example

```python Python theme={"dark"}
from tinfoil import TinfoilAI

client = TinfoilAI(api_key="<API_KEY>")

decision = client.decisions.create(
    model="decision-9b",
    input="Customer says they were charged three times for one $49 purchase "
          "and wants a refund. They sound frustrated but calm.",
    questions=[
        {"type": "predicate", "name": "escalate",
         "instructions": "Should this be escalated to a human agent?"},
        {"type": "choice", "name": "team",
         "instructions": "Which team should handle this?",
         "choices": [{"value": "billing"}, {"value": "security"}, {"value": "shipping"}]},
        {"type": "score", "name": "urgency",
         "instructions": "How urgent is this?",
         "levels": [{"label": "routine"}, {"label": "prompt attention"}, {"label": "critical"}]},
    ],
)

for answer in decision.answers:
    print(answer.name, answer)
```

```go Go theme={"dark"}
client, err := tinfoil.NewClient(option.WithAPIKey("<API_KEY>"))
if err != nil {
    log.Fatal(err)
}

decision, err := client.Decisions.New(context.TODO(), openai.DecisionNewParams{
    Model: "decision-9b",
    Input: openai.DecisionNewParamsInputUnion{
        OfString: openai.String("Customer says they were charged three times for one $49 purchase and wants a refund. They sound frustrated but calm."),
    },
    Questions: []openai.DecisionNewParamsQuestionUnion{{
        OfPredicate: &openai.DecisionNewParamsQuestionPredicate{
            Name:         openai.String("escalate"),
            Instructions: "Should this be escalated to a human agent?",
        },
    }},
})
if err != nil {
    log.Fatal(err)
}

fmt.Println(decision.Answers)
```

The response echoes each question's `name`:

```json theme={"dark"}
{
  "model": "decision-9b",
  "answers": [
    {"type": "predicate", "name": "escalate", "probability": 0.656},
    {"type": "choice", "name": "team", "choice": "billing",
     "probabilities": [
       {"value": "billing", "probability": 0.988},
       {"value": "security", "probability": 0.012},
       {"value": "shipping", "probability": 0.000}
     ],
     "confidence": 0.988},
    {"type": "score", "name": "urgency", "score": 0.981,
     "probabilities": [
       {"value": 0, "label": "routine", "probability": 0.137},
       {"value": 1, "label": "prompt attention", "probability": 0.745},
       {"value": 2, "label": "critical", "probability": 0.118}
     ],
     "confidence": 0.745}
  ],
  "usage": {"input_tokens": 350, "output_tokens": 0, "total_tokens": 350}
}
```

## Working with the answers

Decisions are probabilities. You have to pick the threshold to interpret them. A
moderation gate might block above 0.9, send 0.5–0.9 to human review, and pass
the rest. These probabilities are one of the advantages over text output.

`choice` and `score` answers carry a `confidence`, which is just a convenient
way to extract the probability of the chosen answer.

> [!NOTE]
>
> Ask several questions in one request when they share the same input: the
> model reads the input once, so additional questions are nearly free.

## Choosing a model

All three sizes answer faster than generating text; they differ in
accuracy and speed relative to each other.

| Model | Character |
| - | - |
| `decision-4b` | Very fast, with some accuracy tradeoff |
| `decision-9b` | The default for most decision tasks |
| `decision-27b` | Slower, most accurate |

The sizes tend to agree on easy calls and diverge on hard ones. On the
escalation example above, "should this be escalated?" gets 0.38 from the 4B,
0.66 from the 9B, and 0.89 from the 27B.

The sizes also compose: for instance, you can run the `decision-4b` over
everything and route uncertain answers — a predicate probability near 0.5, or a
choice with no clear winner — to a larger model.


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