> ## 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.

***

## MessageRole

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

Message role enumeration for chat messages.

```typescript theme={null}
type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
```

**Description**: Defines the four message roles in chat conversations.

**Values**:

* `'system'` - System instructions or context
* `'user'` - User messages and input
* `'assistant'` - AI assistant responses
* `'tool'` - Tool/function responses

**Example**:

```typescript theme={null}
import type { PromptMessage, MessageRole } from '@adaline/api';

// System message
const systemMessage: PromptMessage = {
  role: 'system',
  content: [{ modality: 'text', value: 'You are a helpful assistant.' }]
};

// User message
const userMessage: PromptMessage = {
  role: 'user',
  content: [{ modality: 'text', value: 'Hello!' }]
};

// Assistant message
const assistantMessage: PromptMessage = {
  role: 'assistant',
  content: [{ modality: 'text', value: 'Hi! How can I help?' }]
};

// Tool message
const toolMessage: PromptMessage = {
  role: 'tool',
  content: [{
    modality: 'tool-response',
    id: 'call_123',
    name: 'get_weather',
    data: JSON.stringify({ temp: 72 })
  }]
};
```

**Type Guard**:

```typescript theme={null}
function isValidRole(role: string): role is MessageRole {
  return ['system', 'user', 'assistant', 'tool'].includes(role);
}
```

**Filtering Messages**:

```typescript theme={null}
const messages: PromptMessage[] = [...];

// Get all user messages
const userMessages = messages.filter(m => m.role === 'user');

// Get system message
const systemMessage = messages.find(m => m.role === 'system');
```

***

## PromptMessage

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

```typescript theme={null}
interface PromptMessage {
  role: MessageRole;
  content: MessageContent[];
}
```

**Properties**:

* `role` - Message sender role ([MessageRole](/docs/reference/sdk/v2/typescript/types/PromptMessage#messagerole))
* `content` - Array of content items ([MessageContent](/docs/reference/sdk/v2/typescript/types/MessageContent))

***

## Examples

### Simple Text Message

```typescript theme={null}
import type { PromptMessage } from '@adaline/api';

const message: PromptMessage = {
  role: 'user',
  content: [
    { modality: 'text', value: 'Hello, how are you?' }
  ]
};
```

### System Message

```typescript theme={null}
const systemMessage: PromptMessage = {
  role: 'system',
  content: [
    { modality: 'text', value: 'You are a helpful AI assistant.' }
  ]
};
```

### Multi-Modal Message

```typescript theme={null}
const multiModal: PromptMessage = {
  role: 'user',
  content: [
    { modality: 'text', value: 'Describe this image' },
    {
      modality: 'image',
      detail: 'high',
      value: { type: 'url', url: 'https://example.com/img.jpg' }
    }
  ]
};
```

### Conversation History

```typescript theme={null}
const conversation: PromptMessage[] = [
  {
    role: 'system',
    content: [{ modality: 'text', value: 'You are helpful.' }]
  },
  {
    role: 'user',
    content: [{ modality: 'text', value: 'What is 2+2?' }]
  },
  {
    role: 'assistant',
    content: [{ modality: 'text', value: '2+2 equals 4.' }]
  },
  {
    role: 'user',
    content: [{ modality: 'text', value: 'And 3+3?' }]
  },
  {
    role: 'assistant',
    content: [{ modality: 'text', value: '3+3 equals 6.' }]
  }
];
```

### Tool Call Sequence

```typescript theme={null}
// User asks
const userMsg: PromptMessage = {
  role: 'user',
  content: [{ modality: 'text', value: 'What is the weather in Paris?' }]
};

// Assistant requests tool
const assistantTool: PromptMessage = {
  role: 'assistant',
  content: [{
    modality: 'tool-call',
    index: 0,
    id: 'call_123',
    name: 'get_weather',
    arguments: JSON.stringify({ city: 'Paris' })
  }]
};

// Tool responds
const toolMsg: PromptMessage = {
  role: 'tool',
  content: [{
    modality: 'tool-response',
    index: 0,
    id: 'call_123',
    name: 'get_weather',
    data: JSON.stringify({ temp: 24, conditions: 'sunny' })
  }]
};

// Assistant answers
const assistantAnswer: PromptMessage = {
  role: 'assistant',
  content: [{ modality: 'text', value: 'In Paris it is sunny and 24°C.' }]
};
```

***

## Using with Deployments

```typescript theme={null}
import { Adaline } from '@adaline/client';
import type { Deployment, PromptMessage } from '@adaline/api';

const adaline = new Adaline();

const deployment: Deployment = await adaline.getLatestDeployment({
  promptId: 'chat-prompt',
  deploymentEnvironmentId: 'production'
});

// Get system messages from deployment
const systemMessages: PromptMessage[] = deployment.prompt.messages;

// Add user message
const userMessage: PromptMessage = {
  role: 'user',
  content: [{ modality: 'text', value: 'Hello!' }]
};

// Combine for API call
const allMessages: PromptMessage[] = [
  ...systemMessages,
  userMessage
];
```

***

## Helper Functions

```typescript theme={null}
// Create text message
function createTextMessage(role: PromptMessage['role'], text: string): PromptMessage {
  return {
    role,
    content: [{ modality: 'text', value: text }]
  };
}

// Extract text from message
function getMessageText(message: PromptMessage): string {
  return message.content
    .filter(c => c.modality === 'text')
    .map(c => c.value)
    .join(' ');
}

// Check if message has images
function hasImages(message: PromptMessage): boolean {
  return message.content.some(c => c.modality === 'image');
}

// Filter messages by role
function filterByRole(
  messages: PromptMessage[],
  role: PromptMessage['role']
): PromptMessage[] {
  return messages.filter(m => m.role === role);
}

// Count tokens (rough estimate)
function estimateTokens(message: PromptMessage): number {
  const text = message.content
    .filter(c => c.modality === 'text')
    .map(c => c.value)
    .join(' ');
  
  return Math.ceil(text.length / 4); // Rough estimate
}

// Usage
const msg = createTextMessage('user', 'Hello!');
const text = getMessageText(msg);        // 'Hello!'
const hasImg = hasImages(msg);           // false
const tokens = estimateTokens(msg);      // ~2
```

***

## Validation

```typescript theme={null}
function isValidMessage(obj: any): obj is PromptMessage {
  return (
    typeof obj === 'object' &&
    ['system', 'user', 'assistant', 'tool'].includes(obj.role) &&
    Array.isArray(obj.content) &&
    obj.content.every((c: any) => 
      typeof c === 'object' && 
      typeof c.modality === 'string'
    )
  );
}

// Usage
const data = await fetchData();
if (isValidMessage(data)) {
  console.log(data.role);
}
```

***

## 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\"}"
    }
  ]
}
```