Chat Messages

Overview

Messages are the building blocks of conversations in LlmTornado. Understanding how to effectively structure and manage messages is essential for creating rich, interactive AI experiences. This guide covers all aspects of working with messages, including different message types, roles, content formats, and advanced features.

Quick Start

Here's a basic example of creating and using messages:

using LlmTornado;
using LlmTornado.Chat;
using LlmTornado.Chat.Models;

TornadoApi api = new TornadoApi("your-api-key");

// Create a conversation with messages
ChatResult? result = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt4.Turbo,
    Messages = [
        new ChatMessage(ChatMessageRoles.System, "You are a helpful assistant."),
        new ChatMessage(ChatMessageRoles.User, "What is the capital of France?")
    ]
});

Console.WriteLine(result?.Choices?[0].Message?.Content);

Prerequisites

Before working with messages, ensure you have:

1. The LlmTornado package installed
2. A valid API key configured
3. Understanding of Chat Basics

Detailed Explanation

Message Roles

LlmTornado supports several message roles that define the context and purpose of each message:

System Messages

System messages set the behavior and context for the AI assistant. They are processed first and help guide the assistant's responses throughout the conversation.

ChatMessage systemMessage = new ChatMessage(ChatMessageRoles.System, 
    "You are a helpful programming tutor. Explain concepts clearly and provide examples.");

User Messages

User messages represent input from the end user. These are the questions or prompts that the AI will respond to.

ChatMessage userMessage = new ChatMessage(ChatMessageRoles.User, 
    "How do I create a list in Python?");

Assistant Messages

Assistant messages represent responses from the AI. You can also manually add assistant messages to provide context or continue a conversation.

ChatMessage assistantMessage = new ChatMessage(ChatMessageRoles.Assistant, 
    "To create a list in Python, use square brackets: my_list = [1, 2, 3]");

Message Content Types

Messages can contain different types of content beyond simple text:

Text Content

The most common type of message content:

ChatMessage message = new ChatMessage(ChatMessageRoles.User, "Hello, how are you?");

Multipart Messages

Messages can contain multiple parts, including text and images:

ChatMessage message = new ChatMessage(ChatMessageRoles.User, [
    new ChatMessagePart("What's in this image?"),
    new ChatMessagePart(new Uri("https://example.com/image.jpg"))
]);

Basic Usage

Creating Simple Messages

// Create a system message
ChatMessage system = new ChatMessage(ChatMessageRoles.System, 
    "You are a math tutor.");

// Create a user message
ChatMessage user = new ChatMessage(ChatMessageRoles.User, 
    "What is 15 * 23?");

// Use in a chat request
ChatResult? result = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt4.Turbo,
    Messages = [ system, user ]
});

Building Conversations

List<ChatMessage> messages = [
    new ChatMessage(ChatMessageRoles.System, "You are a helpful assistant."),
    new ChatMessage(ChatMessageRoles.User, "Tell me a joke."),
    new ChatMessage(ChatMessageRoles.Assistant, "Why did the programmer quit? Because they didn't get arrays!"),
    new ChatMessage(ChatMessageRoles.User, "That's funny! Tell me another one.")
];

ChatResult? result = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt35Turbo,
    Messages = messages
});

Using the Conversation API

The Conversation API provides a higher-level abstraction for message management:

Conversation conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt4.Turbo
});

// Add messages
conversation.AddUserMessage("What's the weather like?");
ChatRichResponse response = await conversation.GetResponseRich();

conversation.AddUserMessage("What about tomorrow?");
ChatRichResponse followUp = await conversation.GetResponseRich();

Advanced Usage

JSON Response Format

Request structured JSON responses from the AI:

ChatResult? result = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt4.Turbo,
    ResponseFormat = ChatRequestResponseFormats.Json,
    Messages = [
        new ChatMessage(ChatMessageRoles.System, 
            "Solve the math problem given by user, respond in JSON format."),
        new ChatMessage(ChatMessageRoles.User, "2+2=?")
    ]
});

Console.WriteLine(result?.Choices?[0].Message?.Content);
// Output: {"result": 4, "equation": "2+2"}

Message with Images (Vision)

Send images along with text for multimodal analysis:

ChatResult? result = await api.Chat.CreateChatCompletion([
    new ChatMessage(ChatMessageRoles.User, [
        new ChatMessagePart(new Uri("https://example.com/image.jpg")),
        new ChatMessagePart("What is in this image?")
    ])
], ChatModel.OpenAi.Gpt4.VisionPreview, maxTokens: 256);

Console.WriteLine(result?.Choices?[0].Message?.Content);

Base64 Encoded Images

You can also send images as base64-encoded strings:

byte[] bytes = await File.ReadAllBytesAsync("path/to/image.jpg");
string base64 = $"data:image/jpeg;base64,{Convert.ToBase64String(bytes)}";

ChatResult? result = await api.Chat.CreateChatCompletion([
    new ChatMessage(ChatMessageRoles.User, [
        new ChatMessagePart(base64, ImageDetail.Auto),
        new ChatMessagePart("Describe this image in detail.")
    ])
], ChatModel.OpenAi.Gpt4.VisionPreview, maxTokens: 256);

Managing Message History

Control conversation context by managing message history:

List<ChatMessage> messages = [];

// Add initial context
messages.Add(new ChatMessage(ChatMessageRoles.System, 
    "You are a helpful assistant."));

// Add user message
messages.Add(new ChatMessage(ChatMessageRoles.User, "My name is Alex."));

// Get response
ChatResult? result1 = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt35Turbo,
    Messages = messages
});

// Add assistant response to history
messages.Add(result1?.Choices?[0].Message!);

// Continue conversation
messages.Add(new ChatMessage(ChatMessageRoles.User, "What's my name?"));

ChatResult? result2 = await api.Chat.CreateChatCompletion(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt35Turbo,
    Messages = messages
});

// The AI will remember the name is Alex
Console.WriteLine(result2?.Choices?[0].Message?.Content);

Best Practices

1. Use Appropriate System Messages

• Provide clear, concise instructions in system messages
• Set the tone and behavior expectations upfront
• Include any important context or constraints

2. Manage Context Length

• Monitor the total token count of your message history
• Implement message pruning for long conversations
• Consider summarizing older messages to save tokens

3. Structure Multipart Messages Properly

• Place images before related text questions
• Use descriptive text alongside images
• Respect the model's multimodal capabilities

4. Handle Message Validation

• Validate message content before sending
• Ensure required fields are populated
• Check for empty or null content

Common Issues

Context Length Exceeded

• Issue: Error when message history is too long
• Solution: Prune older messages or summarize conversation
• Prevention: Monitor token usage and implement sliding window

Invalid Message Format

• Issue: API rejects malformed messages
• Solution: Ensure proper role and content structure
• Prevention: Use library constructors and validate before sending

Missing System Message

• Issue: Inconsistent AI behavior
• Solution: Always include a clear system message
• Prevention: Set system message at conversation start

Image Format Issues

• Issue: Images not being processed correctly
• Solution: Verify image encoding and URL accessibility
• Prevention: Test image formats and sizes before deployment

API Reference

ChatMessage

• ChatMessage(string role, string content) - Create simple text message
• ChatMessage(string role, List<ChatMessagePart> parts) - Create multipart message
• Role - Message role (system, user, assistant)
• Content - Message text content
• Parts - List of message parts for multipart messages

ChatMessageRoles

• System - System instruction messages
• User - User input messages
• Assistant - AI assistant responses

ChatMessagePart

• ChatMessagePart(string text) - Create text part
• ChatMessagePart(Uri imageUrl) - Create image URL part
• ChatMessagePart(string base64, ImageDetail detail) - Create base64 image part

ChatRequestResponseFormats

• Json - Request JSON formatted response
• Text - Standard text response

Related Topics

• Chat Basics - Fundamental chat concepts
• Structured Output - Working with JSON schemas
• Vision - Detailed vision capabilities
• Streaming - Real-time message streaming