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

# PromptMessage

# PromptMessage

Chat message structures and role enumerations for LLM conversations.

## Overview

Message types define chat messages with roles and multi-modal content arrays. These are the building blocks for all prompt conversations in the Adaline SDK.

***

## MessageRole

See the dedicated [MessageRole](/docs/reference/sdk/v2/python/types/MessageRole) page for full documentation.

Message role enumeration for chat messages.

```python theme={null}
from adaline_api.models.message_role import MessageRole
```

`MessageRole` is a `str` enum with the following values:

| Value         | Enum Member             | Description                    |
| ------------- | ----------------------- | ------------------------------ |
| `"system"`    | `MessageRole.SYSTEM`    | System instructions or context |
| `"user"`      | `MessageRole.USER`      | User messages and input        |
| `"assistant"` | `MessageRole.ASSISTANT` | AI assistant responses         |
| `"tool"`      | `MessageRole.TOOL`      | Tool/function responses        |

**Example**:

```python theme={null}
from adaline_api.models.message_role import MessageRole

role = MessageRole.USER        # 'user'
role = MessageRole.SYSTEM      # 'system'
role = MessageRole.ASSISTANT   # 'assistant'
role = MessageRole.TOOL        # 'tool'

# String comparison works
assert MessageRole.USER == "user"
```

***

## PromptMessage

Chat message with role and multi-modal content for LLM conversations.

```python theme={null}
from adaline_api.models.prompt_message import PromptMessage
```

### Fields

<ParamField body="role" type="MessageRole" required>
  The message sender role. One of: `"system"`, `"user"`, `"assistant"`, `"tool"`.
</ParamField>

<ParamField body="content" type="list[MessageContent]" required>
  Array of content items. See [MessageContent](/docs/reference/sdk/v2/python/types/MessageContent).
</ParamField>

***

## Examples

### Simple Text Message

```python theme={null}
from adaline_api.models.prompt_message import PromptMessage
from adaline_api.models.message_content import MessageContent
from adaline_api.models.text_content import TextContent

message = PromptMessage(
    role="user",
    content=[
        MessageContent(actual_instance=TextContent(
            modality="text",
            value="Hello, how are you?"
        ))
    ]
)
```

### System Message

```python theme={null}
system_message = PromptMessage(
    role="system",
    content=[
        MessageContent(actual_instance=TextContent(
            modality="text",
            value="You are a helpful AI assistant."
        ))
    ]
)
```

### Multi-Modal Message

```python theme={null}
from adaline_api.models.image_content import ImageContent
from adaline_api.models.image_content_value import ImageContentValue

multi_modal = PromptMessage(
    role="user",
    content=[
        MessageContent(actual_instance=TextContent(
            modality="text",
            value="Describe this image"
        )),
        MessageContent(actual_instance=ImageContent(
            modality="image",
            detail="high",
            value=ImageContentValue.from_dict({
                "type": "url",
                "url": "https://example.com/img.jpg"
            })
        ))
    ]
)
```

### Conversation History

```python theme={null}
conversation: list[PromptMessage] = [
    PromptMessage(
        role="system",
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value="You are helpful."
        ))]
    ),
    PromptMessage(
        role="user",
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value="What is 2+2?"
        ))]
    ),
    PromptMessage(
        role="assistant",
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value="2+2 equals 4."
        ))]
    ),
    PromptMessage(
        role="user",
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value="And 3+3?"
        ))]
    ),
    PromptMessage(
        role="assistant",
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value="3+3 equals 6."
        ))]
    ),
]
```

### Tool Call Sequence

```python theme={null}
import json
from adaline_api.models.tool_call_content import ToolCallContent
from adaline_api.models.tool_response_content import ToolResponseContent

# User asks
user_msg = PromptMessage(
    role="user",
    content=[MessageContent(actual_instance=TextContent(
        modality="text",
        value="What is the weather in Paris?"
    ))]
)

# Assistant requests tool
assistant_tool = PromptMessage(
    role="assistant",
    content=[MessageContent(actual_instance=ToolCallContent(
        modality="tool-call",
        index=0,
        id="call_123",
        name="get_weather",
        arguments=json.dumps({"city": "Paris"})
    ))]
)

# Tool responds
tool_msg = PromptMessage(
    role="tool",
    content=[MessageContent(actual_instance=ToolResponseContent(
        modality="tool-response",
        index=0,
        id="call_123",
        name="get_weather",
        data=json.dumps({"temp": 24, "conditions": "sunny"})
    ))]
)

# Assistant answers
assistant_answer = PromptMessage(
    role="assistant",
    content=[MessageContent(actual_instance=TextContent(
        modality="text",
        value="In Paris it is sunny and 24°C."
    ))]
)
```

***

## Using with Deployments

```python theme={null}
from adaline.main import Adaline
from adaline_api.models.prompt_message import PromptMessage
from adaline_api.models.message_content import MessageContent
from adaline_api.models.text_content import TextContent

adaline = Adaline()

deployment = await adaline.get_latest_deployment(
    prompt_id="prompt_abc123",
    deployment_environment_id="environment_abc123"
)

# Get messages from deployment
system_messages: list[PromptMessage] = deployment.prompt.messages

# Add user message
user_message = PromptMessage(
    role="user",
    content=[MessageContent(actual_instance=TextContent(
        modality="text",
        value="Hello!"
    ))]
)

# Combine for API call
all_messages = [*system_messages, user_message]
```

***

## Helper Functions

```python theme={null}
from adaline_api.models.prompt_message import PromptMessage
from adaline_api.models.message_content import MessageContent
from adaline_api.models.text_content import TextContent
from adaline_api.models.image_content import ImageContent


def create_text_message(role: str, text: str) -> PromptMessage:
    return PromptMessage(
        role=role,
        content=[MessageContent(actual_instance=TextContent(
            modality="text", value=text
        ))]
    )


def get_message_text(message: PromptMessage) -> str:
    texts = []
    for c in message.content:
        if isinstance(c.actual_instance, TextContent):
            texts.append(c.actual_instance.value)
    return " ".join(texts)


def has_images(message: PromptMessage) -> bool:
    return any(
        isinstance(c.actual_instance, ImageContent)
        for c in message.content
    )


def filter_by_role(
    messages: list[PromptMessage], role: str
) -> list[PromptMessage]:
    return [m for m in messages if m.role == role]


# Usage
msg = create_text_message("user", "Hello!")
text = get_message_text(msg)        # 'Hello!'
has_img = has_images(msg)           # False
```

***

## Serialization

All autogen models support `to_dict()`, `to_json()`, `from_dict()`, and `from_json()` for serialization.

```python theme={null}
message = PromptMessage(
    role="user",
    content=[MessageContent(actual_instance=TextContent(
        modality="text", value="Hello!"
    ))]
)

# To dict / JSON
d = message.to_dict()
j = message.to_json()

# From dict / JSON
restored = PromptMessage.from_dict(d)
restored = PromptMessage.from_json(j)
```

***

## JSON Examples

### Simple

```json theme={null}
{
  "role": "user",
  "content": [
    { "modality": "text", "value": "Hello!" }
  ]
}
```

### With Image

```json theme={null}
{
  "role": "user",
  "content": [
    { "modality": "text", "value": "Describe this" },
    {
      "modality": "image",
      "detail": "high",
      "value": {
        "type": "url",
        "url": "https://example.com/image.jpg"
      }
    }
  ]
}
```

### Tool Call

```json theme={null}
{
  "role": "assistant",
  "content": [
    {
      "modality": "tool-call",
      "index": 0,
      "id": "call_123",
      "name": "get_weather",
      "arguments": "{\"city\":\"Paris\"}"
    }
  ]
}
```