### Define a simple tool with [OllamaTool]

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

Decorate a method with [OllamaTool] to enable automatic source generation for AI model tool calls. This example defines a basic tool for getting weather information.

```csharp
public class SampleTools
{
	/// <summary>
	/// Get the current weather for a city
	/// </summary>
	/// <param name="city">Name of the city</param>
	[OllamaTool]
	public static string GetWeather(string city) => ...;
}
```

--------------------------------

### Start Chat with Ollama in C#

Source: https://github.com/awaescher/ollamasharp/blob/main/index.md

Initialize an OllamaApiClient and start a chat session. This example demonstrates a continuous chat loop where user input is sent to the Ollama model, and the streamed response is displayed in the console.

```csharp
using OllamaSharp;

var uri = new Uri("http://localhost:11434");
var ollama = new OllamaApiClient(uri, "qwen3.5:35b-a3b");

// messages including their roles and tool calls will automatically
// be tracked within the chat object and are accessible via the Messages property
var chat = new Chat(ollama);
   
Console.WriteLine("You're now talking with Ollama. Hit Ctrl+C to exit.");

while (true)
{
    Console.Write("You: ");
    var message = Console.ReadLine();

    Console.Write("Assistant: ");
    await foreach (var stream in chat.SendAsync(message))
        Console.Write(stream);

    Console.WriteLine("");
}
```

--------------------------------

### Create Chat Client with OllamaApiClient

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Installs the Microsoft.Extensions.AI.Abstractions package. Use OllamaApiClient as IChatClient when the provider is 'ollama', otherwise use OpenAIChatClient.

```csharp
// install package Microsoft.Extensions.AI.Abstractions

private static IChatClient CreateChatClient(Arguments arguments)
{
  if (arguments.Provider.Equals("ollama", StringComparison.OrdinalIgnoreCase))
    return new OllamaApiClient(arguments.Uri, arguments.Model);
  else
    return new OpenAIChatClient(new OpenAI.OpenAIClient(arguments.ApiKey), arguments.Model); // ChatGPT or compatible
}
```

--------------------------------

### Define a tool with optional arguments and implementation

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

Extend tool definitions with optional parameters and provide a concrete implementation. This example adds a unit parameter to the GetWeather tool and includes a sample return value.

```csharp
public class SampleTools
{
	/// <summary>
	/// Get the current weather for a city
	/// </summary>
	/// <param name="city">Name of the city</param>
	/// <param name="unit">Temperature unit for the weather</param>
	[OllamaTool]
	public static string GetWeather(string city, Unit unit = Unit.Celsius) => $"It's cold at only 6° {unit} in {city}.";

    public enum Unit
    {
        Celsius,
        Fahrenheit
    }
}
```

--------------------------------

### List Running Models

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Get information about models currently loaded and running in memory, including VRAM usage and expiration times.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// List currently loaded (running) models
IEnumerable<RunningModel> running = await ollama.ListRunningModelsAsync();
foreach (var m in running)
    Console.WriteLine($"{m.Name} — VRAM {m.SizeVram} bytes — expires {m.ExpiresAt}");
```

--------------------------------

### GenerateAsync - Single-turn Completions

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Provides examples of using `GenerateAsync` for single-turn text completions, including streaming responses, providing context manually for multi-turn behavior, and generating with images.

```APIDOC
## `GenerateAsync` — single-turn completions

`GenerateAsync` maps directly to the `/api/generate` Ollama endpoint. Unlike `Chat`, it does **not** maintain history between calls — each call is self-contained.

### Streaming a completion to the console

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");

await foreach (var chunk in ollama.GenerateAsync("Why is the sky blue?"))
    Console.Write(chunk.Response);
```

### Providing context manually

If you need multi-turn behaviour without the `Chat` class you can pass the context tokens returned by a previous response:

```csharp
GenerateDoneResponseStream? lastResponse = null;

await foreach (var chunk in ollama.GenerateAsync("Tell me a joke"))
{
    Console.Write(chunk?.Response);

    if (chunk is GenerateDoneResponseStream done)
        lastResponse = done;
}

// Use the context from the previous turn
var request = new GenerateRequest
{
    Prompt = "Explain why that was funny",
    Context = lastResponse?.Context,
};

await foreach (var chunk in ollama.GenerateAsync(request))
    Console.Write(chunk?.Response);
```

> [!TIP]
> The `Context` property is only available on `GenerateDoneResponseStream` (the final chunk), not on every streamed chunk. Use pattern matching to capture it as shown above.

### Generating with an image

```csharp
var imageBytes = await File.ReadAllBytesAsync("chart.png");

var request = new GenerateRequest
{
    Prompt = "Summarise this chart",
    Images = [Convert.ToBase64String(imageBytes)],
};

await foreach (var chunk in ollama.GenerateAsync(request))
    Console.Write(chunk?.Response);
```

> [!NOTE]
> `GenerateRequest.Images` expects Base64-encoded strings, not raw byte arrays. Use `Convert.ToBase64String()` to convert your image bytes.
```

--------------------------------

### Chat with System Prompt

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Configures the Chat instance with a system prompt to guide the model's behavior or persona. This is useful for setting constraints or defining the assistant's role.

```csharp
var chat = new Chat(ollama, "You are a helpful assistant that only answers questions about cooking.");

await foreach (var token in chat.SendAsync("How do I make pasta carbonara?"))
    Console.Write(token);
```

--------------------------------

### Stream Completion to Console using GenerateAsync in C#

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Use the GenerateAsync method to get single-turn text completions from the Ollama API. This example demonstrates streaming the response chunk by chunk to the console.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");

await foreach (var chunk in ollama.GenerateAsync("Why is the sky blue?"))
    Console.Write(chunk.Response);
```

--------------------------------

### Configure OllamaSharp for Cloud Models

Source: https://github.com/awaescher/ollamasharp/blob/main/README.md

Connect to Ollama cloud models by providing an HttpClient configured with the correct base address and API key in the default request headers. This setup is necessary when using the constructor that accepts an HttpClient.

```csharp
var client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:11434");
client.DefaultRequestHeaders.Add(/* your api key here */);
var ollama = new OllamaApiClient(client);
```

--------------------------------

### Get Ollama Version

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Retrieves the current version of the Ollama server.

```csharp
string version = await ollama.GetVersionAsync();
Console.WriteLine($"Ollama version: {version}");
```

--------------------------------

### Generating Embeddings

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Shows how to use `EmbedAsync` to generate vector embeddings for text, useful for semantic search and other NLP tasks. Includes examples for single and multiple inputs.

```APIDOC
--- 

## Generating embeddings

Use `EmbedAsync` to produce vector embeddings for semantic search, clustering and similar tasks:

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "nomic-embed-text");

var response = await ollama.EmbedAsync("The quick brown fox");
float[] vector = response.Embeddings[0];
```

Multiple inputs can be embedded in a single round-trip:

```csharp
var response = await ollama.EmbedAsync(new EmbedRequest
{
    Model = "nomic-embed-text",
    Input = ["First sentence", "Second sentence"],
});
```
```

--------------------------------

### Define Custom Tool with DTO

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Define tools manually using the Tool DTO for non-C# projects or third-party tools. This example shows how to define a weather tool.

```csharp
public class WeatherTool : Tool
{
    public WeatherTool()
    {
        Type = "function";
        Function = new Function
        {
            Description = "Get the current weather for a city",
            Name = "get_current_weather",
            Parameters = new Parameters
            {
                Properties = new Dictionary<string, Property>
                {
                    ["city"] = new() { Type = "string", Description = "Name of the city" }
                },
                Required = ["city"],
            }
        };
    }
}

var chat = new Chat(ollama);
await foreach (var token in chat.SendAsync("What's the weather in London?", [new WeatherTool()]))
    Console.Write(token);
```

--------------------------------

### Ollama Tool Definition Example

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

This JSON structure defines a tool for Ollama, specifying its name, description, and the parameters it accepts. It's used to inform AI models about available functions.

```json
tools=[
    {
      'type': 'function',
      'function': {
        'name': 'get_current_weather',
        'description': 'Get the current weather for a city',
        'parameters': {
          'type': 'object',
          'properties': {
            'city': {
              'type': 'string',
              'description': 'The name of the city',
            },
          },
          'required': ['city'],
        },
      },
    },
  ]
```

--------------------------------

### Initialize OllamaApiClient

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Set up the OllamaApiClient by providing the server URI. The selected model can be set directly on the client instance.

```csharp
var uri = new Uri("http://localhost:11434");
var ollama = new OllamaApiClient(uri);

// select a model which should be used for further operations
ollama.SelectedModel = "qwen3.5:35b-a3b";
```

--------------------------------

### Get Ollama Version

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Retrieves the current version of the Ollama server.

```APIDOC
## Get Ollama Version

### Description
Retrieves the current version of the Ollama server.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **Version** (string) - The Ollama server version.

### Request Example
(No request body needed for this operation)

### Response Example
```json
{
  "version": "v0.1.29"
}
```
```

--------------------------------

### Initialize OllamaApiClient with Configuration

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

For advanced scenarios like Native AOT, use the Configuration class to set up the OllamaApiClient with URI and model.

```csharp
var ollama = new OllamaApiClient(new OllamaApiClient.Configuration
{
    Uri = new Uri("http://localhost:11434"),
    Model = "qwen3.5:35b-a3b",
});
```

--------------------------------

### Pack NuGet Package

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Create a NuGet package from the project. The output will be placed in the 'nupkgs' directory. Use the 'Release' configuration.

```bash
dotnet pack --output nupkgs --configuration=Release
```

--------------------------------

### Create a Custom Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Builds a new model from an existing one with custom instructions, such as a system prompt. Streams status updates during creation.

```csharp
await foreach (var status in ollama.CreateModelAsync(new CreateModelRequest
{
    Model = "my-assistant",
    From = "qwen3.5:35b-a3b",
    System = "You are a helpful assistant that only speaks like a pirate.",
}))
{
    Console.WriteLine(status?.Status);
}
```

--------------------------------

### Build Project in Release Configuration

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Compiles the project in the Release configuration for optimized performance.

```bash
dotnet build --configuration=Release
```

--------------------------------

### Initialize OllamaApiClient in .NET

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Demonstrates various ways to initialize the OllamaApiClient, including using URI strings, Uri objects, Configuration objects for Native AOT, and pre-configured HttpClients for dependency injection.

```csharp
// Simplest form — URI string + model
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
```

```csharp
// Uri object, assign model separately
var ollama2 = new OllamaApiClient(new Uri("http://localhost:11434"));
ollama2.SelectedModel = "deepseek-r1:14b";
```

```csharp
// Configuration object (supports Native AOT via custom JsonSerializerContext)
var ollama3 = new OllamaApiClient(new OllamaApiClient.Configuration
{
    Uri = new Uri("http://localhost:11434"),
    Model = "qwen3.5:35b-a3b",
});
```

```csharp
// Pre-configured HttpClient (e.g., from IHttpClientFactory or for cloud/API-key auth)
var httpClient = httpClientFactory.CreateClient("ollama");
httpClient.BaseAddress = new Uri("http://localhost:11434");
httpClient.DefaultRequestHeaders.Add("Authorization", "Bearer sk-...");
var ollama4 = new OllamaApiClient(httpClient, "qwen3.5:35b-a3b");
```

```csharp
// Default request headers applied to every call
ollama.DefaultRequestHeaders["Authorization"] = "Bearer sk-...";
ollama.DefaultRequestHeaders["X-Custom-Header"] = "my-value";
```

```csharp
// Dispose when done (only needed when OllamaSharp created the HttpClient internally)
using var ollama5 = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
```

--------------------------------

### Initialize OllamaApiClient with Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

A shorthand constructor to initialize the OllamaApiClient with both the server URI and the default model.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
```

--------------------------------

### Client Initialization

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Demonstrates various ways to initialize the OllamaApiClient, the entry point for all Ollama API operations. It can be initialized with a URI string, a Uri object, a Configuration object for Native AOT, or a pre-configured HttpClient.

```APIDOC
## Client Initialization

`OllamaApiClient` is the entry point for all Ollama API operations. It accepts a URI string, a `Uri` object, a `Configuration` object (for Native AOT), or a pre-configured `HttpClient` (for DI/factory scenarios). The optional second argument sets the default model for all subsequent calls.

```csharp
// Simplest form — URI string + model
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");

// Uri object, assign model separately
var ollama2 = new OllamaApiClient(new Uri("http://localhost:11434"));
ollama2.SelectedModel = "deepseek-r1:14b";

// Configuration object (supports Native AOT via custom JsonSerializerContext)
var ollama3 = new OllamaApiClient(new OllamaApiClient.Configuration
{
    Uri = new Uri("http://localhost:11434"),
    Model = "qwen3.5:35b-a3b",
});

// Pre-configured HttpClient (e.g., from IHttpClientFactory or for cloud/API-key auth)
var httpClient = httpClientFactory.CreateClient("ollama");
httpClient.BaseAddress = new Uri("http://localhost:11434");
httpClient.DefaultRequestHeaders.Add("Authorization", "Bearer sk-...");
var ollama4 = new OllamaApiClient(httpClient, "qwen3.5:35b-a3b");

// Default request headers applied to every call
ollama.DefaultRequestHeaders["Authorization"] = "Bearer sk-...";
ollama.DefaultRequestHeaders["X-Custom-Header"] = "my-value";

// Dispose when done (only needed when OllamaSharp created the HttpClient internally)
using var ollama5 = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
```
```

--------------------------------

### Using Tools (Function Calling)

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Illustrates how to define and use tools with the `[OllamaTool]` attribute for function calling within chat interactions.

```APIDOC
## Using tools (function calling)

Many models support tools. See the [Tool Support](tool-support.md) page for a detailed walkthrough. The short version is:

```csharp
// Define a tool with the [OllamaTool] attribute (requires source generator)
public class MyTools
{
    /// <summary>Gets the current weather for a city.</summary>
    /// <param name="city">Name of the city</param>
    [OllamaTool]
    public static string GetWeather(string city) => $"Sunny and 22°C in {city}.";
}

// Pass tool instances alongside the message
var chat = new Chat(ollama);

await foreach (var token in chat.SendAsync("What's the weather in Berlin?", [new GetWeatherTool()]))
    Console.Write(token);
```

Tool calls and their results are fed back into `chat.Messages` automatically.
```

--------------------------------

### Initialize OllamaApiClient with HttpClient

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Connect to Ollama cloud models or use a pre-configured HttpClient by passing it to the OllamaApiClient constructor. This allows for setting API keys or other HttpClient configurations.

```csharp
var client = new HttpClient();
client.BaseAddress = new Uri("http://localhost:11434");
client.DefaultRequestHeaders.Add(/* your api key here */);

var ollama = new OllamaApiClient(client);
```

--------------------------------

### Create Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Builds a new model from an existing one with custom instructions.

```APIDOC
## Create Model

### Description
Builds a new model from an existing one with a custom system prompt or other Modelfile instructions.

### Method
POST

### Endpoint
/api/create

### Parameters
#### Request Body
- **Name** (string) - Required - The name for the new model.
- **From** (string) - Required - The name of the base model to use.
- **System** (string) - Optional - A custom system prompt for the new model.
- **Template** (string) - Optional - A custom template for the new model.
- **Description** (string) - Optional - A description for the new model.
- **License** (string) - Optional - The license for the new model.
- **Files** (object) - Optional - A dictionary mapping filenames to blob digests for model weights or other files.
- **Parameters** (object) - Optional - Parameters for the new model (e.g., temperature, top_k).
- **Modelfile** (string) - Optional - A complete Modelfile content.
- **Stream** (boolean) - Optional - Whether to stream the response. Defaults to true.

### Request Example
```json
{
  "name": "my-assistant",
  "from": "qwen3.5:35b-a3b",
  "system": "You are a helpful assistant that only speaks like a pirate.",
  "stream": true
}
```

### Response
#### Success Response (200)
- **Status** (string) - The current status of the model creation process.

### Response Example (Streaming)
```json
{
  "status": "creating model"
}
```
```

--------------------------------

### Pull Model with Progress

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Initiate the download of a model from the Ollama model hub and monitor the download progress.

```csharp
await foreach (var status in ollama.PullModelAsync("qwen3.5:35b-a3b"))
    Console.WriteLine($"{status.Percent}% {status.Status}");
```

--------------------------------

### Create Custom Model

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Create a new model, potentially from an existing base model, with custom system prompts. This operation streams status updates.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// Create a custom model from an existing base
await foreach (var status in ollama.CreateModelAsync(new CreateModelRequest
{
    Model = "my-pirate-assistant",
    From = "qwen3.5:35b-a3b",
    System = "You are a helpful assistant that only speaks like a pirate.",
}))
{
    Console.WriteLine(status?.Status);
}
```

--------------------------------

### Check Server Health and Version

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Verify if the Ollama server is running and retrieve its version information.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// Check server health and version
bool isUp = await ollama.IsRunningAsync();
string version = await ollama.GetVersionAsync();
Console.WriteLine($"Ollama {version} — running: {isUp}");
```

--------------------------------

### Restore Dependencies with dotnet restore

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Restores the project's dependencies using the specified solution file.

```bash
dotnet restore OllamaSharp.slnx
```

--------------------------------

### Copy Model

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Create a copy of an existing model on the Ollama server.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// Copy a model
await ollama.CopyModelAsync("qwen3.5:35b-a3b", "qwen3.5:35b-a3b-backup");
```

--------------------------------

### Chat Events and Model Options

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Demonstrates how to subscribe to chat events like `OnThink`, `OnToolCall`, and `OnToolResult`, and how to set model-specific inference options.

```APIDOC
## Chat Events and Model Options

### Events

The `Chat` class exposes events to monitor conversation progress:

| Event | Argument | Fires when |
|---|---|---|
| `OnThink` | `string` | The model emits thinking/reasoning tokens |
| `OnToolCall` | `Message.ToolCall` | The model requests a tool invocation |
| `OnToolResult` | `ToolResult` | A tool invocation has completed and produced a result |

```csharp
var chat = new Chat(ollama);

chat.OnThink += (_, thoughts) => Console.Write($"[thinking] {thoughts}");
chat.OnToolCall += (_, call) => Console.WriteLine($"[calling tool] {call.Function?.Name}");
chat.OnToolResult += (_, result) => Console.WriteLine($"[tool result] {result.Result}");
```

### Model-level options

Fine-tune inference parameters via the `Options` property:

```csharp
var chat = new Chat(ollama)
{
    Options = new RequestOptions
    {
        Temperature = 0.7f,
        TopP = 0.9f,
        NumCtx = 4096,
    }
};
```
```

--------------------------------

### Implement a custom tool invoker

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

Replace the default tool invocation logic by providing your own `IToolInvoker` implementation. This allows for custom behaviors such as logging, caching, or advanced error handling during tool execution.

```csharp
var chat = new Chat(...)
{
    ToolInvoker = new MyCustomToolInvoker()
};
```

--------------------------------

### Show Model Information

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Retrieves detailed metadata for a locally available model, including its Modelfile, parameters, and template.

```csharp
ShowModelResponse info = await ollama.ShowModelAsync("qwen3.5:35b-a3b");

Console.WriteLine(info.ModelInfo);
Console.WriteLine(info.Parameters);
```

--------------------------------

### Add OllamaSharp Package

Source: https://github.com/awaescher/ollamasharp/blob/main/index.md

Use the .NET CLI to add the OllamaSharp package to your project.

```bash
dotnet add package OllamaSharp
```

--------------------------------

### Show Model Metadata

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Retrieve detailed metadata and parameters for a specific model.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// Show model metadata
ShowModelResponse info = await ollama.ShowModelAsync("qwen3.5:35b-a3b");
Console.WriteLine(info.Parameters);
```

--------------------------------

### Run Specific Test by Fully Qualified Name

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Execute a single test case using its fully qualified name. Ensure the test project is built with the 'Release' configuration.

```bash
dotnet test --configuration=Release --filter 'FullyQualifiedName=Tests.OllamaApiClientTests+ChatMethod.Returns_Messages_From_Chat_Endpoint'
```

--------------------------------

### Copy a Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Creates a local copy of an existing model under a new name.

```csharp
await ollama.CopyModelAsync("qwen3.5:35b-a3b", "qwen3.5:35b-a3b-backup");
```

--------------------------------

### Chat - Multi-Modal Input from URL

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Downloads an image from a URL and sends it as raw bytes to a vision-capable model for analysis.

```csharp
// Download image and query in one step
var http = new HttpClient();
var catBytes = await http.GetByteArrayAsync("https://cataas.com/cat");
await foreach (var token in chat.SendAsync("What animal is this?", [catBytes]))
    Console.Write(token);
// Output: The image shows a cat lying on the floor...
```

--------------------------------

### List Running Models

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Queries which models are currently loaded in memory.

```APIDOC
## List Running Models

### Description
Queries which models are currently loaded in memory.

### Method
GET

### Endpoint
/api/runningModels

### Response
#### Success Response (200)
- **RunningModels** (array) - A list of RunningModel objects.
  - **RunningModel** (object)
    - **Name** (string) - The name of the running model.
    - **ExpiresAt** (string) - The expiration time of the model in memory.

### Request Example
(No request body needed for this operation)

### Response Example
```json
{
  "runningModels": [
    {
      "name": "llama2:latest",
      "expiresAt": "2023-08-04T10:05:00Z"
    }
  ]
}
```
```

--------------------------------

### Blob Management

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Upload raw model weight files to the Ollama server before creating a model from them.

```APIDOC
## Blob Management

### Description
Upload raw model weight files to the Ollama server before creating a model from them.

### Methods

#### Is Blob Exists
##### Description
Checks if the Ollama server already has a specific blob (model weight file).
##### Method
`IsBlobExistsAsync(string digest)`
##### Parameters
- **digest** (string) - The SHA256 digest of the blob to check.
##### Response
- **exists** (bool) - True if the blob exists on the server, false otherwise.

#### Push Blob
##### Description
Uploads a raw model weight file (blob) to the Ollama server.
##### Method
`PushBlobAsync(string digest, byte[] bytes)`
##### Parameters
- **digest** (string) - The SHA256 digest of the blob.
- **bytes** (byte[]) - The raw bytes of the model weight file.

#### Create Model (with Blob)
##### Description
Creates a new model, referencing an already uploaded blob for its weights.
##### Method
`CreateModelAsync(CreateModelRequest request)`
##### Parameters
- **request** (CreateModelRequest) - The request object containing model creation details.
  - **model** (string) - The name for the new model.
  - **files** (Dictionary<string, string>) - A dictionary mapping filenames to their blob digests.
##### Response
- **status** (CreateStatus) - Streaming status updates of the model creation process.

### Request Example (Upload and Create Model)
```csharp
var ollama = new OllamaApiClient("http://localhost:11434");
var digest = "sha256:29fdb92e57cf0a4e2752d739b5d9ab9f51adae34e851f37c20fe15ef68bebc51";

if (!await ollama.IsBlobExistsAsync(digest))
{
    var bytes = await File.ReadAllBytesAsync("my-model-weights.gguf");
    await ollama.PushBlobAsync(digest, bytes);
}

await foreach (var status in ollama.CreateModelAsync(new CreateModelRequest
{
    Model = "my-local-model",
    Files = new Dictionary<string, string> { ["my-model-weights.gguf"] = digest },
}))
{
    Console.WriteLine(status?.Status);
}
```
```

--------------------------------

### Generate Direct Completion

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Generate a text completion directly from a prompt and stream the response to the console.

```csharp
await foreach (var stream in ollama.GenerateAsync("How are you today?"))
    Console.Write(stream.Response);
```

--------------------------------

### Show Model Information

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Retrieves detailed metadata for a locally available model.

```APIDOC
## Show Model Information

### Description
Retrieves detailed metadata for a locally available model, including its Modelfile, parameters, and template.

### Method
POST

### Endpoint
/api/show

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the model to show information for (e.g., "qwen3.5:35b-a3b").

### Request Example
```json
{
  "name": "qwen3.5:35b-a3b"
}
```

### Response
#### Success Response (200)
- **ModelInfo** (string) - Detailed information about the model, including its Modelfile.
- **Parameters** (string) - The model's parameters.
- **Template** (string) - The model's template.
- **Digest** (string) - The model's digest.

### Response Example
```json
{
  "modelInfo": "FROM qwen3.5:35b-a3b\nSYSTEM You are a helpful assistant.",
  "parameters": "temperature: 0.8\n top_k: 40\n ...",
  "template": "{{ .System }}",
  "digest": "sha256:abcdef1234567890..."
}
```
```

--------------------------------

### Manual Tool Definition in C# with OllamaSharp

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

This C# class demonstrates how to manually define a tool for OllamaSharp, mirroring the structure required by the Ollama API. This approach is still supported but is more verbose and requires manual handling of tool calls.

```csharp
public class WeatherTool : Tool
{
    public WeatherTool()
    {
        Function = new Function
        {
            Description = "Get the current weather for a city",
            Name = "get_current_weather",
            Parameters = new Parameters
            {
                Properties = new Dictionary<string, Property>
                {
                    ["city"] = new() { Type = "string", Description = "Name of the city" }
                },
                Required = ["city"],
            }
        };
        Type = "function";
    }
}
```

--------------------------------

### Define and Use Tools for Function Calling in C#

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Implement function calling by defining tools with the [OllamaTool] attribute. Pass instances of these tools to the SendAsync method to enable the model to request tool invocations.

```csharp
// Define a tool with the [OllamaTool] attribute (requires source generator)
public class MyTools
{
    /// <summary>Gets the current weather for a city.</summary>
    /// <param name="city">Name of the city</param>
    [OllamaTool]
    public static string GetWeather(string city) => $"Sunny and 22°C in {city}.";
}

// Pass tool instances alongside the message
var chat = new Chat(ollama);

await foreach (var token in chat.SendAsync("What's the weather in Berlin?", [new GetWeatherTool()]))
    Console.Write(token);
```

--------------------------------

### Run a Specific Test Project

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Execute tests from a particular test project, excluding tests that require a live Ollama instance. Use the 'Release' configuration.

```bash
dotnet test test/Tests.csproj --configuration=Release --filter 'FullyQualifiedName!~FunctionalTests'
```

--------------------------------

### Configure Model Inference Options in C#

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Fine-tune model inference parameters such as temperature, top-p, and context window size using the Options property of the Chat class. This allows for customized model behavior.

```csharp
var chat = new Chat(ollama)
{
    Options = new RequestOptions
    {
        Temperature = 0.7f,
        TopP = 0.9f,
        NumCtx = 4096,
    }
};
```

--------------------------------

### List Running Models

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/advanced-configuration.md

Retrieve a list of models currently loaded in Ollama, including their VRAM usage and expiration times, by calling the ListRunningModelsAsync method.

```csharp
var running = await ollama.ListRunningModelsAsync();

foreach (var model in running)
    Console.WriteLine($"{model.Name} — VRAM: {model.SizeVram} bytes — expires {model.ExpiresAt}");
```

--------------------------------

### Push Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Pushes a locally created model to a registry.

```APIDOC
## Push Model

### Description
Pushes a locally created model to a registry (requires a valid Ollama account).

### Method
POST

### Endpoint
/api/push

### Parameters
#### Request Body
- **Name** (string) - Required - The name of the model to push (e.g., "myuser/my-custom-model:latest").
- **Insecure** (boolean) - Optional - Allow insecure connections to the registry.
- **Username** (string) - Optional - Username for registry authentication.
- **Password** (string) - Optional - Password for registry authentication.
- **Stream** (boolean) - Optional - Whether to stream the response. Defaults to true.

### Request Example
```json
{
  "name": "myuser/my-custom-model:latest",
  "stream": true
}
```

### Response
#### Success Response (200)
- **Status** (string) - The current status of the push operation.

### Response Example (Streaming)
```json
{
  "status": "pushing manifest"
}
```
```

--------------------------------

### GenerateAsync - With Image Input

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Generates a completion based on text and an image. The image must be Base64-encoded.

```csharp
// Generate with an image (Base64-encoded)
var imageBytes = await File.ReadAllBytesAsync("chart.png");
var imgRequest = new GenerateRequest
{
    Prompt = "Summarise this chart",
    Images = [Convert.ToBase64String(imageBytes)],
};
await foreach (var chunk in ollama.GenerateAsync(imgRequest))
    Console.Write(chunk?.Response);
```

--------------------------------

### Push Custom Model

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Upload a custom model to a registry. This operation streams status updates.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434");

// Push a custom model to a registry
await foreach (var status in ollama.PushModelAsync("myuser/my-custom-model:latest"))
    Console.WriteLine(status?.Status);
```

--------------------------------

### Push a Model

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Pushes a locally created model to a registry. Requires a valid Ollama account and streams status updates.

```csharp
await foreach (var status in ollama.PushModelAsync("myuser/my-custom-model:latest"))
    Console.WriteLine(status?.Status);
```

--------------------------------

### Sending Images to Multi-modal Models (Base64)

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Provides an alternative method for sending images to multi-modal models using Base64-encoded strings. This can be more convenient if images are already encoded.

```csharp
var base64 = Convert.ToBase64String(imageBytes);

await foreach (var token in chat.SendAsync("Describe the image", [base64]))
    Console.Write(token);
```

--------------------------------

### Configure OllamaApiClient with Custom JsonSerializerContext

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/native-aot-support.md

Instantiate OllamaApiClient, providing your custom JsonSerializerContext in the configuration. This ensures that OllamaSharp uses your AOT-compatible serializer.

```csharp
// pass your configuration context to the OllamaApiClient
var config = new OllamaApiClient.Configuration
{
    Uri = new Uri("http://localhost:11434"),
    Model = "qwen3.5:35b-a3b",
    JsonSerializerContext = MyCustomJsonContext.Default
};
var client = new OllamaApiClient(config);
```

--------------------------------

### Monitor tool calls with events

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/tool-support.md

Observe tool invocation and result events using `OnToolCall` and `OnToolResult`. These events allow you to log or react to tool activity as it happens during the chat interaction.

```csharp
chat.OnToolCall += (_, call) => Console.WriteLine($"Model wants to call: {call.Function?.Name}");
chat.OnToolResult += (_, result) => Console.WriteLine($"Tool returned: {result.Result}");
```

--------------------------------

### List Local Models

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/getting-started.md

Retrieve a list of all models currently available on your local Ollama server.

```csharp
var models = await ollama.ListLocalModelsAsync();
```

--------------------------------

### Configuring Thinking Budget Levels

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Sets the reasoning effort for 'thinking' mode using predefined `ThinkValue` budget levels (High, Medium, Low). Note that not all models support these budget levels.

```csharp
// Use predefined budget levels
var chat = new Chat(ollama) { Think = ThinkValue.High };   // maximum reasoning effort
var chat = new Chat(ollama) { Think = ThinkValue.Medium }; // balanced reasoning
var chat = new Chat(ollama) { Think = ThinkValue.Low };    // minimal reasoning
```

--------------------------------

### Tool/Function Calling with OllamaSharp Source Generator

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Define tools using static methods decorated with [OllamaTool]. The source generator creates companion classes for Chat to invoke automatically. Monitor tool calls and results using OnToolCall and OnToolResult events.

```csharp
// Tool definitions — in any class, any namespace
public class WeatherTools
{
    /// <summary>Gets the current weather for a city.</summary>
    /// <param name="city">Name of the city</param>
    /// <param name="unit">Temperature unit for the weather</param>
    [OllamaTool]
    public static string GetWeather(string city, Unit unit = Unit.Celsius)
        => $"It's 22° {unit} in {city}.";

    /// <summary>Gets the population of a city.</summary>
    /// <param name="city">The city name</param>
    [OllamaTool]
    public static int GetPopulation(string city) => 1_000_000; // stub

    public enum Unit { Celsius, Fahrenheit }
}

// Usage — pass generated tool instances with the message
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
var chat = new Chat(ollama);

// Monitor tool activity
chat.OnToolCall   += (_, call)   => Console.WriteLine($"[calling] {call.Function?.Name}");
chat.OnToolResult += (_, result) => Console.WriteLine($"[result]  {result.Result}");

// Tools are invoked automatically, results fed back into the conversation
await foreach (var token in chat.SendAsync(
    "What's the weather in Berlin and how many people live there?",
    [new GetWeatherTool(), new GetPopulationTool()]))
{
    Console.Write(token);
}

// Disable recursive chaining if needed
chat.AllowRecursiveToolCalls = false;

// Replace the default invoker for custom logging / caching / error handling
chat.ToolInvoker = new MyCustomToolInvoker();
```

--------------------------------

### Run All Tests in a Specific Test Class

Source: https://github.com/awaescher/ollamasharp/blob/main/AGENTS.md

Execute all tests within a specified test class. This is useful for testing a particular feature set. Use the 'Release' configuration.

```bash
dotnet test --configuration=Release --filter 'FullyQualifiedName~Tests.ChatTests'
```

--------------------------------

### List Running Models

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/model-management.md

Queries which models are currently loaded into memory by the Ollama server. Provides the model name and its expiration time.

```csharp
IEnumerable<RunningModel> running = await ollama.ListRunningModelsAsync();

foreach (var model in running)
    Console.WriteLine($"{model.Name} — expires {model.ExpiresAt}");
```

--------------------------------

### Basic Chat Loop with OllamaSharp

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Initiates a chat session with a specified model and enters a loop to continuously send user messages and receive model responses. The conversation history is automatically managed by the Chat class.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
var chat = new Chat(ollama);

while (true)
{
    Console.Write("You: ");
    var message = Console.ReadLine()!;

    Console.Write("Assistant: ");
    await foreach (var token in chat.SendAsync(message))
        Console.Write(token);

    Console.WriteLine();
}
```

--------------------------------

### GenerateAsync - Simple Streaming Completion

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Performs a simple streaming text completion. No history is maintained between calls.

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");

// Simple streaming completion
await foreach (var chunk in ollama.GenerateAsync("Why is the sky blue?"))
    Console.Write(chunk?.Response);
```

--------------------------------

### Enable Reasoning with OllamaSharp

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Activate 'think' tokens for reasoning models to surface internal thought processes. Control the level of reasoning effort using ThinkValue (High, Medium, Low, Off).

```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "deepseek-r1:14b");
var chat = new Chat(ollama) { Think = true };

chat.OnThink += (_, thoughts) => Console.Write($"[thinking] {thoughts}");

await foreach (var token in chat.SendAsync("What is the square root of 144?"))
    Console.Write(token);

// Budget levels — control how much reasoning the model performs
var chatHigh   = new Chat(ollama) { Think = ThinkValue.High };   // maximum effort
var chatMedium = new Chat(ollama) { Think = ThinkValue.Medium }; // balanced
var chatLow    = new Chat(ollama) { Think = ThinkValue.Low };    // minimal
var chatOff    = new Chat(ollama) { Think = new ThinkValue(false) }; // disable
```

--------------------------------

### GenerateAsync — Single-Turn Completions

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Maps to the Ollama /api/generate endpoint for stateless, one-shot completions. Supports streaming, context reuse, image inputs, and custom headers.

```APIDOC
## GenerateAsync — Single-Turn Completions

`GenerateAsync` maps to the Ollama `/api/generate` endpoint. Each call is stateless — no history is maintained between calls. Useful for one-shot completions, batch processing, or when you need direct access to context tokens.

### Method
POST

### Endpoint
/api/generate

### Parameters
#### Request Body
- **Prompt** (string) - Required - The text prompt to send to the model.
- **Model** (string) - Optional - The model to use for generation.
- **Context** (string) - Optional - The context from a previous response to maintain conversation state.
- **Images** (string[]) - Optional - A list of Base64-encoded image strings.
- **Options** (object) - Optional - Generation parameters like temperature, top_p, etc.
- **Stream** (boolean) - Optional - Whether to stream the response.
- **CustomHeaders** (Dictionary<string, string>) - Optional - Custom headers to include in the request.

### Request Example (Simple)
```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
await foreach (var chunk in ollama.GenerateAsync("Why is the sky blue?"))
    Console.Write(chunk?.Response);
```

### Request Example (With Context)
```csharp
var ollama = new OllamaApiClient("http://localhost:11434", "qwen3.5:35b-a3b");
GenerateDoneResponseStream? lastResponse = null;
await foreach (var chunk in ollama.GenerateAsync("Tell me a joke"))
{
    Console.Write(chunk?.Response);
    if (chunk is GenerateDoneResponseStream done)
        lastResponse = done;
}

var followUp = new GenerateRequest
{
    Prompt = "Explain why that was funny",
    Context = lastResponse?.Context,
};
await foreach (var chunk in ollama.GenerateAsync(followUp))
    Console.Write(chunk?.Response);
```

### Request Example (With Image)
```csharp
var imageBytes = await File.ReadAllBytesAsync("chart.png");
var imgRequest = new GenerateRequest
{
    Prompt = "Summarise this chart",
    Images = [Convert.ToBase64String(imageBytes)],
};
await foreach (var chunk in ollama.GenerateAsync(imgRequest))
    Console.Write(chunk?.Response);
```

### Request Example (With Custom Header)
```csharp
var req = new GenerateRequest { Prompt = "Hello!" };
req.CustomHeaders["X-Request-Id"] = Guid.NewGuid().ToString();
await foreach (var chunk in ollama.GenerateAsync(req))
    Console.Write(chunk?.Response);
```

### Response
- **chunk** (object) - Streaming response chunks containing `Response` and potentially `Context` and `Done` information.
```

--------------------------------

### Chat - Multi-Modal Input with Base64 String

Source: https://context7.com/awaescher/ollamasharp/llms.txt

Sends an image as a Base64-encoded string to a vision-capable model using the Chat.SendAsync method.

```csharp
// Base64 string directly
var base64 = Convert.ToBase64String(imageBytes);
await foreach (var token in chat.SendAsync("Describe the image", [base64]))
    Console.Write(token);
```

--------------------------------

### Handle Chat Events in C#

Source: https://github.com/awaescher/ollamasharp/blob/main/docs/chat-and-generate.md

Subscribe to events like OnThink, OnToolCall, and OnToolResult to monitor the chat process. These events provide insights into the model's reasoning, tool requests, and tool execution outcomes.

```csharp
var chat = new Chat(ollama);

chat.OnThink += (_, thoughts) => Console.Write($"[thinking] {thoughts}");
chat.OnToolCall += (_, call) => Console.WriteLine($"[calling tool] {call.Function?.Name}");
chat.OnToolResult += (_, result) => Console.WriteLine($"[tool result] {result.Result}");
```

--------------------------------

### Build Interactive Chats with OllamaSharp

Source: https://github.com/awaescher/ollamasharp/blob/main/README.md

Use the Chat class for conversational applications. It automatically tracks message history, including tool calls and their results, providing the model with full context across turns. This snippet demonstrates a basic interactive chat loop.

```csharp
var chat = new Chat(ollama);

while (true)
{
    var message = Console.ReadLine();
    await foreach (var answerToken in chat.SendAsync(message))
        Console.Write(answerToken);
}
```