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

# Messages

> Message types for chat-based interactions

# Messages

Verifiers uses a provider-agnostic message format compatible with OpenAI and Anthropic APIs.

## Overview

The `Messages` type represents conversations as lists of message objects, where each message has a role and content.

## Type Definition

```python theme={null}
Messages = list[Message]

Message = (
    SystemMessage
    | UserMessage
    | AssistantMessage
    | ToolMessage
    | TextMessage
)
```

## Message Types

### SystemMessage

```python theme={null}
class SystemMessage(CustomBaseModel):
    role: Literal["system"] = "system"
    content: MessageContent
```

System instructions that set context for the conversation.

**Example**:

```python theme={null}
{
    "role": "system",
    "content": "You are a helpful math tutor."
}
```

### UserMessage

```python theme={null}
class UserMessage(CustomBaseModel):
    role: Literal["user"] = "user"
    content: MessageContent
```

User input or environment observations.

**Example**:

```python theme={null}
{
    "role": "user",
    "content": "What is 2+2?"
}
```

**Multimodal**:

```python theme={null}
{
    "role": "user",
    "content": [
        {"type": "text", "text": "What's in this image?"},
        {"type": "image_url", "image_url": {"url": "https://..."}}
    ]
}
```

### AssistantMessage

```python theme={null}
class AssistantMessage(CustomBaseModel):
    role: Literal["assistant"] = "assistant"
    content: MessageContent | None = None
    reasoning_content: str | None = None
    thinking_blocks: list[ThinkingBlock] | None = None
    tool_calls: list[ToolCall] | None = None
```

Model responses, including text, reasoning, and tool calls.

**Text response**:

```python theme={null}
{
    "role": "assistant",
    "content": "The answer is 4."
}
```

**With tool calls**:

```python theme={null}
{
    "role": "assistant",
    "content": "I'll search for that.",
    "tool_calls": [
        {
            "id": "call_123",
            "name": "search",
            "arguments": '{"query": "weather"}'
        }
    ]
}
```

**With reasoning** (OpenAI o1/o3):

```python theme={null}
{
    "role": "assistant",
    "content": "The answer is 4.",
    "reasoning_content": "First I add 2+2..."
}
```

**With thinking blocks** (Claude 3.7 Sonnet):

```python theme={null}
{
    "role": "assistant",
    "content": "The answer is 4.",
    "thinking_blocks": [
        {"type": "thinking", "thinking": "Let me calculate..."}
    ]
}
```

### ToolMessage

```python theme={null}
class ToolMessage(CustomBaseModel):
    role: Literal["tool"] = "tool"
    tool_call_id: str
    content: MessageContent
```

Tool execution results returned to the model.

**Example**:

```python theme={null}
{
    "role": "tool",
    "tool_call_id": "call_123",
    "content": "Weather: Sunny, 72°F"
}
```

### TextMessage

```python theme={null}
class TextMessage(CustomBaseModel):
    role: Literal["text"] = "text"
    content: str
```

Legacy format for completion-style APIs.

**Example**:

```python theme={null}
{
    "role": "text",
    "content": "The capital of France is Paris."
}
```

## MessageContent

```python theme={null}
MessageContent = str | list[ContentPart]

ContentPart = (
    TextContentPart
    | ImageUrlContentPart
    | InputAudioContentPart
    | GenericContentPart
    | dict[str, Any]
)
```

Content can be:

* **String**: Simple text
* **List of parts**: Multimodal content (text, images, audio)

### TextContentPart

```python theme={null}
class TextContentPart(CustomBaseModel):
    type: Literal["text"] = "text"
    text: str
```

**Example**:

```python theme={null}
{"type": "text", "text": "Hello"}
```

### ImageUrlContentPart

```python theme={null}
class ImageUrlContentPart(CustomBaseModel):
    type: Literal["image_url"] = "image_url"
    image_url: ImageUrlSource

class ImageUrlSource(CustomBaseModel):
    url: str
```

**Example**:

```python theme={null}
{
    "type": "image_url",
    "image_url": {"url": "https://example.com/image.jpg"}
}
```

### InputAudioContentPart

```python theme={null}
class InputAudioContentPart(CustomBaseModel):
    type: Literal["input_audio"] = "input_audio"
    input_audio: InputAudioSource

class InputAudioSource(CustomBaseModel):
    data: str  # Base64-encoded audio
    format: str  # e.g., "wav", "mp3"
```

**Example**:

```python theme={null}
{
    "type": "input_audio",
    "input_audio": {
        "data": "base64_encoded_audio_data",
        "format": "wav"
    }
}
```

## ToolCall

```python theme={null}
class ToolCall(CustomBaseModel):
    id: str
    name: str
    arguments: str  # JSON string
```

Represents a tool invocation from the assistant.

**Example**:

```python theme={null}
{
    "id": "call_abc123",
    "name": "get_weather",
    "arguments": '{"location": "San Francisco"}'
}
```

## Example Usage

### Building Conversations

```python theme={null}
import verifiers as vf

messages: vf.Messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {
        "role": "assistant",
        "content": "Python is a programming language."
    },
    {"role": "user", "content": "Show me an example"},
]
```

### Tool Call Flow

```python theme={null}
messages: vf.Messages = [
    {"role": "user", "content": "What's the weather?"},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [{
            "id": "call_1",
            "name": "get_weather",
            "arguments": '{"city": "NYC"}'
        }]
    },
    {
        "role": "tool",
        "tool_call_id": "call_1",
        "content": "Sunny, 70°F"
    },
    {
        "role": "assistant",
        "content": "It's sunny and 70°F in NYC."
    },
]
```

### Multimodal Messages

```python theme={null}
messages: vf.Messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Describe this image:"},
            {
                "type": "image_url",
                "image_url": {"url": "https://example.com/cat.jpg"}
            }
        ]
    },
    {
        "role": "assistant",
        "content": "I see a cat sitting on a windowsill."
    },
]
```

### Extracting Content

```python theme={null}
def get_text_content(message: vf.Message) -> str:
    """Extract text from a message."""
    content = message.get("content")
    
    if isinstance(content, str):
        return content
    elif isinstance(content, list):
        # Extract text parts
        text_parts = [
            part["text"]
            for part in content
            if isinstance(part, dict) and part.get("type") == "text"
        ]
        return " ".join(text_parts)
    else:
        return ""
```

### Formatting for Display

```python theme={null}
def format_conversation(messages: vf.Messages) -> str:
    """Format messages for display."""
    output = []
    
    for msg in messages:
        role = msg["role"]
        content = msg.get("content", "")
        
        if role == "system":
            output.append(f"[SYSTEM] {content}")
        elif role == "user":
            output.append(f"[USER] {content}")
        elif role == "assistant":
            if msg.get("tool_calls"):
                calls = ", ".join(
                    tc["name"] for tc in msg["tool_calls"]
                )
                output.append(f"[ASSISTANT] Calling tools: {calls}")
            else:
                output.append(f"[ASSISTANT] {content}")
        elif role == "tool":
            output.append(f"[TOOL] {content}")
    
    return "\n".join(output)
```

## Provider Compatibility

Verifiers messages are compatible with:

* **OpenAI**: Direct usage with `openai.ChatCompletion.create()`
* **Anthropic**: Automatic conversion by `AnthropicClient`
* **Custom APIs**: Can be serialized/deserialized as needed

## Validation

Messages use Pydantic models for validation:

```python theme={null}
from verifiers.types import UserMessage

# Valid
msg = UserMessage(role="user", content="Hello")

# Invalid - will raise ValidationError
try:
    msg = UserMessage(role="assistant", content="Hello")
except ValidationError as e:
    print(e)
```

## Dict-like Access

Message objects support dict-like access:

```python theme={null}
msg = vf.UserMessage(role="user", content="Hello")

# Dict-style access
role = msg["role"]           # "user"
content = msg.get("content") # "Hello"
"role" in msg                # True

# Attribute access
role = msg.role              # "user"
content = msg.content        # "Hello"
```

## See Also

* [Response](/api/types/response) - API response format
* [State](/api/types/state) - Rollout state containing messages
* [Tool](/api/types/tool) - Tool definition format