OllamaApiClient.Client 1.0.0

OllamaApiClient

A modern, comprehensive C# library for interacting with the Ollama API, providing both streaming and non-streaming operations with full .NET integration.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• API Examples
• Dependency Injection
• Error Handling
• Contributing
• License

Features

OllamaApiClient provides a complete, production-ready C# interface for the Ollama API:

✅ Fully Implemented Endpoints

❌ Not Implemented Endpoints

The following endpoints are not implemented in this version:

• /api/create - Create/customize models from Modelfile
• /api/push - Push models to remote registry
• /api/blobs/* - Blob management operations

🏗️ Architecture Features

• Modern .NET Design: Built for .NET 9.0 with nullable reference types
• Async/Await Patterns: Full async support with proper cancellation handling
• Streaming Support: Real-time response streaming using IAsyncEnumerable<T>
• Comprehensive API Coverage: 10/13 Ollama endpoints implemented (77% coverage)
• Dependency Injection: First-class support for Microsoft DI container
• HttpClient Integration: Optimized HTTP client usage with IHttpClientFactory
• Comprehensive Error Handling: Structured exception hierarchy
• Production Ready: Logging, validation, and security best practices

Installation

Via NuGet Package Manager

dotnet add package OllamaApiClient

Via Package Manager Console

Install-Package OllamaApiClient

Via PackageReference

<PackageReference Include="OllamaApiClient" Version="1.0.0" />

Quick Start

Basic Usage

using OllamaApiClient.Core.Interfaces;
using OllamaApiClient.Core.Models;
using OllamaApiClient.Client.Services;

// Create HTTP client
var httpClient = new HttpClient 
{ 
    BaseAddress = new Uri("http://localhost:11434") 
};

// Initialize the Ollama client
IOllamaClient client = new OllamaClient(httpClient);

// Generate text completion
var request = new GenerateRequest
{
    Model = "llama3.2",
    Prompt = "Explain the benefits of using C# for modern applications"
};

var response = await client.GenerateCompletionAsync(request);
Console.WriteLine(response.Response);

Streaming Example

// Stream responses in real-time
await foreach (var chunk in client.GenerateCompletionStreamAsync(request))
{
    Console.Write(chunk.Response);
}

Configuration

Using Options Pattern

using OllamaApiClient.Core.Models;

var options = new OllamaClientOptions
{
    BaseAddress = new Uri("http://localhost:11434"),
    Timeout = TimeSpan.FromMinutes(5),
    DefaultRequestHeaders = new Dictionary<string, string>
    {
        ["User-Agent"] = "MyApp/1.0.0"
    }
};

Environment Configuration

// Configure via environment variables
Environment.SetEnvironmentVariable("OLLAMA_BASE_URL", "http://localhost:11434");
Environment.SetEnvironmentVariable("OLLAMA_TIMEOUT", "300"); // seconds

API Examples

Chat Completion

var chatRequest = new ChatRequest
{
    Model = "llama3.2",
    Messages = new List<ChatMessage>
    {
        new() { Role = "system", Content = "You are a helpful programming assistant." },
        new() { Role = "user", Content = "How do I implement async/await in C#?" }
    }
};

var chatResponse = await client.ChatCompletionAsync(chatRequest);
Console.WriteLine(chatResponse.Message.Content);

Model Management

// List available models
var models = await client.ListLocalModelsAsync();
foreach (var model in models.Models)
{
    Console.WriteLine($"Model: {model.Name}, Size: {model.Size:N0} bytes");
}

// Get model details
var modelInfo = await client.GetModelInfoAsync("llama3.2");
Console.WriteLine($"Parameters: {modelInfo.Details?.ParameterSize}");

// Pull (download) a model with progress tracking
var pullRequest = new PullRequest { Model = "llama3.2" };

// Option 1: Streaming with progress updates
await foreach (var progress in client.PullModelStreamAsync(pullRequest))
{
    Console.WriteLine($"Status: {progress.Status}, Progress: {progress.Completed}/{progress.Total}");
}

// Option 2: Non-streaming (wait for completion)
var pullResult = await client.PullModelAsync(pullRequest);
Console.WriteLine($"Pull completed: {pullResult.Status}");

// Copy a model
await client.CopyModelAsync("llama3.2", "my-custom-model");

// Delete a model
await client.DeleteModelAsync("old-model");

Embeddings

var embedRequest = new EmbedRequest
{
    Model = "nomic-embed-text",
    Input = new[] { "Hello world", "Semantic search example" }
};

var embedResponse = await client.GenerateEmbeddingsAsync(embedRequest);
foreach (var embedding in embedResponse.Embeddings)
{
    Console.WriteLine($"Embedding dimension: {embedding.Length}");
}

Advanced Generation Options

var advancedRequest = new GenerateRequest
{
    Model = "codellama",
    Prompt = "def fibonacci(",
    Suffix = "    return result",  // For code completion
    Options = new Dictionary<string, object>
    {
        ["temperature"] = 0.7f,
        ["max_tokens"] = 150,
        ["top_p"] = 0.9f
    },
    Stream = false
};

Dependency Injection

ASP.NET Core Integration

using OllamaApiClient.Extensions.DependencyInjection;

// In Program.cs or Startup.cs
builder.Services.AddOllamaClient(options =>
{
    options.BaseAddress = new Uri("http://localhost:11434");
    options.Timeout = TimeSpan.FromMinutes(5);
});

// In your controller or service
public class AIService
{
    private readonly IOllamaClient _ollamaClient;
    
    public AIService(IOllamaClient ollamaClient)
    {
        _ollamaClient = ollamaClient;
    }
    
    public async Task<string> GenerateTextAsync(string prompt)
    {
        var request = new GenerateRequest { Model = "llama3.2", Prompt = prompt };
        var response = await _ollamaClient.GenerateCompletionAsync(request);
        return response.Response;
    }
}

Console Application DI

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder()
    .ConfigureServices(services =>
    {
        services.AddOllamaClient(options =>
        {
            options.BaseAddress = new Uri("http://localhost:11434");
        });
        services.AddScoped<MyService>();
    })
    .Build();

var myService = host.Services.GetRequiredService<MyService>();
await myService.DoWorkAsync();

Error Handling

The library provides structured exception handling:

using OllamaApiClient.Core.Exceptions;

try
{
    var response = await client.GenerateCompletionAsync(request);
}
catch (OllamaModelNotFoundException ex)
{
    Console.WriteLine($"Model not found: {ex.ModelName}");
}
catch (OllamaServiceUnavailableException ex)
{
    Console.WriteLine($"Ollama service unavailable: {ex.Message}");
}
catch (OllamaApiException ex)
{
    Console.WriteLine($"API error ({ex.StatusCode}): {ex.Message}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}

Prerequisites

• .NET 9.0 SDK or higher
• Ollama installed and running locally
• Visual Studio 2022, VS Code, or any .NET-compatible IDE

Testing

# Run all tests
dotnet test

# Run unit tests only
dotnet test tests/OllamaApiClient.Tests/

# Run integration tests (requires Ollama running)
dotnet test tests/OllamaApiClient.IntegrationTests/

# Generate coverage report
dotnet test --collect:"XPlat Code Coverage"

Sample Projects

Explore the /samples directory for complete examples:

# Run the console sample
dotnet run --project samples/OllamaApiClient.Samples/

# Dependency injection example
dotnet run --project samples/OllamaApiClient.Samples/ -- --example di

Performance & Production

Recommended Configuration

services.AddOllamaClient(options =>
{
    options.BaseAddress = new Uri("http://localhost:11434");
    options.Timeout = TimeSpan.FromMinutes(10); // Long timeout for large models
});

// Configure HTTP client for production
services.ConfigureHttpClientDefaults(builder =>
{
    builder.ConfigurePrimaryHttpMessageHandler(() => new SocketsHttpHandler
    {
        MaxConnectionsPerServer = 10,
        PooledConnectionLifetime = TimeSpan.FromMinutes(5),
        PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2)
    });
});

Security Considerations

• The library automatically uses LogDebug for sensitive data (prompts, responses) to prevent production exposure
• Implement proper input validation for user-provided prompts
• Consider rate limiting for production applications
• Use HTTPS endpoints when possible

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/yourusername/OllamaApiClient.git
cd OllamaApiClient
dotnet restore
dotnet build
dotnet test

Prerequisites for Development

Make sure you have Ollama installed and running:

# Install Ollama (see official documentation)
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama service
ollama serve

# Pull a test model (in another terminal)
ollama pull llama3.2

License

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

Related Projects

• 🦙 Ollama - The official Ollama project for running large language models locally
• 📚 Ollama API Documentation - Official Ollama API documentation
• 🌐 Ollama Models - Browse available models
• 🐳 Ollama Docker - Official Docker images

Support

• 📖 API Documentation
• 💬 Discussions
• 🐛 Issue Tracker
• 📝 Changelog

⭐ If this library helps you, please consider giving it a star!