FluentAI.NET 1.0.5

FLUENTAI.NET - Universal AI SDK for .NET

FluentAI.NET is a comprehensive, production-ready SDK that unifies access to multiple AI chat models under a single, elegant API. Built for .NET developers who want enterprise-grade AI capabilities without vendor lock-in or complex configuration.

📋 Table of Contents

• ✨ Key Features
• 🚀 Supported Providers
• 📦 Installation
• 🎯 Quick Start
• 🔧 Advanced Usage
• 🏗️ Architecture
• 📖 Documentation
• 🧪 Examples & Demos
• 🛠️ Integration Guides
• 🔐 Security
• ⚡ Performance
• 🧪 Testing
• 🤝 Contributing
• 📄 License
• 🆘 Support

✨ Key Features

🌟 Production-Ready Architecture

✅ Multi-Provider Support - OpenAI, Anthropic, Google AI with unified interface
✅ Enterprise Security - Input sanitization, content filtering, risk assessment
✅ Advanced Resilience - Rate limiting, automatic failover, circuit breakers
✅ Performance Optimized - Response caching, memory management, streaming support
✅ Observability Built-in - Comprehensive logging, metrics, health checks
✅ Dependency Injection - First-class support for modern .NET patterns

🔧 Developer Experience

✅ Simple Integration - Single interface for all providers
✅ Rich Configuration - Environment variables, appsettings.json, Azure Key Vault
✅ Comprehensive Examples - Working demos for all project types
✅ Extensive Documentation - API reference, integration guides, troubleshooting
✅ Strong Typing - Full IntelliSense support and compile-time safety
✅ Async/Await - Native async support with cancellation tokens

🛡️ Security & Compliance

✅ Input Validation - Prompt injection detection and prevention
✅ Content Filtering - Configurable safety filters and risk assessment
✅ Secure Logging - Automatic redaction of sensitive data
✅ API Key Protection - Secure storage and rotation support
✅ GDPR Compliance - Data protection and privacy controls

🚀 Supported Providers

Extensible Architecture - Add custom providers with minimal code

📦 Installation

# Single package includes all providers - no additional dependencies needed
dotnet add package FluentAI.NET

Supported Platforms:

• .NET 8.0+
• Windows, Linux, macOS
• Docker containers
• Azure Functions, AWS Lambda
• Blazor Server, Blazor WebAssembly

🎯 Quick Start

1. Set Up API Keys

# Environment Variables (Recommended)
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GOOGLE_API_KEY="your-google-api-key"

2. Configure Services

ASP.NET Core

var builder = WebApplication.CreateBuilder(args);

// Add FluentAI with automatic provider detection
builder.Services.AddAiSdk(builder.Configuration)
    .AddOpenAiChatModel(builder.Configuration)
    .AddAnthropicChatModel(builder.Configuration)
    .AddGoogleGeminiChatModel(builder.Configuration);

var app = builder.Build();

Console Application

var builder = Host.CreateDefaultBuilder(args)
    .ConfigureServices((context, services) =>
    {
        services.AddAiSdk(context.Configuration)
            .AddOpenAiChatModel(context.Configuration);
    });

using var host = builder.Build();

3. Configuration (appsettings.json)

{
  "AiSdk": {
    "DefaultProvider": "OpenAI",
    "Failover": {
      "PrimaryProvider": "OpenAI",
      "FallbackProvider": "Anthropic"
    }
  },
  "OpenAI": {
    "Model": "gpt-4",
    "MaxTokens": 2000,
    "RequestTimeout": "00:02:00",
    "PermitLimit": 100,
    "WindowInSeconds": 60
  },
  "Anthropic": {
    "Model": "claude-3-sonnet-20240229",
    "MaxTokens": 2000,
    "RequestTimeout": "00:02:00",
    "PermitLimit": 50,
    "WindowInSeconds": 60
  }
}

4. Use in Your Code

public class ChatController : ControllerBase
{
    private readonly IChatModel _chatModel;

    public ChatController(IChatModel chatModel)
    {
        _chatModel = chatModel;
    }

    [HttpPost("chat")]
    public async Task<IActionResult> Chat([FromBody] ChatRequest request)
    {
        var messages = new[]
        {
            new ChatMessage(ChatRole.System, "You are a helpful assistant."),
            new ChatMessage(ChatRole.User, request.Message)
        };

        try
        {
            var response = await _chatModel.GetResponseAsync(messages);
            return Ok(new { response = response.Content, model = response.ModelId });
        }
        catch (AiSdkRateLimitException)
        {
            return StatusCode(429, "Rate limit exceeded. Please try again later.");
        }
        catch (AiSdkException ex)
        {
            return BadRequest($"AI service error: {ex.Message}");
        }
    }

    [HttpPost("stream")]
    public async IAsyncEnumerable<string> StreamChat([FromBody] ChatRequest request)
    {
        var messages = new[] { new ChatMessage(ChatRole.User, request.Message) };
        
        await foreach (var token in _chatModel.StreamResponseAsync(messages))
        {
            yield return token;
        }
    }
}

🔧 Advanced Usage

Multi-Provider with Automatic Failover

// Configuration enables automatic failover
{
  "AiSdk": {
    "Failover": {
      "PrimaryProvider": "OpenAI",
      "FallbackProvider": "Anthropic"
    }
  }
}

// Transparent failover - no code changes needed
var response = await _chatModel.GetResponseAsync(messages);
// Uses OpenAI first, automatically falls back to Anthropic on errors

Provider-Specific Options

// OpenAI with advanced options
var openAiOptions = new OpenAiRequestOptions
{
    Temperature = 0.8f,
    MaxTokens = 1500,
    TopP = 0.9f,
    FrequencyPenalty = 0.1f
};

var response = await _chatModel.GetResponseAsync(messages, openAiOptions);

// Anthropic with system prompt
var anthropicOptions = new AnthropicRequestOptions
{
    SystemPrompt = "You are an expert software architect.",
    Temperature = 0.7f,
    MaxTokens = 2000
};

Security Features

public class SecureChatService
{
    private readonly IChatModel _chatModel;
    private readonly IInputSanitizer _sanitizer;

    public async Task<string> ProcessSecurelyAsync(string userInput)
    {
        // Security validation
        if (!_sanitizer.IsContentSafe(userInput))
            throw new SecurityException("Unsafe content detected");

        // Risk assessment
        var risk = _sanitizer.AssessRisk(userInput);
        if (risk.RiskLevel >= SecurityRiskLevel.High)
            throw new SecurityException($"High risk content: {string.Join(", ", risk.DetectedConcerns)}");

        // Sanitize input
        var sanitizedInput = _sanitizer.SanitizeContent(userInput);
        
        var messages = new[] { new ChatMessage(ChatRole.User, sanitizedInput) };
        var response = await _chatModel.GetResponseAsync(messages);
        
        return response.Content;
    }
}

Performance Optimization

public class PerformantChatService
{
    private readonly IChatModel _chatModel;
    private readonly IResponseCache _cache;
    private readonly IPerformanceMonitor _monitor;

    public async Task<ChatResponse> GetCachedResponseAsync(IEnumerable<ChatMessage> messages)
    {
        // Check cache first
        var cachedResponse = await _cache.GetAsync(messages);
        if (cachedResponse != null)
            return cachedResponse;

        // Monitor performance
        using var operation = _monitor.StartOperation("ChatCompletion");
        
        var response = await _chatModel.GetResponseAsync(messages);
        
        // Cache successful responses
        await _cache.SetAsync(messages, null, response, TimeSpan.FromMinutes(30));
        
        // Record metrics
        _monitor.RecordMetric("ResponseLength", response.Content.Length);
        _monitor.IncrementCounter("RequestsProcessed");
        
        return response;
    }
}

Resilience and Error Handling

public class ResilientChatService
{
    public async Task<string> GetResponseWithRetryAsync(IEnumerable<ChatMessage> messages)
    {
        var retryPolicy = Policy
            .Handle<AiSdkRateLimitException>()
            .Or<HttpRequestException>()
            .WaitAndRetryAsync(
                retryCount: 3,
                sleepDurationProvider: attempt => TimeSpan.FromSeconds(Math.Pow(2, attempt)),
                onRetry: (outcome, timespan, retryCount, context) =>
                {
                    _logger.LogWarning("Retry {RetryCount} after {Delay}ms", retryCount, timespan.TotalMilliseconds);
                });

        return await retryPolicy.ExecuteAsync(async () =>
        {
            var response = await _chatModel.GetResponseAsync(messages);
            return response.Content;
        });
    }
}

🏗️ Architecture

FluentAI.NET follows clean architecture principles with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                        │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │   Controllers   │ │    Services     │ │  Components  │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                  FluentAI.NET Abstractions                 │
│  ┌─────────────────┐ ┌─────────────────┐ ┌──────────────┐   │
│  │   IChatModel    │ │  IInputSanitizer│ │ IPerformance │   │
│  │                 │ │                 │ │   Monitor    │   │
│  └─────────────────┘ └─────────────────┘ └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    Provider Layer                          │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────┐ │
│  │   OpenAI    │ │  Anthropic  │ │   Google    │ │ Custom │ │
│  │  Provider   │ │   Provider  │ │   Provider  │ │Provider│ │
│  └─────────────┘ └─────────────┘ └─────────────┘ └────────┘ │
└─────────────────────────────────────────────────────────────┘

Key Components:

• Abstractions Layer: Core interfaces and models
• Provider Layer: AI service implementations
• Configuration Layer: Strongly-typed configuration
• Security Layer: Input validation and risk assessment
• Performance Layer: Caching, monitoring, and optimization
• Extensions Layer: Dependency injection and fluent configuration

📖 Documentation

📚 Core Documentation

• API Reference - Complete API documentation with examples
• Security Guide - Security best practices and compliance
• Contributing Guide - Development guidelines and processes

🛠️ Integration Guides

• Console Applications - Complete setup with DI
• ASP.NET Core - Web APIs with middleware
• Blazor - Interactive web UIs with real-time streaming
• Common Patterns - Best practices and reusable code
• Troubleshooting - Common issues and solutions

🔧 Advanced Topics

• Performance Optimization - Caching, streaming, memory management
• Security Implementation - Input validation, content filtering
• Error Handling - Resilience patterns, retry logic
• Testing Strategies - Unit tests, integration tests, mocking

🧪 Examples & Demos

🎮 Interactive Console Demo

Explore all SDK features with our comprehensive console application:

cd Examples/ConsoleApp
dotnet run

Features Demonstrated:

• 💬 Basic chat completion with multiple providers
• 🌊 Real-time streaming responses
• 🔄 Provider comparison and failover
• 🔒 Security features and input sanitization
• ⚡ Performance monitoring and caching
• ⚙️ Configuration management
• 🚨 Error handling and resilience patterns

📝 Code Examples

Simple Chat

var messages = new[] { new ChatMessage(ChatRole.User, "Hello!") };
var response = await chatModel.GetResponseAsync(messages);
Console.WriteLine(response.Content);

Streaming Chat

await foreach (var token in chatModel.StreamResponseAsync(messages))
{
    Console.Write(token);
}

Multiple Providers

// Configuration-based provider switching
var openAIResponse = await openAIModel.GetResponseAsync(messages);
var anthropicResponse = await anthropicModel.GetResponseAsync(messages);

// Compare responses or use as fallback

🛠️ Integration Guides

Quick Integration Matrix

Configuration Patterns

All integration guides include:

• ✅ Step-by-step setup instructions
• ✅ Complete working code examples
• ✅ Configuration best practices
• ✅ Security considerations
• ✅ Performance optimization
• ✅ Testing strategies
• ✅ Troubleshooting tips

🔐 Security

Built-in Security Features

// Input sanitization
var sanitizer = serviceProvider.GetRequiredService<IInputSanitizer>();
var safeContent = sanitizer.SanitizeContent(userInput);
var riskLevel = sanitizer.AssessRisk(userInput);

// Secure logging (automatic API key redaction)
_logger.LogInformation("Processing request from {UserId}", userId);
// API keys are automatically redacted from logs

// Content filtering
if (riskLevel.RiskLevel >= SecurityRiskLevel.High)
{
    throw new SecurityException("High-risk content detected");
}

Security Best Practices

• 🔑 API Key Management: Environment variables, Azure Key Vault integration
• 🛡️ Input Validation: Prompt injection detection and prevention
• 🔍 Content Filtering: Configurable safety filters and risk assessment
• 📝 Secure Logging: Automatic redaction of sensitive information
• 🚫 Rate Limiting: Prevent abuse and DoS attacks
• 🔐 Compliance: GDPR, CCPA, SOC 2 compliance support

⚡ Performance

Performance Features

• Response Caching: Intelligent caching with configurable TTL
• Streaming Support: Real-time token streaming for better UX
• Memory Management: Efficient memory usage and cleanup
• Connection Pooling: Optimized HTTP client management
• Metrics Collection: Built-in performance monitoring

Benchmarks

Benchmarks vary based on provider, model, and network conditions.

Performance Monitoring

// Built-in performance monitoring
var monitor = serviceProvider.GetRequiredService<IPerformanceMonitor>();

using var operation = monitor.StartOperation("ChatCompletion");
var response = await chatModel.GetResponseAsync(messages);

// Automatic metrics collection
// - Request duration
// - Token usage
// - Success/failure rates
// - Memory usage

🧪 Testing

Test Suite Overview

• 235+ Tests with 90%+ code coverage
• Unit Tests: Fast, isolated tests for all components
• Integration Tests: Real provider testing with API keys
• Performance Tests: Benchmarking and load testing
• Security Tests: Vulnerability and penetration testing

Testing Your Integration

// Unit testing with mocks
[Test]
public async Task GetResponse_ShouldReturnExpectedContent()
{
    var mockChatModel = new Mock<IChatModel>();
    mockChatModel.Setup(x => x.GetResponseAsync(It.IsAny<IEnumerable<ChatMessage>>(), null, default))
        .ReturnsAsync(new ChatResponse { Content = "Test response" });

    var service = new ChatService(mockChatModel.Object);
    var result = await service.GetResponseAsync("Test message");

    Assert.AreEqual("Test response", result);
}

// Integration testing
[Test, Category("Integration")]
public async Task RealProvider_ShouldWork()
{
    var services = new ServiceCollection();
    services.AddAiSdk(Configuration).AddOpenAiChatModel(Configuration);
    
    using var provider = services.BuildServiceProvider();
    var chatModel = provider.GetRequiredService<IChatModel>();
    
    var response = await chatModel.GetResponseAsync(testMessages);
    Assert.IsNotEmpty(response.Content);
}

Running Tests

# Run all tests
dotnet test

# Run only unit tests
dotnet test --filter Category!=Integration

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run performance tests
dotnet test --filter Category=Performance

🤝 Contributing

We welcome contributions! See our Contributing Guide for:

• 🐛 Bug Reports - Help us identify and fix issues
• ✨ Feature Requests - Suggest new capabilities
• 📖 Documentation - Improve guides and examples
• 🧪 Testing - Add test coverage and scenarios
• 🔧 Code Contributions - Submit pull requests

Quick Start for Contributors

# Fork and clone
git clone https://github.com/YOUR_USERNAME/fluentai-dotnet.git
cd fluentai-dotnet

# Build and test
dotnet restore
dotnet build
dotnet test

# Make your changes and submit a PR

Development Requirements:

• .NET 8.0 SDK
• API keys for testing (optional)
• IDE with C# support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Key Points:

• ✅ Commercial use allowed
• ✅ Modification and distribution allowed
• ✅ Private use allowed
• ❌ No warranty provided
• ❌ No liability assumed