> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sdvm.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversation

> ConversationSample: a chat transcript in the OpenAI messages shape, its roles and rules, and extra columns.

`ConversationSample` holds a chat transcript: a list of `messages`, each a `role` and its `content`, in the shape every chat API and SFT corpus already uses.

## Shape

```python theme={"theme":{"light":"material-theme-lighter","dark":"material-theme-darker"}}
from sdvm import ConversationSample, Message

sample = ConversationSample(
    messages=[
        Message("system", "You are a concise assistant."),
        Message("user", "how do i reverse a list in python"),
        Message("assistant", "Use slicing: `xs[::-1]` returns a reversed copy, or `xs.reverse()` in place."),
    ],
)
```

Plain dicts work too: `messages=[{"role": "user", "content": "..."}, ...]` is normalised to `Message` objects. On the wire:

```json wrap theme={"theme":{"light":"material-theme-lighter","dark":"material-theme-darker"}}
{
  "task_type": "conversation",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "how do i reverse a list in python" },
    { "role": "assistant", "content": "Use slicing: `xs[::-1]` returns a reversed copy, or `xs.reverse()` in place." }
  ]
}
```

Roles are `system`, `user` and `assistant`. A system message may appear once, and only first. The transcript needs at least one user and one assistant turn. Tool and function turns are not accepted.

The type deliberately lets some defects through: an empty turn, a transcript that ends on the user, two user turns in a row. Those are what `sdvm-audit-1` reports and `sdvm-fix-1` repairs, so refusing them at construction would put them out of reach.

## Extra columns

Anything beyond `messages` goes in `extra` and comes back untouched, exactly as on every other sample type:

```python theme={"theme":{"light":"material-theme-lighter","dark":"material-theme-darker"}}
ConversationSample(messages=[...], extra={"prompt_id": "a1b2", "source": "ultrachat"})
```

## Turns

`turns` says how much of the transcript the models read. `"last"`, the default, is the final exchange: the last user turn, the last assistant reply, and whether that reply belongs to the transcript. `"all"` is every assistant turn, each against the transcript before it, reported per turn under `turns` in the audit. Each turn read this way adds to the cost of the sample.

```python theme={"theme":{"light":"material-theme-lighter","dark":"material-theme-darker"}}
ConversationSample(messages=[...], turns="all")
```

On the wire it is `"turns": "all"` on the sample.

## What the models return

<CardGroup cols={3}>
  <Card title="sdvm-audit-1" icon="magnifying-glass" href="/models/audit">
    What it returns for this sample.
  </Card>

  <Card title="sdvm-fix-1" icon="wrench" href="/models/fix">
    What it changes, and what it never does.
  </Card>

  <Card title="Refine" icon="arrows-rotate" href="/models/refine">
    Audit, fix and re-audit in one call.
  </Card>
</CardGroup>