jev_api/question

The typed questions Jev answers.

A request carries one piece of state and any number of questions, each under a key of your choosing. Jev answers every question in a single call:

Noul: a yes/no judgement, answered with the probability that the answer is “yes”.
Choice: pick one option from a set you supply, answered with the chosen option key, a probability for every option, and a confidence.
Score: place the state on an ordered scale, answered with a (possibly fractional) score, a probability per level, and a confidence.

The instructions and the criteria of a question are free-form JSON on the wire: a plain string, or an object/array when a structured rubric reads better. They are therefore gleam/json values here. The noul, choice and score constructors cover the plain-string case; build the record directly when you want structured instructions or criteria.

Types

NoulCriteria

</>

Clarifies the two outcomes of a Noul question. Either side may be left out.

pub type NoulCriteria {
  NoulCriteria(
    when_true: option.Option(json.Json),
    when_false: option.Option(json.Json),
  )
}

Constructors

NoulCriteria(
  when_true: option.Option(json.Json),
  when_false: option.Option(json.Json),
)

Question

</>

One question to ask about the state.

pub type Question {
  Noul(
    instructions: json.Json,
    criteria: option.Option(NoulCriteria),
  )
  Choice(
    instructions: json.Json,
    options: List(#(String, option.Option(json.Json))),
  )
  Score(instructions: json.Json, levels: List(json.Json))
}

Constructors

```
Noul(
  instructions: json.Json,
  criteria: option.Option(NoulCriteria),
)
```
A yes/no judgement. criteria optionally spells out what counts as “yes” and what counts as “no”.
```
Choice(
  instructions: json.Json,
  options: List(#(String, option.Option(json.Json))),
)
```
Pick one of options. Each option is a key (echoed back as the chosen choice in the answer) and an optional description. TypeSafe recommends including a catch-all option such as "other" when the list may not be exhaustive, and caps a question at 255 options.
```
Score(instructions: json.Json, levels: List(json.Json))
```
Rate the state along levels, listed from lowest to highest. The score in the answer can fall between two levels.

Values

choice

</>

pub fn choice(
  instructions: String,
  options: List(String),
) -> Question

A pick-one question whose options need no description beyond their keys.

described_choice

</>

pub fn described_choice(
  instructions: String,
  options: List(#(String, String)),
) -> Question

A pick-one question with a description for every option.

noul

</>

pub fn noul(instructions: String) -> Question

A yes/no question.

noul_with_criteria

</>

pub fn noul_with_criteria(
  instructions: String,
  when_true when_true: String,
  when_false when_false: String,
) -> Question

A yes/no question with a description of what makes the answer “yes” and what makes it “no”.

questions_to_json

</>

pub fn questions_to_json(
  questions: List(#(String, Question)),
) -> json.Json

Encodes a keyed set of questions as the request’s questions object, preserving the order given.

score

</>

pub fn score(
  instructions: String,
  levels: List(String),
) -> Question

A rating question over the given levels, lowest first.

to_json

</>

pub fn to_json(question: Question) -> json.Json

Encodes one question in the shape the API expects.