# Question objects

Source: https://docs.temprl.org/api/questions

> JSON schema for every Simo question type in the HTTP API - noul, choice, score, fill, extract and locate - with fields, defaults and limits.

`questions` maps an id you choose to a question object. Every object has a `type` and an `instructions` string.

## noul

A statement; the answer is P(true).

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"noul"` | yes | |
| `instructions` | string | yes | A statement, e.g. "The task is finished" |
| `criteria` | object | no | `{"true": "...", "false": "..."}`: what each side means |

```json
{"type": "noul", "instructions": "The next action is risky",
 "criteria": {"true": "it deletes data or moves money", "false": "it only reads"}}
```

## choice

One of several options.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"choice"` | yes | |
| `instructions` | string | yes | The question |
| `criteria` | object | yes | `{option_key: description}`, 2 to 256 options |
| `args` | object | no | `{option_key: {arg_name: fill or extract question}}`: arguments generated for the chosen option only |

```json
{"type": "choice", "instructions": "Which team should handle this ticket?",
 "criteria": {"billing": "refunds and payments", "shipping": "delivery and tracking", "tech": "website and app problems"}}
```

## score

A level on an ordered scale.

| Field | Type | Required | Description |
|---|---|---|---|
| `type` | `"score"` | yes | |
| `instructions` | string | yes | The question |
| `criteria` | array | yes | Levels, lowest first |

```json
{"type": "score", "instructions": "How upset is the customer?", "criteria": ["calm", "annoyed", "angry", "furious"]}
```

## fill

Write a short value, constrained to its type. *Preview.*

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"fill"` | yes | | |
| `instructions` | string | yes | | What to write |
| `kind` | string | no | `"text"` | `text`, `int`, `number` or `json_list` |
| `pattern` | string | no | | A regex the value must match. Only with `kind: "text"` |
| `max_tokens` | integer | no | 16 | 1 to 256 |

```json
{"type": "fill", "instructions": "the amount due, in dollars", "kind": "number", "max_tokens": 16}
```

## extract

Copy a value from the state, verbatim where possible. *Preview.*

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"extract"` | yes | | |
| `instructions` | string | yes | | What to extract |
| `kind` | string | no | `"text"` | `text` (or `coordinates`, see locate) |
| `many` | boolean | no | `false` | Return every match as a list |
| `list_format` | string | no | | `"json"`: read a `many` extract from a JSON list instead of one item per line |
| `max_tokens` | integer | no | 64 | 1 to 512 |

```json
{"type": "extract", "instructions": "every order number mentioned", "kind": "text", "many": true, "max_tokens": 64}
```

## locate

Where something is in an image. A locate is an `extract` with `kind: "coordinates"`. *Preview.*

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | `"extract"` | yes | | |
| `kind` | `"coordinates"` | yes | | |
| `instructions` | string | yes | | What to find |
| `image` | integer | no | 1 | Which image, 1-based (the N of `<image:N>`) |
| `scale` | string | no | `"rel1000"` | How coordinates are expressed to the model: `rel1000` or `pixels`. Answers are in pixels either way |
| `max_tokens` | integer | no | 64 | |

```json
{"type": "extract", "kind": "coordinates", "instructions": "the Pay button", "image": 1, "scale": "rel1000", "max_tokens": 64}
```