# Core concepts

Source: https://docs.temprl.org/guide/concepts

> How Simo works - the state, typed questions, decisions versus reads, and what a calibrated probability means for your code.

Every Simo request has the same shape: a **state** describing the situation, and a set of **questions** about it. Simo reads the state once and returns one **answer** per question.

## State

The state is everything Simo should know to answer: a support ticket, a policy, an agent's history, a screenshot. It can be:

- **A string**: `"The customer says the parcel arrived broken."`
- **A JSON object** (recommended when there are several parts). The keys become labels the model sees:

```python
state = {
    "policy":  "Refunds are allowed within 30 days of delivery.",
    "ticket":  "My order arrived 12 days ago, broken. I want my money back.",
    "history": "(nothing yet)",
}
```

- **Text with media placeholders** such as `<image:1>` or `<video:1>`, pointing at images and videos sent in `media`. See [Images and video](https://docs.temprl.org/guide/images-and-video).

Put rules, policies and context **in the state**, and keep each question short and specific.

## Questions

Questions are a map from an id you choose to a typed question. The id is the key you read the answer back with.

```python
questions = {
    "refund": Noul("The customer asks for a refund"),
    "team":   Choice("Which team should handle this?", {"billing": "...", "shipping": "..."}),
}
```

There are two families:

| Family | Types | How it answers |
|---|---|---|
| **Decisions** | `Noul`, `Choice`, `Score` | Picks among fixed answers, with a calibrated probability for each |
| **Reads** (preview) | `Fill`, `Extract`, `Locate` | Writes a value, constrained to its type: text, int, number, list or coordinates |

See [Question types](https://docs.temprl.org/guide/question-types) for each one.

## Calibration

A probability is **calibrated** when it matches how often it is right. Among all the decisions Simo answers with 0.8, about 80% are correct; among those at 0.99, about 99% are.

That makes probabilities usable as thresholds. Pick the threshold from what a mistake costs:

```python
p = r["approve"].noul
if p > 0.97:   approve()        # a wrong approval is expensive: demand near-certainty
elif p < 0.10: decline()
else:          send_to_person()
```

> **Note** Decisions (`Noul`, `Choice`, `Score`) are calibrated. The `confidence` on reads (`Fill`, `Extract`, `Locate`) shows how sure the model was while writing, and is useful, but it is not calibrated. For a calibrated check of a value, use [`self_check`](https://docs.temprl.org/guide/options#self-check).

## One read, many questions

The cost of a request is mostly in reading the state. Questions about the same state are nearly free, so ask everything at once rather than one request per question. See [Pricing](https://docs.temprl.org/models/pricing).

## Models

`simo-1-pro` is the model available today. On a confident decision it answers at full speed, and only spends extra time deliberating when a decision is genuinely uncertain. See [Models](https://docs.temprl.org/models).