# `ChatMessage`

One message in a conversation with an AI model: who wrote it and what it says.

Use it to build the history you send to a model. The [`ChatRole`](/docs/types/type-chat-role.md) says who wrote it.

## Shape

| Field | Type | Required? |
|---|---|---|
| `role` | [`ChatRole`](/docs/types/type-chat-role.md) | Yes |
| `content` | `Text` | Yes |

## Example

```jadpo
ChatMessage { role: ChatRole.user content: "Summarise this page." }
```

## Good to know

- `==` tells you whether two are the same. `<` and `list.sort_by` don't take it, so sort by one of its parts instead.
- A field that holds one counts as personal data (`health`), so you don't mark it yourself.

## In JSON

An object of its parts, in a request, a response or `json.write`:

```json
{"role":"system","content":"Answer in British English."}
{"role":"user","content":"Summarise this page.\nThanks"}
{"role":"assistant","content":""}
```

## Details

<details>
<summary>Text form, storage, how it is shown, and operations</summary>

`ChatMessage` is in the group AI, and has been in Jadpo since 0.1.0.

### Text form

It has no single text form, so `text.from` and `text.parse` don't take it.

### How it is stored

It is stored in 2 columns, each named for the field, `_` and its suffix. This is `{"role":"user","content":"Summarise this page.\nThanks"}`:

| Column | Type | Holds |
|---|---|---|
| `<field>_role` | `text` | `'user'` |
| `<field>_content` | `text` | `E'Summarise this page.\nThanks'` |

### How it is shown to people

`text.format(value, locale:)` shows it to people in their locale.

With `locale: Locale.en_gb`:

| Value | Shown |
|---|---|
| `{"role":"system","content":"Answer in British English."}` | `system: Answer in British English.` |
| `{"role":"user","content":"Summarise this page.\nThanks"}` | `"user: Summarise this page.\nThanks"` |
| `{"role":"assistant","content":""}` | `assistant: ` |

### Operations

It also takes `text.format`, `json.read`, `json.write` and `==`. [How every standard type behaves](/docs/every-standard-type-meets-one-contract.md) says how they work.

</details>