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 page for full documentation. Message role enumeration for chat messages.

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:

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:

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

Filtering Messages:

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.

interface PromptMessage {
  role: MessageRole;
  content: MessageContent[];
}

Properties:

role - Message sender role (MessageRole)
content - Array of content items (MessageContent)

Examples

Simple Text Message

import type { PromptMessage } from '@adaline/api';

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

System Message

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

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

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

// 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

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

// 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

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

{
  "role": "user",
  "content": [
    { "modality": "text", "value": "Hello!" }
  ]
}

With Image

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

Tool Call

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

Get started

API

SDKs

Proxy

PromptMessage

PromptMessage

Overview

MessageRole

PromptMessage

Examples

Simple Text Message

System Message

Conversation History

Tool Call Sequence

Using with Deployments

Helper Functions

Validation

JSON Examples

Simple

With Image

Tool Call

​PromptMessage

​Overview

​MessageRole

​PromptMessage

​Examples

​Simple Text Message

​System Message

​Multi-Modal Message

​Conversation History

​Tool Call Sequence

​Using with Deployments

​Helper Functions

​Validation

​JSON Examples

​Simple

​With Image

​Tool Call

PromptMessage

Overview

MessageRole

PromptMessage

Examples

Simple Text Message

System Message

Multi-Modal Message

Conversation History

Tool Call Sequence

Using with Deployments

Helper Functions

Validation

JSON Examples

Simple

With Image

Tool Call