Chat Basics

Overview

Chat functionality is the core feature of LlmTornado, allowing you to have conversations with various AI providers including OpenAI, Google Gemini, and Anthropic Claude. This guide covers the fundamental concepts and patterns for setting up and using chat conversations in your applications.

Quick Start

Here's a simple example to get you started with basic chat functionality:

csharp

using LlmTornado;
using LlmTornado.Chat;

// Initialize the API client
var api = new TornadoApi("your-api-key-here");

// Create a conversation with initial messages
var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    Messages = [
        new ChatMessage(ChatMessageRoles.System, "You are a helpful programming assistant."),
        new ChatMessage(ChatMessageRoles.User, "Hello! Can you help me with a programming question?")
    ]
});

// Get the response
ChatRichResponse response = await conversation.GetResponseRich();

Console.WriteLine($"Assistant: {response.Text}");

Prerequisites

Before using chat functionality, ensure you have:

An API key from your preferred AI provider (OpenAI, Google, or Anthropic)
The LlmTornado package installed via NuGet: Install-Package LlmTornado
Basic understanding of C# and async programming

Detailed Explanation

Understanding the Chat Flow

LlmTornado uses a conversation-based approach where you:

Create a conversation - Sets up the chat session with a specific model
Add messages - Both user and assistant messages are added to the conversation history
Get responses - The AI processes the conversation history and generates a response
Continue the conversation - Add more messages to have an ongoing dialogue

Key Components

TornadoApi

The main entry point for all LlmTornado functionality. It handles authentication and provides access to different services.

csharp

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

ChatRequest

Configures how the conversation should behave:

Model: Specifies which AI model to use
Temperature: Controls randomness (0.0-1.0 for most models, default 1.0)
MaxTokens: Limits response length in tokens
Messages: Collection of chat messages in the conversation

csharp

var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    Temperature = 0.7,
    MaxTokens = 150
});

// Add a system message to guide the AI's behavior
conversation.Messages.Add(new ChatMessage(ChatMessageRoles.System, "You are a helpful programming assistant."));

Conversation

Manages the conversation state and message history:

AddUserMessage(): Adds a message from the user
AddAssistantMessage(): Adds a message from the AI (typically after getting a response)
GetResponseRich(): Gets a response from the AI
Serialize(): Converts the conversation to a format suitable for storage or transmission

Basic Usage

Simple Conversation

csharp

// Create conversation
var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5
});

// Create conversation with initial messages
var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    Messages = [
        new ChatMessage(ChatMessageRoles.User, "What is C#?")
    ]
});

// Get response
ChatRichResponse response = await conversation.GetResponseRich();

// The response contains the assistant's message
Console.WriteLine(response.Text);

// Add another message to continue the conversation
conversation.AddUserMessage("Can you give me a simple example?");
ChatRichResponse followUp = await conversation.GetResponseRich();
Console.WriteLine(followUp.Text);

Using Different Models

LlmTornado supports multiple AI providers with their latest models:

csharp

// OpenAI GPT-5 (latest flagship model)
var openaiConversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5
});

// Google Gemini 2.5 Flash (latest standard model)
var geminiConversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.Google.Gemini.Gemini25Flash
});

// Anthropic Claude 4.5 Sonnet (latest balanced model)
var claudeConversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.Anthropic.Claude45.Sonnet250929
});

Setting System Messages

System messages help guide the AI's behavior:

csharp

var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5
});

// Add a system message to guide the AI's behavior
conversation.Messages.Add(new ChatMessage(ChatMessageRoles.System, "You are a friendly and helpful assistant. Always respond in a cheerful tone."));

conversation.AddUserMessage("I'm having a bad day.");
// The AI will respond in a cheerful tone as instructed

Controlling Response Length

csharp

var conversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    MaxTokens = 100  // Limit response to 100 tokens (approximately 75 words, but varies by model)
});

conversation.AddUserMessage("Explain quantum computing in simple terms.");
ChatRichResponse response = await conversation.GetResponseRich();

Advanced Usage

Temperature and Creativity

Temperature controls how random the AI's responses are:

csharp

// Low temperature (0.1-0.5) - More focused and deterministic
var focusedConversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    Temperature = 0.3
});

// High temperature (0.8-1.0) - More creative and varied
var creativeConversation = api.Chat.CreateConversation(new ChatRequest
{
    Model = ChatModel.OpenAi.Gpt5.V5,
    Temperature = 0.9
});

Conversation History

The conversation maintains history automatically:

csharp

// The conversation remembers previous messages
conversation.AddUserMessage("My name is Alex.");
var response1 = await conversation.GetResponseRich();

conversation.AddUserMessage("What's my name?");
var response2 = await conversation.GetResponseRich();

// The AI will remember that your name is Alex
Console.WriteLine(response2.Text); // Should mention "Alex"

Error Handling

Always include proper error handling:

csharp

try
{
    var conversation = api.Chat.CreateConversation(new ChatRequest
    {
        Model = ChatModel.OpenAi.Gpt5.V5
    });

    conversation.AddUserMessage("Hello!");
    
    try
    {
        ChatRichResponse response = await conversation.GetResponseRich();
        Console.WriteLine(response.Text);
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error getting response: {ex.Message}");
        // Handle API errors, rate limiting, etc.
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Error setting up conversation: {ex.Message}");
}

Best Practices

1. Use Appropriate Models

Use ChatModel.OpenAi.Gpt35.Turbo for simple, fast responses
Use ChatModel.OpenAi.Gpt5.V5 for balanced performance and cost
Use provider-specific models for specialized capabilities

2. Manage Context Length

Be mindful of token limits for each model
For long conversations, consider summarizing or truncating history
Use MaxTokens to prevent overly long responses

3. Handle Rate Limiting

Implement retry logic for API calls
Handle rate limiting gracefully with exponential backoff
Monitor usage to avoid hitting quotas

4. Validate Responses

Always validate AI responses before using them
Sanitize outputs if they'll be displayed to users
Implement fallback responses for critical applications

Common Issues

API Key Problems

Issue: "Invalid API key" errors
Solution: Verify your API key is correct and has the necessary permissions
Prevention: Store API keys securely using environment variables or secret management

Model Not Available

Issue: Model not found or unavailable
Solution: Check if the model name is correct and available in your region
Prevention: Use model constants from the library instead of hardcoded strings

Rate Limiting

Issue: Too many requests in a short time
Solution: Implement rate limiting and retry logic
Prevention: Monitor usage and implement request queuing if needed

Context Length Exceeded

Issue: "Context length exceeded" errors
Solution: Reduce conversation history or increase context window
Prevention: Implement conversation summarization for long sessions

API Reference

TornadoApi

TornadoApi(string apiKey) - Initialize with API key
Chat - Property to access chat functionality

ChatRequest

Model ChatModel - The AI model to use
double? Temperature - Response randomness (0.0-1.0 for most models)
int? MaxTokens - Maximum response length in tokens
List<ChatMessage>? Messages - Collection of chat messages
ChatRequestResponseFormats? ResponseFormat - Response format options

Conversation

void AddUserMessage(string content) - Add user message
void AddAssistantMessage(string content) - Add assistant message
Task<ChatRichResponse> GetResponseRich() - Get AI response
Task<string> GetResponse() - Get simple text response
TornadoRequestContent Serialize() - Serialize conversation

ChatRichResponse

string Text - The text content of the response
List<ChatRichResponseBlock> Blocks - The response blocks (text, tool calls, etc.)
ChatUsage? Usage - Token usage statistics
ChatResult? Result - The full API result

Chat Models - Learn about available models and providers
Messages - Detailed guide on message types and handling
Conversations - Advanced conversation management
Streaming - Real-time streaming responses
Function Calling - Using AI functions and tools

Chat Basics ​

Overview ​

Quick Start ​

Prerequisites ​

Detailed Explanation ​

Understanding the Chat Flow ​

Key Components ​

TornadoApi ​

ChatRequest ​

Conversation ​

Basic Usage ​

Simple Conversation ​

Using Different Models ​

Setting System Messages ​

Controlling Response Length ​

Advanced Usage ​

Temperature and Creativity ​

Conversation History ​

Error Handling ​

Best Practices ​

1. Use Appropriate Models ​

2. Manage Context Length ​

3. Handle Rate Limiting ​

4. Validate Responses ​

Common Issues ​

API Key Problems ​

Model Not Available ​

Rate Limiting ​

Context Length Exceeded ​

API Reference ​

TornadoApi ​

ChatRequest ​

Conversation ​

ChatRichResponse ​

Related Topics ​

Chat Basics

Overview

Quick Start

Prerequisites

Detailed Explanation

Understanding the Chat Flow

Key Components

TornadoApi

ChatRequest

Conversation

Basic Usage

Simple Conversation

Using Different Models

Setting System Messages

Controlling Response Length

Advanced Usage

Temperature and Creativity

Conversation History

Error Handling

Best Practices

1. Use Appropriate Models

2. Manage Context Length

3. Handle Rate Limiting

4. Validate Responses

Common Issues

API Key Problems

Model Not Available

Rate Limiting

Context Length Exceeded

API Reference

TornadoApi

ChatRequest

Conversation

ChatRichResponse

Related Topics