# Writing questions

> Every request is a state plus a set of questions. Each question has a type, optional instructions, and criteria that define the possible answers.

Source: https://codiv.ai/docs/guides/questions

## The state

`state` is whatever the questions are about. It can be a string, or any JSON object or array, which is sent to the model as JSON. Put all the context the model needs here, because each question sees only the state and its own instructions and criteria.

JSON:


```json
{"state": {"subject": "Refund?", "body": "I was charged twice in September.", "plan": "team"}}
```

## noul: yes or no

A `noul` answers a yes/no question with the probability of *yes*. You can define what yes and no mean with `criteria`; it is optional.

Question:

```json
"wants_refund": {
  "type": "noul",
  "instructions": "The customer is asking for a refund",
  "criteria": {"true": "explicitly asks for money back", "false": "anything else"}
}
```

Answer:

```json
"wants_refund": {"type": "noul", "noul": 0.93}
```

## choice: pick one

A `choice` picks one of up to 128 named options. The `criteria` object maps each option name to a description, or to `null` when the name speaks for itself. The answer contains the most likely option, the probability of every option and a `confidence`.

Question:

```json
"topic": {
  "type": "choice",
  "instructions": "Primary topic of the message",
  "criteria": {"billing": "charges, invoices, refunds", "bug": "something is broken", "other": null}
}
```

Answer:

```json
"topic": {
  "type": "choice",
  "choice": "bug",
  "probabilities": {"billing": 0.04, "bug": 0.95, "other": 0.01},
  "confidence": 0.81
}
```

## score: a scale

A `score` places the state on an ordered scale of 2 to 10 levels, listed from lowest to highest. The answer's `score` is the expected level, `Σ i·pᵢ` with levels numbered from 0, so it can fall between levels. `legend` echoes your levels.

Question:

```json
"sentiment": {
  "type": "score",
  "instructions": "Overall sentiment",
  "criteria": ["negative", "neutral", "positive"]
}
```

Answer:

```json
"sentiment": {
  "type": "score",
  "score": 1.62,
  "legend": {"0": "negative", "1": "neutral", "2": "positive"},
  "probabilities": {"0": 0.03, "1": 0.32, "2": 0.65},
  "confidence": 0.62
}
```

## Many questions at once

Put every question about the same state in one request. They share one read of the state, so ten questions cost far less than ten requests. Large sets are split into chunks and answered in parallel. Question ids only key the answers and are never shown to the model, so name them for your code rather than for the model.

## Tips

- **Be concrete.** "Does the customer need a reply within the hour?" beats "urgent?".
- **Describe options by what they contain**, not just by their names, especially when names overlap.
- **Add an explicit fallback** such as `"other"` to choices, so the model is never forced into a bad fit.
- **Instructions and descriptions can be JSON** when you already have structured definitions.

> **Warning: Evaluate on your own data.**
> OpenJev is a new model. Check its answers on a labelled sample of your data before you rely on it in production.