Mythosia.AI 2.2.1

Mythosia.AI

Package Summary

The Mythosia.AI library provides a unified interface for various AI models with multimodal support, including OpenAI GPT-4o, Anthropic Claude 3, Google Gemini, DeepSeek, and Perplexity Sonar.

🚀 What's New in v2.2.0

• Latest AI Models:
  • OpenAI GPT-5: Full support for GPT-5 series models (Gpt5, Gpt5Mini, Gpt5Nano, Gpt5ChatLatest)
  • OpenAI GPT-4.1: Support for GPT-4.1 series models (Gpt4_1, Gpt4_1Mini, Gpt4_1Nano)
  • Anthropic Claude 4: Support for latest Claude 4 Opus and Sonnet models
  • Google Gemini 2.5: Added Gemini 2.5 Pro, Flash, and Flash Lite models
  • Enhanced DeepSeek: DeepSeek Reasoner model support
• Model Migration: Deprecated Gemini15Pro and Gemini15Flash in favor of Gemini1_5Pro and Gemini1_5Flash
• Improved Stability: Enhanced error handling and model compatibility

Installation

dotnet add package Mythosia.AI

For advanced LINQ operations with streams:

dotnet add package System.Linq.Async

Important Usage Notes

Required Using Statements

Many convenient features are implemented as extension methods and require specific using statements:

// Core functionality
using Mythosia.AI;
using Mythosia.AI.Services;

// For MessageBuilder
using Mythosia.AI.Builders;

// For extension methods (IMPORTANT!)
using Mythosia.AI.Extensions;  // Required for:
                               // - BeginMessage()
                               // - WithSystemMessage()
                               // - WithTemperature()
                               // - WithMaxTokens()
                               // - AskOnceAsync()
                               // - StartNewConversation()
                               // - GetLastAssistantResponse()
                               // - And more...

// For models and enums
using Mythosia.AI.Models.Enums;

// For advanced LINQ operations (optional)
using System.Linq;

Common Issue: If BeginMessage() or other extension methods don't appear in IntelliSense, make sure you have added using Mythosia.AI.Extensions; at the top of your file.

Quick Start

Basic Setup

using Mythosia.AI;
using Mythosia.AI.Builders;
using Mythosia.AI.Extensions;
using System.Net.Http;

var httpClient = new HttpClient();
var aiService = new ChatGptService("your-api-key", httpClient);

Text-Only Queries

// Simple completion
string response = await aiService.GetCompletionAsync("What is AI?");

// With conversation history
await aiService.GetCompletionAsync("Tell me about machine learning");
await aiService.GetCompletionAsync("How does it differ from AI?"); // Remembers context

// One-off query (no history)
string quickAnswer = await aiService.AskOnceAsync("What time is it in Seoul?");

Streaming Responses

// Modern IAsyncEnumerable streaming
await foreach (var chunk in aiService.StreamAsync("Explain quantum computing"))
{
    Console.Write(chunk);
}

// One-off streaming without affecting conversation history
await foreach (var chunk in aiService.StreamOnceAsync("Quick question"))
{
    Console.Write(chunk);
}

// Traditional callback streaming (still supported)
await aiService.StreamCompletionAsync("Explain AI", 
    chunk => Console.Write(chunk));

// With cancellation support
var cts = new CancellationTokenSource();
await foreach (var chunk in aiService.StreamAsync("Long explanation", cts.Token))
{
    Console.Write(chunk);
    if (chunk.Contains("enough")) cts.Cancel();
}

Streaming Limitations:

• GPT-5 models: Streaming is not yet supported in this library. Use regular GetCompletionAsync() for GPT-5 models.
• All other models support both streaming and regular completion methods.

Image Analysis (Multimodal)

// Analyze a single image
var description = await aiService.GetCompletionWithImageAsync(
    "What's in this image?", 
    "photo.jpg"
);

// Compare multiple images using fluent API
var comparison = await aiService
    .BeginMessage()
    .AddText("What are the differences between these images?")
    .AddImage("before.jpg")
    .AddImage("after.jpg")
    .SendAsync();

// Stream image analysis
await foreach (var chunk in aiService
    .BeginMessage()
    .AddText("Describe this artwork in detail")
    .AddImage("painting.jpg")
    .WithHighDetail()
    .StreamAsync())
{
    Console.Write(chunk);
}

// One-off image query (doesn't affect conversation history)
var quickAnalysis = await aiService
    .BeginMessage()
    .AddText("What color is this?")
    .AddImage("sample.jpg")
    .SendOnceAsync();

Advanced Streaming with LINQ

// Requires: dotnet add package System.Linq.Async

// Take only first 1000 characters
var limitedResponse = await aiService
    .StreamAsync("Tell me a long story")
    .Take(100)  // Take first 100 chunks
    .ToListAsync();

// Filter empty chunks
await foreach (var chunk in aiService
    .StreamAsync("Explain something")
    .Where(c => !string.IsNullOrWhiteSpace(c)))
{
    ProcessChunk(chunk);
}

// Collect full response
var fullText = await aiService
    .StreamAsync("Explain AI")
    .ToListAsync()
    .ContinueWith(t => string.Concat(t.Result));

// Transform chunks
await foreach (var upper in aiService
    .StreamAsync("Hello")
    .Select(chunk => chunk.ToUpper()))
{
    Console.Write(upper);
}

Stateless Mode

// Enable stateless mode for all requests
aiService.StatelessMode = true;

// Each request is independent
await aiService.GetCompletionAsync("Translate: Hello");  // No history
await aiService.GetCompletionAsync("Translate: World");  // No history

// Or use one-off methods while maintaining conversation
aiService.StatelessMode = false;  // Back to normal

// These don't affect the conversation history
var oneOffResult = await aiService.AskOnceAsync("What time is it?");

await foreach (var chunk in aiService.StreamOnceAsync("Quick question"))
{
    Console.Write(chunk);
}

Fluent Message Building

// Build complex multimodal messages
var result = await aiService
    .BeginMessage()
    .WithRole(ActorRole.User)
    .AddText("Analyze this chart and explain the trend")
    .AddImage("sales-chart.png")
    .WithHighDetail()
    .SendAsync();

// Stream with fluent API
await foreach (var chunk in aiService
    .BeginMessage()
    .AddText("Compare these approaches:")
    .AddText("1. Traditional ML")
    .AddText("2. Deep Learning") 
    .AddImage("comparison.jpg")
    .StreamAsync())
{
    ProcessChunk(chunk);
}

// Using image URLs
var urlAnalysis = await aiService
    .BeginMessage()
    .AddText("What's in this image?")
    .AddImageUrl("https://example.com/image.jpg")
    .SendAsync();

Service-Specific Features

OpenAI GPT Models

var gptService = new ChatGptService(apiKey, httpClient);

// Use latest GPT-4o model (supports vision natively)
gptService.ActivateChat.ChangeModel(AIModel.Gpt4oLatest);

// GPT-5 models (available)
gptService.ActivateChat.ChangeModel(AIModel.Gpt5);

// Stream with GPT-4o
await foreach (var chunk in gptService
    .BeginMessage()
    .AddText("Analyze this complex diagram")
    .AddImage("diagram.png")
    .StreamAsync())
{
    Console.Write(chunk);
}

// Generate images
byte[] imageData = await gptService.GenerateImageAsync(
    "A futuristic city at sunset",
    "1024x1024"
);

// Audio features
// Text-to-Speech
byte[] audioData = await gptService.GetSpeechAsync(
    "Hello, world!", 
    voice: "alloy", 
    model: "tts-1"
);

// Speech-to-Text
string transcription = await gptService.TranscribeAudioAsync(
    audioData, 
    "audio.mp3", 
    language: "en"
);

Important Notes:

• GPT-4o models (gpt-4o-latest, gpt-4o, gpt-4o-2024-08-06, gpt-4o-2024-11-20) support vision natively
• gpt-4o-mini does NOT support vision
• gpt-4-vision-preview is deprecated, use gpt-4o instead
• GPT-5 models are available and support all core features
• ⚠️ GPT-5 streaming is not yet supported in this library (text completion only)

Anthropic Claude Models

var claudeService = new ClaudeService(apiKey, httpClient);

// Use latest Claude models
claudeService.ActivateChat.ChangeModel(AIModel.Claude3_5Sonnet241022);

// Claude 4 models (available)
claudeService.ActivateChat.ChangeModel(AIModel.ClaudeOpus4_250514);

// Claude models support vision natively
await foreach (var chunk in claudeService
    .BeginMessage()
    .AddText("Analyze this medical image")
    .AddImage("xray.jpg")
    .StreamAsync())
{
    Console.Write(chunk);
}

// Token counting
uint tokens = await claudeService.GetInputTokenCountAsync();

Google Gemini Models

var geminiService = new GeminiService(apiKey, httpClient);

// Use latest Gemini 2.5 models (recommended)
geminiService.ActivateChat.ChangeModel(AIModel.Gemini2_5Pro);

// Gemini 1.5 models (use new enum values)
geminiService.ActivateChat.ChangeModel(AIModel.Gemini1_5Pro);  // ✅ Recommended
// geminiService.ActivateChat.ChangeModel(AIModel.Gemini15Pro);  // ⚠️ Deprecated

// Stream multimodal analysis with Gemini 2.5
await foreach (var chunk in geminiService
    .BeginMessage()
    .AddText("What objects are in this image?")
    .AddImage("objects.jpg")
    .StreamAsync())
{
    ProcessChunk(chunk);
}

// Gemini Pro Vision for legacy support
geminiService.ActivateChat.ChangeModel(AIModel.GeminiProVision);

Model Migration Note:

• Gemini15Pro → Gemini1_5Pro (deprecated, please update)
• Gemini15Flash → Gemini1_5Flash (deprecated, please update)
• New Gemini 2.5 models offer improved performance and capabilities

DeepSeek Models

var deepSeekService = new DeepSeekService(apiKey, httpClient);

// Use Reasoner model for complex reasoning
deepSeekService.ActivateChat.ChangeModel(AIModel.DeepSeekReasoner);

// Stream code generation
deepSeekService.WithCodeGenerationMode("python");
await foreach (var chunk in deepSeekService.StreamAsync(
    "Write a fibonacci function"))
{
    Console.Write(chunk);
}

// Math mode with Chain of Thought
deepSeekService.WithMathMode();
var solution = await deepSeekService.GetCompletionWithCoTAsync(
    "Solve: 2x^2 + 5x - 3 = 0"
);

Perplexity Sonar Models

var sonarService = new SonarService(apiKey, httpClient);

// Use enhanced reasoning model
sonarService.ActivateChat.ChangeModel(AIModel.PerplexitySonarReasoning);

// Web search with streaming
await foreach (var chunk in sonarService.StreamAsync(
    "Latest AI breakthroughs in 2024"))
{
    Console.Write(chunk);
}

// Get search with citations
var searchResult = await sonarService.GetCompletionWithSearchAsync(
    "Recent developments in quantum computing",
    domainFilter: new[] { "arxiv.org", "nature.com" },
    recencyFilter: "month"
);

// Access citations
foreach (var citation in searchResult.Citations)
{
    Console.WriteLine($"{citation.Title}: {citation.Url}");
}

Advanced Usage

Conversation Management

// Start fresh conversation
aiService.StartNewConversation();

// Start with different model
aiService.StartNewConversation(AIModel.Claude3_5Sonnet241022);

// Switch models mid-conversation
aiService.SwitchModel(AIModel.Gpt4o241120);

// Get conversation info
var summary = aiService.GetConversationSummary();
var lastResponse = aiService.GetLastAssistantResponse();

// Retry last message
var betterResponse = await aiService.RetryLastMessageAsync();

// Clear specific messages
aiService.ActivateChat.RemoveLastMessage();
aiService.ActivateChat.ClearMessages();

Token Management

// Check tokens before sending
uint currentTokens = await aiService.GetInputTokenCountAsync();
if (currentTokens > 3000)
{
    aiService.ActivateChat.MaxMessageCount = 10; // Reduce history
}

// Check tokens for specific prompt
uint promptTokens = await aiService.GetInputTokenCountAsync("Long prompt...");

// Configure max tokens
aiService.WithMaxTokens(2000);

Configuration

// Method chaining for configuration
aiService
    .WithSystemMessage("You are a helpful coding assistant")
    .WithTemperature(0.7f)
    .WithMaxTokens(2000)
    .WithStatelessMode(false);

// Configure chat parameters
aiService.ActivateChat.Temperature = 0.5f;
aiService.ActivateChat.TopP = 0.9f;
aiService.ActivateChat.MaxTokens = 4096;
aiService.ActivateChat.MaxMessageCount = 20;

// Custom models
aiService.ActivateChat.ChangeModel("gpt-4-turbo-preview");

Error Handling

try
{
    await foreach (var chunk in aiService.StreamAsync(message))
    {
        Console.Write(chunk);
    }
}
catch (MultimodalNotSupportedException ex)
{
    Console.WriteLine($"Service {ex.ServiceName} doesn't support {ex.RequestedFeature}");
}
catch (TokenLimitExceededException ex)
{
    Console.WriteLine($"Too many tokens: {ex.RequestedTokens} > {ex.MaxTokens}");
}
catch (RateLimitExceededException ex)
{
    Console.WriteLine($"Rate limit hit. Retry after: {ex.RetryAfter}");
}
catch (AIServiceException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
    Console.WriteLine($"Details: {ex.ErrorDetails}");
}

Static Quick Methods

For one-off queries without managing service instances:

// Quick text query
var answer = await AIService.QuickAskAsync(
    apiKey, 
    "What's the capital of France?",
    AIModel.Gpt4oMini
);

// Quick image analysis
var description = await AIService.QuickAskWithImageAsync(
    apiKey,
    "Describe this image",
    "image.jpg",
    AIModel.Gpt4o240806
);

Model Support Matrix

*GPT-5 streaming support is not yet implemented in this library (text completion only)

Available Models

OpenAI Models

• GPT-5 Series: Gpt5, Gpt5Mini, Gpt5Nano, Gpt5ChatLatest
  • ⚠️ Note: GPT-5 models support text completion but streaming is not yet implemented in this library
  • Use GetCompletionAsync() instead of StreamAsync() for GPT-5 models
• GPT-4.1 Series: Gpt4_1, Gpt4_1Mini, Gpt4_1Nano
• GPT-4o Series: Gpt4oLatest, Gpt4o, Gpt4o241120, Gpt4o240806, Gpt4oMini
• Legacy: Gpt4Vision (deprecated)

Anthropic Claude Models

• Claude 4 Series: ClaudeOpus4_1_250805, ClaudeOpus4_250514, ClaudeSonnet4_250514
• Claude 3.7: Claude3_7SonnetLatest
• Claude 3.5: Claude3_5Sonnet241022, Claude3_5Haiku241022
• Claude 3: Claude3Opus240229, Claude3Haiku240307

Google Gemini Models

• Gemini 2.5 Series (Latest): Gemini2_5Pro, Gemini2_5Flash, Gemini2_5FlashLite
• Gemini 2.0: Gemini2_0Flash
• Gemini 1.5: Gemini1_5Pro, Gemini1_5Flash (use these instead of deprecated Gemini15Pro, Gemini15Flash)
• Legacy: GeminiPro, GeminiProVision

DeepSeek Models

• DeepSeekChat, DeepSeekReasoner

Perplexity Models

• PerplexitySonar, PerplexitySonarPro, PerplexitySonarReasoning

Best Practices

1. Model Selection:

   • Use latest model versions for best performance and features
   • Migrate from deprecated model enum values (e.g., Gemini15Pro → Gemini1_5Pro)
   • Use Gemini2_5Pro for newest Google capabilities
   • Use gpt-4o models for vision tasks
   • Use gpt-4o-mini for cost-effective text-only tasks

2. Streaming Best Practices:

   • Use StreamAsync() for better performance with long responses
   • Always handle cancellation tokens for user-initiated stops
   • Consider using StreamOnceAsync() for queries that don't need history
   • Use System.Linq.Async for advanced stream manipulation

3. Image Handling:

   • Keep images under 4MB
   • Supported formats: JPEG, PNG, GIF, WebP
   • Use WithHighDetail() for detailed analysis (costs more tokens)
   • For URLs, ensure they are publicly accessible

4. Performance:

   • Reuse HttpClient instances
   • Monitor token usage to manage costs
   • Use streaming for long responses
   • Enable stateless mode for independent queries

5. Error Handling:

   • Always wrap API calls in try-catch blocks
   • Check model capabilities before sending multimodal content
   • Handle rate limits gracefully with exponential backoff
   • Log errors for debugging

Migration Guide

Model Enum Updates

Update deprecated model references:

// ❌ Deprecated (will be removed in future versions)
service.ActivateChat.ChangeModel(AIModel.Gemini15Pro);
service.ActivateChat.ChangeModel(AIModel.Gemini15Flash);

// ✅ Use these instead
service.ActivateChat.ChangeModel(AIModel.Gemini1_5Pro);
service.ActivateChat.ChangeModel(AIModel.Gemini1_5Flash);

// ✅ Or upgrade to latest Gemini 2.5 models
service.ActivateChat.ChangeModel(AIModel.Gemini2_5Pro);
service.ActivateChat.ChangeModel(AIModel.Gemini2_5Flash);

From v2.0.x to v2.1.0

Version 2.1.0 adds IAsyncEnumerable support while maintaining full backward compatibility:

// Old way (still works)
await service.StreamCompletionAsync("Hello", chunk => Console.Write(chunk));

// New way (recommended)
await foreach (var chunk in service.StreamAsync("Hello"))
{
    Console.Write(chunk);
}

// Fluent API now supports both
await service.BeginMessage()
    .AddText("Hello")
    .StreamAsync(chunk => Console.Write(chunk));  // Callback version

await foreach (var chunk in service.BeginMessage()
    .AddText("Hello")
    .StreamAsync())  // IAsyncEnumerable version
{
    Console.Write(chunk);
}

From v1.x to v2.x

Version 2.x adds multimodal support and many new features. All v1.x code continues to work:

// This still works exactly as before
var response = await aiService.GetCompletionAsync("Hello");

New features are additive and optional.

Troubleshooting

Q: Extension methods like BeginMessage() not showing up?

• Add using Mythosia.AI.Extensions; to your file

Q: Want to use LINQ with streams?

• Install System.Linq.Async package: dotnet add package System.Linq.Async

Q: Getting "Channel not found" error?

• The project targets .NET Standard 2.1. Make sure your project targets .NET Core 3.0+ or .NET 5.0+

Q: Images not working with GPT-4?

• Use gpt-4o models, not the deprecated gpt-4-vision-preview
• Make sure images are in supported formats (JPEG, PNG, GIF, WebP)

Q: Getting obsolete warnings for Gemini models?

• Update Gemini15Pro to Gemini1_5Pro
• Update Gemini15Flash to Gemini1_5Flash
• Consider upgrading to newer Gemini2_5Pro or Gemini2_5Flash models

Q: GPT-5 streaming not working?

• GPT-5 streaming is not yet supported in this library
• Use GetCompletionAsync() instead of StreamAsync() for GPT-5 models
• All other models support both streaming and regular completion