Skip to main content

​
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:

​
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.' }
  ]
};

​
Multi-Modal Message

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