### Install Ollama Swift Package

Source: https://context7.com/mattt/ollama-swift/llms.txt

Add the Ollama Swift Client as a dependency in your Package.swift file.

```swift
// Package.swift
dependencies: [
    .package(url: "https://github.com/mattt/ollama-swift.git", from: "1.8.0")
],
targets: [
    .target(name: "MyApp", dependencies: [
        .product(name: "Ollama", package: "ollama-swift")
    ])
]
```

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

### Show Model Information

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Get detailed information about a specific model, including its modelfile, parameters, and template. This helps in understanding the model's configuration.

```swift
do {
    let modelInfo = try await client.showModel("llama3.2")
    print("Modelfile: \(modelInfo.modelfile)")
    print("Parameters: \(modelInfo.parameters)")
    print("Template: \(modelInfo.template)")
} catch {
    print("Error: \(error)")
}
```

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

### Get Ollama Server Version with client.version

Source: https://context7.com/mattt/ollama-swift/llms.txt

Retrieves the version string of the currently running Ollama server. This is useful for checking compatibility or monitoring server status.

```swift
import Ollama

let client = Client.default

let versionInfo = try await client.version()
print("Ollama server version:", versionInfo.version)  // e.g. "0.5.4"
```

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

### Initializing the Client

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Demonstrates how to initialize the Ollama client, either with default settings or custom host and user agent.

```APIDOC
## Initializing the Client

### Description
Initialize the Ollama client using default settings (http://localhost:11434) or provide a custom host URL and user agent.

### Usage
```swift
import Ollama

// Use the default client (http://localhost:11434)
let client = Client.default

// Or create a custom client
let customClient = Client(host: URL(string: "http://your-ollama-host:11434")!, userAgent: "MyApp/1.0")
```
```

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

### Client Initialization

Source: https://context7.com/mattt/ollama-swift/llms.txt

Demonstrates how to initialize the Ollama Client, including using the default singleton for localhost and creating custom instances for remote servers or custom URLSessions.

```APIDOC
## Client Initialization

`Client` is the single entry point for all API calls. Use the shared `Client.default` singleton for the standard `http://localhost:11434` endpoint, or construct a custom instance with an explicit host and optional `User-Agent` string.

```swift
import Ollama

// Shared default — points to http://localhost:11434
let client = Client.default

// Custom host (e.g., a remote Ollama server or a different port)
let remoteClient = Client(
    host: URL(string: "http://192.168.1.42:11434")!,
    userAgent: "MyApp/2.0"
)

// Custom URLSession (e.g., with a background configuration)
let backgroundSession = URLSession(configuration: .background(withIdentifier: "com.example.ollama"))
let backgroundClient = Client(
    session: backgroundSession,
    host: URL(string: "http://localhost:11434")!
)
```
```

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

### Initialize Ollama Client

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Initialize the Ollama client using the default host or a custom configuration. Ensure Ollama is running.

```swift
import Ollama

// Use the default client (http://localhost:11434)
let client = Client.default

// Or create a custom client
let customClient = Client(host: URL(string: "http://your-ollama-host:11434")!, userAgent: "MyApp/1.0")
```

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

### Stream Chat Responses with Ollama

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Stream chat responses to get real-time partial completions. Concatenate content from each chunk to form the complete response.

```swift
do {
    let stream = try await client.chatStream(
        model: "llama3.2",
        messages: [
            .system("You are a helpful assistant."),
            .user("Write a short poem about Swift programming.")
        ]
    )

    var fullContent = ""
    for try await chunk in stream {
        // Process each chunk of the message as it arrives
        if let content = chunk.message.content {
            print(content, terminator: "")
            fullContent += content
        }
    }
    print("\nComplete poem: \(fullContent)")
} catch {
    print("Error: \(error)")
}
```

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

### Define and Use Typed Tools for Chat

Source: https://context7.com/mattt/ollama-swift/llms.txt

Demonstrates how to define typed tools with input and output structs, pass them to the chat function, and handle tool calls in a multi-turn conversation. Ensure your input/output structs conform to Codable.

```swift
import Ollama

// --- Define input/output Codable structs ---
struct WeatherInput: Codable { let city: String }
struct WeatherOutput: Codable { let temperatureC: Double; let conditions: String }

// --- Build the tool ---
let weatherTool = Tool<WeatherInput, WeatherOutput>(
    name: "get_current_weather",
    description: "Returns current temperature (°C) and conditions for a city.",
    parameters: [
        "city": ["type": "string", "description": "City name, e.g. Portland"]
    ],
    required: ["city"] // Specify required parameters
) { input async throws -> WeatherOutput in
    // Replace with a real weather API call
    return WeatherOutput(temperatureC: 14.2, conditions: "overcast")
}

// --- First turn: model decides to call the tool ---
var messages: [Chat.Message] = [
    .system("You are a helpful weather assistant."),
    .user("What's the weather in Portland right now?")
]

let client = Client.default
let firstResponse = try await client.chat(
    model: "llama3.2",
    messages: messages,
    tools: [weatherTool]
)

messages.append(firstResponse.message)  // add assistant's tool-call message

// --- Execute tool calls returned by the model ---
if let toolCalls = firstResponse.message.toolCalls {
    for toolCall in toolCalls {
        let args = toolCall.function.arguments
        guard let cityValue = args["city"],
              let city = String(cityValue) else { continue } // Safely extract and cast city argument

        let output = try await weatherTool(WeatherInput(city: city))

        // Serialize output and append as a tool message
        let encoder = JSONEncoder()
        let json = try String(data: encoder.encode(output), encoding: .utf8)!
        messages.append(.tool(json))
    }
}

// --- Second turn: model uses tool result to answer ---
let finalResponse = try await client.chat(
    model: "llama3.2",
    messages: messages,
    tools: [weatherTool]
)
print(finalResponse.message.content)
// "The current weather in Portland is 14.2 °C with overcast skies."
```

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

### Define a Swift Tool for Ollama

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Define a tool with its name, description, parameters, and implementation. Ensure input and output models conform to Codable.

```swift
struct WeatherInput: Codable {
    let city: String
}

struct WeatherOutput: Codable {
    let temperature: Double
    let conditions: String
}

let weatherTool = Tool<WeatherInput, WeatherOutput>(
    name: "get_current_weather",
    description: """
    Get the current weather for a city,
    with conditions ("sunny", "cloudy", etc.)
    and temperature in °C.
    """,
    parameters: [
        "city": [
            "type": "string",
            "description": "The city to get weather for"
        ]
    ],
    required: ["city"]
```

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

### Retrieve Model Details with client.showModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Fetches detailed information about a model, including its Modelfile, template, parameters, architecture, and supported capabilities. Use this to understand model features and gate usage based on capabilities like `.vision` or `.thinking`.

```swift
import Ollama

let client = Client.default

let info = try await client.showModel("llama3.2")
print("Template   :", info.template)
print("Parameters :", info.parameters ?? "none")
print("Format     :", info.details.format)          // gguf
print("Family     :", info.details.family)          // llama
print("Size       :", info.details.parameterSize)   // 3.2B
print("Quant      :", info.details.quantizationLevel) // Q4_K_M

print("Capabilities:", info.capabilities.map(\.rawValue).sorted().joined(separator: ", "))
// completion, tools

// Guard on specific capabilities before using them
if info.capabilities.contains(.vision) {
    print("Multimodal vision is supported.")
}
if info.capabilities.contains(.thinking) {
    print("Chain-of-thought thinking is supported.")
}
```

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

### Tool Calling with `chat` and `chatStream`

Source: https://context7.com/mattt/ollama-swift/llms.txt

Demonstrates how to define typed tools, pass them to the chat API, execute tool calls returned by the model, and feed results back in a multi-turn conversation.

```APIDOC
## Tool Calling

Define typed tools using `Tool<Input, Output>`, pass them to `chat` or `chatStream`, then dispatch on `message.toolCalls` to execute them and feed results back in a multi-turn loop.

```swift
import Ollama

// --- Define input/output Codable structs ---
struct WeatherInput: Codable { let city: String }
struct WeatherOutput: Codable { let temperatureC: Double; let conditions: String }

// --- Build the tool ---
let weatherTool = Tool<WeatherInput, WeatherOutput>(
    name: "get_current_weather",
    description: "Returns current temperature (°C) and conditions for a city.",
    parameters: [
        "city": ["type": "string", "description": "City name, e.g. Portland"]
    ],
    required: ["city"]
) { input async throws -> WeatherOutput in
    // Replace with a real weather API call
    return WeatherOutput(temperatureC: 14.2, conditions: "overcast")
}

// --- First turn: model decides to call the tool ---
var messages: [Chat.Message] = [
    .system("You are a helpful weather assistant."),
    .user("What's the weather in Portland right now?")
]

let client = Client.default
let firstResponse = try await client.chat(
    model: "llama3.2",
    messages: messages,
    tools: [weatherTool]
)

messages.append(firstResponse.message)  // add assistant's tool-call message

// --- Execute tool calls returned by the model ---
if let toolCalls = firstResponse.message.toolCalls {
    for toolCall in toolCalls {
        let args = toolCall.function.arguments
        guard let cityValue = args["city"],
              let city = String(cityValue) else { continue }

        let output = try await weatherTool(WeatherInput(city: city))

        // Serialize output and append as a tool message
        let encoder = JSONEncoder()
        let json = try String(data: encoder.encode(output), encoding: .utf8)!
        messages.append(.tool(json))
    }
}

// --- Second turn: model uses tool result to answer ---
let finalResponse = try await client.chat(
    model: "llama3.2",
    messages: messages,
    tools: [weatherTool]
)
print(finalResponse.message.content)
// "The current weather in Portland is 14.2 °C with overcast skies."
```
```

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

### Pull a Model

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Download a model from the Ollama library to your local machine. This is necessary before you can use a model for inference or other tasks.

```swift
do {
    let success = try await client.pullModel("llama3.2")
    if success {
        print("Model successfully pulled")
    } else {
        print("Failed to pull model")
    }
} catch {
    print("Error: \(error)")
}
```

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

### Request Structured Output with JSON Schema

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Provide a JSON Schema to the `format` parameter for more control over the output structure. The response will conform to the provided schema.

```swift
let schema: Value = [
    "type": "object",
    "properties": [
        "colors": [
            "type": "array",
            "items": [
                "type": "object",
                "properties": [
                    "name": ["type": "string"],
                    "hex": ["type": "string"]
                ],
                "required": ["name", "hex"]
            ]
        ]
    ],
    "required": ["colors"]
]

let response = try await client.chat(
    model: "llama3.2",
    messages: [.user("List 3 colors with their hex codes.")],
    format: schema
)
```

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

### client.generate

Source: https://context7.com/mattt/ollama-swift/llms.txt

Sends a prompt to a model for single-shot text generation and returns the complete response. Supports optional image data, JSON format constraints, model-specific options, system prompts, and keep-alive durations.

```APIDOC
## `client.generate` — Single-shot text generation

Sends a prompt to a model and returns the complete response once generation finishes. Accepts optional image data for multimodal models, a JSON format constraint, model-specific option overrides, a system prompt, a raw-prompt flag, a `think` flag for reasoning models, and a `keepAlive` duration.

```swift
import Ollama

let client = Client.default

do {
    let response = try await client.generate(
        model: "llama3.2",
        prompt: "Explain what a Swift actor is in one paragraph.",
        options: [
            "temperature": 0.6,
            "top_p": 0.9,
            "num_predict": 200
        ],
        system: "You are a concise Swift programming tutor.",
        keepAlive: .minutes(5)
    )

    print("Model    :", response.model)
    print("Answer   :", response.response)
    print("Tokens   :", response.evalCount ?? 0)
    print("Duration :", response.totalDuration ?? 0, "ns")
    // Model    : llama3.2
    // Answer   : A Swift actor is a reference type that protects its mutable state …
    // Tokens   : 87
    // Duration : 1432900000 ns
} catch let error as Client.Error {
    print("API error:", error.description)
}
```
```

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

### client.version

Source: https://context7.com/mattt/ollama-swift/llms.txt

Retrieves the version string of the currently running Ollama server.

```APIDOC
## `client.version` — Server version

Returns the version string of the running Ollama server.

```swift
import Ollama

let client = Client.default

let versionInfo = try await client.version()
print("Ollama server version:", versionInfo.version)  // e.g. "0.5.4"
```
```

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

### client.showModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Retrieves detailed information about a specific model, including its Modelfile contents, prompt template, parameters, architecture, and supported capabilities.

```APIDOC
## `client.showModel` — Retrieve model details and capabilities

Returns the Modelfile contents, prompt template, parameter string, architecture details, and a `Set<Model.Capability>` that can be used to gate feature usage (`.completion`, `.tools`, `.vision`, `.embedding`, `.thinking`, `.insert`).

```swift
import Ollama

let client = Client.default

let info = try await client.showModel("llama3.2")
print("Template   :", info.template)
print("Parameters :", info.parameters ?? "none")
print("Format     :", info.details.format)          // gguf
print("Family     :", info.details.family)          // llama
print("Size       :", info.details.parameterSize)   // 3.2B
print("Quant      :", info.details.quantizationLevel) // Q4_K_M

print("Capabilities:", info.capabilities.map(\.rawValue).sorted().joined(separator: ", "))
// completion, tools

// Guard on specific capabilities before using them
if info.capabilities.contains(.vision) {
    print("Multimodal vision is supported.")
}
if info.capabilities.contains(.thinking) {
    print("Chain-of-thought thinking is supported.")
}
```
```

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

### List Running Models with `client.listRunningModels`

Source: https://context7.com/mattt/ollama-swift/llms.txt

Returns models that are actively occupying GPU/CPU memory along with their VRAM usage and expiry timestamp.

```APIDOC
## `client.listRunningModels` — List models currently loaded in memory

Returns models that are actively occupying GPU/CPU memory along with their VRAM usage and expiry timestamp.

```swift
import Ollama

let client = Client.default

let running = try await client.listRunningModels()
if running.models.isEmpty {
    print("No models currently loaded.")
} else {
    for m in running.models {
        print("\(m.name)  VRAM: \(m.sizeVRAM / 1_048_576) MB  expires: \(m.expiresAt)")
    }
}
```
```

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

### Show Model

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Retrieves detailed information about a specific model.

```APIDOC
## Show Model

### Description
Gets detailed information about a specific model.

### Method
`client.showModel(String)`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the model to retrieve information for.

### Request Example
```swift
do {
    let modelInfo = try await client.showModel("llama3.2")
    print("Modelfile: \(modelInfo.modelfile)")
    print("Parameters: \(modelInfo.parameters)")
    print("Template: \(modelInfo.template)")
} catch {
    print("Error: \(error)")
}
```

### Response
#### Success Response
- **modelInfo** (ModelInfo) - An object containing detailed information about the model, including `modelfile`, `parameters`, and `template`.
```

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

### Working with Universal JSON Values in Swift

Source: https://context7.com/mattt/ollama-swift/llms.txt

Shows how to use the `Value` enum to represent any JSON value, build structured data with literals, access typed values, perform non-strict coercion, and encode Codable models. Import the `Ollama` framework.

```swift
import Ollama

// Build structured values with dictionary/array literals
let options: [String: Value] = [
    "temperature": 0.7,
    "top_p": 0.9,
    "stop": ["<|im_end|>", "</s>"]
]

// Access typed values
if let temp = options["temperature"]?.doubleValue {
    print("Temperature:", temp)  // 0.7
}

// Non-strict coercion — converts "42" → 42
let toolArg: Value = "42"
let asInt = Int(toolArg, strict: false)  // Optional(42)

// Encode a Codable model into a Value
struct Point: Codable { let x: Int; let y: Int }
let point = try Value(Point(x: 10, y: 20))
print(point)  // ["x": 10, "y": 20]

// Data URL encoding (for multimodal image inputs)
let imageData = Data(/* PNG bytes */)
let imageValue = Value.data(mimeType: "image/png", imageData)
// imageValue encodes as a data: URL when serialised
```

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

### List Locally Available Models with `client.listModels`

Source: https://context7.com/mattt/ollama-swift/llms.txt

Returns every model that has been pulled to the local Ollama instance, including size, digest, and architecture details.

```APIDOC
## `client.listModels` — List locally available models

Returns every model that has been pulled to the local Ollama instance, including size, digest, and architecture details.

```swift
import Ollama

let client = Client.default

let listing = try await client.listModels()
for model in listing.models.sorted(by: { $0.name < $1.name }) {
    let sizeMB = model.size / 1_048_576
    print("\(model.name)  \(sizeMB) MB  \(model.details.parameterSize)  \(model.details.quantizationLevel)")
}
// deepseek-r1:8b   4819 MB  8.0B   Q4_K_M
// llama3.2         2020 MB  3.2B   Q4_K_M
// nomic-embed-text  274 MB  136M   F16
```
```

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

### Structured Outputs (`format` parameter)

Source: https://context7.com/mattt/ollama-swift/llms.txt

Both `chat` and `generate` accept a `format` parameter to enforce structured output. Pass `"json"` for free-form JSON or a JSON Schema object for precise response shaping.

```APIDOC
## Structured Outputs (`format` parameter)

Both `chat` and `generate` accept a `format` parameter of type `Value`. Pass `"json"` for free-form JSON output, or pass a full JSON Schema object to constrain the response shape precisely.

```swift
import Ollama

let client = Client.default

// Strongly-typed JSON Schema
let colorSchema: Value = [
    "type": "object",
    "properties": [
        "colors": [
            "type": "array",
            "items": [
                "type": "object",
                "properties": [
                    "name": ["type": "string"],
                    "hex":  ["type": "string"],
                    "rgb":  [
                        "type": "object",
                        "properties": [
                            "r": ["type": "integer"],
                            "g": ["type": "integer"],
                            "b": ["type": "integer"]
                        ],
                        "required": ["r", "g", "b"]
                    ]
                ],
                "required": ["name", "hex", "rgb"]
            ]
        ]
    ],
    "required": ["colors"]
]

let response = try await client.chat(
    model: "llama3.2",
    messages: [.user("Give me 3 primary colours with names, hex codes and RGB values.")],
    format: colorSchema
)

// response.message.content is guaranteed to match the schema:
// {"colors":[{"name":"red","hex":"#FF0000","rgb":{"r":255,"g":0,"b":0}}, …]}
print(response.message.content)
```
```

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

### client.pullModel / client.pushModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Allows downloading models from the Ollama library with automatic resumption of interrupted downloads, and uploading local models to a namespace.

```APIDOC
## `client.pullModel` / `client.pushModel` — Download and upload models

`pullModel` downloads a model from the Ollama library (resuming interrupted downloads automatically). `pushModel` uploads a local model to a namespace (requires a registered Ollama account and public key).

```swift
import Ollama

let client = Client.default

// Pull a model from the Ollama library
let pulled = try await client.pullModel("llama3.2")
print(pulled ? "llama3.2 ready" : "Pull failed")

// Pull with insecure flag (for private/self-hosted registries in development)
let pulledInsecure = try await client.pullModel("myregistry/mymodel:latest", insecure: true)

// Push a locally built model to a namespace
let pushed = try await client.pushModel("mynamespace/mymodel:v1", insecure: false)
print(pushed ? "Push succeeded" : "Push failed")
```
```

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

### Download and Upload Models with client.pullModel and client.pushModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Use `pullModel` to download models from the Ollama library, with automatic resumption of interrupted downloads. Use `pushModel` to upload local models to a namespace, requiring an Ollama account and public key. The `insecure` flag can be used for development with private registries.

```swift
import Ollama

let client = Client.default

// Pull a model from the Ollama library
let pulled = try await client.pullModel("llama3.2")
print(pulled ? "llama3.2 ready" : "Pull failed")

// Pull with insecure flag (for private/self-hosted registries in development)
let pulledInsecure = try await client.pullModel("myregistry/mymodel:latest", insecure: true)

// Push a locally built model to a namespace
let pushed = try await client.pushModel("mynamespace/mymodel:v1", insecure: false)
print(pushed ? "Push succeeded" : "Push failed")
```

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

### Provide Tools to Ollama for Chat

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Pass a list of defined tools to the client.chat method to enable the model to use them. Handle potential tool calls in the response.

```swift
let messages: [Chat.Message] = [
    .system("You are a helpful assistant that can check the weather."),
    .user("What's the weather like in Portland?")
]

let response = try await client.chat(
    model: "llama3.1",
    messages: messages,
    tools: [weatherTool]
)

// Handle tool calls in the response
if let toolCalls = response.message.toolCalls {
    for toolCall in toolCalls {
        print("Tool called: \(toolCall.function.name)")
        print("Arguments: \(toolCall.function.arguments)")
    }
}
```

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

### List Locally Available Models

Source: https://context7.com/mattt/ollama-swift/llms.txt

Retrieves a list of all models available in the local Ollama instance, including their size, digest, and architecture. The output is sorted alphabetically by model name.

```swift
import Ollama

let client = Client.default

let listing = try await client.listModels()
for model in listing.models.sorted(by: { $0.name < $1.name }) {
    let sizeMB = model.size / 1_048_576
    print("\(model.name)  \(sizeMB) MB  \(model.details.parameterSize)  \(model.details.quantizationLevel)")
}
// deepseek-r1:8b   4819 MB  8.0B   Q4_K_M
// llama3.2         2020 MB  3.2B   Q4_K_M
// nomic-embed-text  274 MB  136M   F16
```

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

### Push a Model

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Upload a local model to the Ollama library. This requires the model to be tagged with a namespace and name.

```swift
do {
    let success = try await client.pushModel("mynamespace/mymodel:latest")
    if success {
        print("Model successfully pushed")
    } else {
        print("Failed to push model")
    }
} catch {
    print("Error: \(error)")
}
```

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

### Single-shot Text Generation with Ollama Client

Source: https://context7.com/mattt/ollama-swift/llms.txt

Send a prompt to a model for text generation and receive the complete response. Supports options, system prompts, and keep-alive durations. Handles potential API errors.

```swift
import Ollama

let client = Client.default

do {
    let response = try await client.generate(
        model: "llama3.2",
        prompt: "Explain what a Swift actor is in one paragraph.",
        options: [
            "temperature": 0.6,
            "top_p": 0.9,
            "num_predict": 200
        ],
        system: "You are a concise Swift programming tutor.",
        keepAlive: .minutes(5)
    )

    print("Model    :", response.model)
    print("Answer   :", response.response)
    print("Tokens   :", response.evalCount ?? 0)
    print("Duration :", response.totalDuration ?? 0, "ns")
    // Model    : llama3.2
    // Answer   : A Swift actor is a reference type that protects its mutable state …
    // Tokens   : 87
    // Duration : 1432900000 ns
} catch let error as Client.Error {
    print("API error:", error.description)
}
```

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

### Tool Definition Parameter Formats (New vs. Deprecated)

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Use the new, simplified 'parameters' format for tool definitions. The older, full JSON schema format is deprecated but still supported.

```swift
// ✅ New format
let weatherTool = Tool<WeatherInput, WeatherOutput>(
    name: "get_current_weather",
    description: "Get the current weather for a city",
    parameters: [
        "city": [
            "type": "string",
            "description": "The city to get weather for"
        ]
    ],
    required: ["city"]
) { /* implementation */ }
```

```swift
// ❌ Deprecated format (still works but not recommended)
let weatherTool = Tool<WeatherInput, WeatherOutput>(
    name: "get_current_weather",
    description: "Get the current weather for a city",
    parameters: [
        "type": "object",
        "properties": [
            "city": [
                "type": "string",
                "description": "The city to get weather for"
            ]
        ],
        "required": ["city"]
    ]
) { /* implementation */ }
```

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

### Using Typed Model Identifiers in Swift

Source: https://context7.com/mattt/ollama-swift/llms.txt

Demonstrates how to use the strongly-typed `Model.ID` for model identification, including string literal conversion, accessing components, and pattern matching. Ensure the `Ollama` framework is imported.

```swift
import Ollama

// String literals are implicitly converted
let id1: Model.ID = "llama3.2"              // namespace: nil,     model: "llama3.2", tag: nil
let id2: Model.ID = "llama3.2:latest"       // namespace: nil,     model: "llama3.2", tag: "latest"
let id3: Model.ID = "myns/mymodel:v2"       // namespace: "myns",  model: "mymodel",  tag: "v2"

print(id3.namespace ?? "")  // myns
print(id3.model)            // mymodel
print(id3.tag ?? "")        // v2

// Pattern matching — tag wildcard
let pattern: Model.ID = "llama3.2"   // no tag specified
switch id2 {
case pattern: print("matched llama3.2 (any tag)")  // ✓ — tag not required to match
default: break
}

// Sorting a list of IDs (case-insensitive)
let ids: [Model.ID] = ["llama3.2", "deepseek-r1:8b", "nomic-embed-text"]
print(ids.sorted())  // [deepseek-r1:8b, llama3.2, nomic-embed-text]
```

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

### Manage Model Lifecycle with client.createModel, client.copyModel, and client.deleteModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Create new models from Modelfiles, create aliases for existing models using `copyModel`, or permanently remove models with `deleteModel`. This covers the full lifecycle of model management within Ollama.

```swift
import Ollama

let client = Client.default

// Create a custom model from an inline Modelfile
let modelfile = """
FROM llama3.2
SYSTEM You are a terse command-line assistant. Reply in 10 words or fewer.
PARAMETER temperature 0.2
"""
let created = try await client.createModel(name: "llama3.2-terse", modelfile: modelfile)
print(created ? "Model created" : "Creation failed")

// Copy / alias a model
let copied = try await client.copyModel(source: "llama3.2", destination: "llama3.2-backup")
print(copied ? "Copied" : "Copy failed")

// Delete a model
let deleted = try await client.deleteModel("llama3.2-backup")
print(deleted ? "Deleted" : "Delete failed")
```

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

### List Models Currently Loaded in Memory

Source: https://context7.com/mattt/ollama-swift/llms.txt

Fetches a list of models that are actively loaded in memory (GPU/CPU), including their VRAM usage and expiry timestamp. Handles the case where no models are loaded.

```swift
import Ollama

let client = Client.default

let running = try await client.listRunningModels()
if running.models.isEmpty {
    print("No models currently loaded.")
} else {
    for m in running.models {
        print("\(m.name)  VRAM: \(m.sizeVRAM / 1_048_576) MB  expires: \(m.expiresAt)")
    }
}
```

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

### Manage Model Memory with Keep-Alive (Default)

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Use the default `keepAlive` behavior, which relies on the server's default setting (typically 5 minutes).

```swift
let response = try await client.generate(
    model: "llama3.2",
    prompt: "Hello!"
    // keepAlive defaults to .default
)
```

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

### Handling Ollama Client Errors in Swift

Source: https://context7.com/mattt/ollama-swift/llms.txt

Illustrates how to handle errors from the Ollama client using a `do-catch` block and a `switch` statement on `Client.Error`. This is crucial for managing request, response, decoding, and unexpected errors. Ensure the `Ollama` framework is imported.

```swift
import Ollama

let client = Client.default

do {
    let response = try await client.generate(
        model: "nonexistent-model:latest",
        prompt: "Hello"
    )
    print(response.response)
} catch let error as Client.Error {
    switch error {
    case .requestError(let detail):
        print("Bad request:", detail)
    case .responseError(let httpResponse, let detail):
        print("HTTP \(httpResponse.statusCode):", detail)
        // HTTP 404: model "nonexistent-model:latest" not found, try pulling it first
    case .decodingError(let httpResponse, let detail):
        print("Decode failure (\(httpResponse.statusCode)):", detail)
    case .unexpectedError(let detail):
        print("Unexpected:", detail)
    }
} catch {
    print("Unknown error:", error)
}
```

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

### List Models

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Retrieves a list of all available models on the Ollama server.

```APIDOC
## List Models

### Description
Lists all available models on the Ollama server.

### Method
`client.listModels()`

### Parameters
None

### Request Example
```swift
do {
    let models = try await client.listModels()
    for model in models {
        print("Model: \(model.name), Modified: \(model.modifiedAt)")
    }
} catch {
    print("Error: \(error)")
}
```

### Response
#### Success Response
- **models** (array of Model) - A list of available models, each with properties like `name` and `modifiedAt`.
```

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

### Generating Text

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Shows how to generate text completions from a specified model with optional parameters and keep-alive settings.

```APIDOC
## Generating Text

### Description
Generate text using a specified model. You can provide custom options like temperature and max_tokens, and configure how long the model should remain loaded.

### Method Signature
```swift
func generate(
    model: String,
    prompt: String,
    options: [String: Any]? = nil,
    keepAlive: Duration? = nil
) async throws -> GenerationResponse
```

### Parameters
- **model** (String) - The name of the model to use for generation.
- **prompt** (String) - The input prompt for text generation.
- **options** ([String: Any]?) - Optional dictionary for generation parameters (e.g., `temperature`, `max_tokens`).
- **keepAlive** (Duration?) - Optional duration to keep the model loaded after the request.

### Request Example
```swift
do {
    let response = try await client.generate(
        model: "llama3.2",
        prompt: "Tell me a joke about Swift programming.",
        options: [
            "temperature": 0.7,
            "max_tokens": 100
        ],
        keepAlive: .minutes(10)  // Keep model loaded for 10 minutes
    )
    print(response.response)
} catch {
    print("Error: \(error)")
}
```
```

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

### client.generateStream

Source: https://context7.com/mattt/ollama-swift/llms.txt

Initiates streaming text generation, returning an `AsyncThrowingStream` that yields chunks of the response as they are generated. The final chunk includes performance counters.

```APIDOC
## `client.generateStream` — Streaming text generation

Returns an `AsyncThrowingStream<GenerateResponse, Error>`. Each yielded chunk carries a partial `response` string and a `done` flag; the final chunk includes performance counters.

```swift
import Ollama

let client = Client.default

do {
    let stream = client.generateStream(
        model: "llama3.2",
        prompt: "Write a haiku about async/await in Swift.",
        options: ["temperature": 0.8],
        keepAlive: .minutes(10)
    )

    var fullText = ""
    for try await chunk in stream {
        print(chunk.response, terminator: "")   // print tokens as they arrive
        fullText += chunk.response
        if chunk.done {
            print()   // newline after last token
            print("Finished — eval tokens:", chunk.evalCount ?? 0)
        }
    }
} catch {
    print("Stream error:", error)
}
```
```

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

### List Available Models

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Retrieve a list of all models currently available on the Ollama server. This is useful for checking which models can be used for generation or embedding tasks.

```swift
do {
    let models = try await client.listModels()
    for model in models {
        print("Model: \(model.name), Modified: \(model.modifiedAt)")
    }
} catch {
    print("Error: \(error)")
}
```

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

### Pull Model

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Downloads a model from the Ollama library.

```APIDOC
## Pull Model

### Description
Downloads a model from the Ollama library.

### Method
`client.pullModel(String)`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the model to download.

### Request Example
```swift
do {
    let success = try await client.pullModel("llama3.2")
    if success {
        print("Model successfully pulled")
    } else {
        print("Failed to pull model")
    }
} catch {
    print("Error: \(error)")
}
```

### Response
#### Success Response
- **success** (boolean) - Indicates whether the model was successfully pulled.
```

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

### Push Model

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Uploads a model to the Ollama library.

```APIDOC
## Push Model

### Description
Uploads a model to the Ollama library.

### Method
`client.pushModel(String)`

### Parameters
#### Path Parameters
- **name** (string) - Required - The name of the model to push.

### Request Example
```swift
do {
    let success = try await client.pushModel("mynamespace/mymodel:latest")
    if success {
        print("Model successfully pushed")
    } else {
        print("Failed to push model")
    }
} catch {
    print("Error: \(error)")
}
```

### Response
#### Success Response
- **success** (boolean) - Indicates whether the model was successfully pushed.
```

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

### Add Ollama Swift to Package.swift

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Add the Ollama Swift client library to your project's Swift Package Manager dependencies.

```swift
.package(url: "https://github.com/mattt/ollama-swift.git", from: "1.8.0")
```

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

### client.createModel / client.copyModel / client.deleteModel

Source: https://context7.com/mattt/ollama-swift/llms.txt

Provides functionalities for managing the model lifecycle, including creating new models from Modelfiles, aliasing existing models, and permanently deleting models.

```APIDOC
## `client.createModel` / `client.copyModel` / `client.deleteModel` — Model lifecycle

Create a new model from a Modelfile string or path, copy (alias) an existing model under a new name, or permanently delete a model and its data.

```swift
import Ollama

let client = Client.default

// Create a custom model from an inline Modelfile
let modelfile = """
FROM llama3.2
SYSTEM You are a terse command-line assistant. Reply in 10 words or fewer.
PARAMETER temperature 0.2
"""
let created = try await client.createModel(name: "llama3.2-terse", modelfile: modelfile)
print(created ? "Model created" : "Creation failed")

// Copy / alias a model
let copied = try await client.copyModel(source: "llama3.2", destination: "llama3.2-backup")
print(copied ? "Copied" : "Copy failed")

// Delete a model
let deleted = try await client.deleteModel("llama3.2-backup")
print(deleted ? "Deleted" : "Delete failed")
```
```

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

### Manage Model Memory with Keep-Alive (Minutes)

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Keep a model loaded in memory for a specified number of minutes using `keepAlive: .minutes(Int)`.

```swift
let response = try await client.generate(
    model: "llama3.2",
    prompt: "Hello!",
    keepAlive: .minutes(10)
)
```

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

### Streaming Text Generation with Ollama Client

Source: https://context7.com/mattt/ollama-swift/llms.txt

Generate text in a streaming fashion, receiving chunks of the response as they are produced. The stream yields partial responses and a final chunk with performance metrics. Handles potential stream errors.

```swift
import Ollama

let client = Client.default

do {
    let stream = client.generateStream(
        model: "llama3.2",
        prompt: "Write a haiku about async/await in Swift.",
        options: ["temperature": 0.8],
        keepAlive: .minutes(10)
    )

    var fullText = ""
    for try await chunk in stream {
        print(chunk.response, terminator: "")   // print tokens as they arrive
        fullText += chunk.response
        if chunk.done {
            print()   // newline after last token
            print("Finished — eval tokens:", chunk.evalCount ?? 0)
        }
    }
} catch {
    print("Stream error:", error)
}
```

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

### Multi-turn Tool Conversation in Swift

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Manage multi-turn conversations where the model may call a tool. Parse tool arguments, execute the tool, and add the result back to the conversation history.

```swift
var messages: [Chat.Message] = [
    .system("You are a helpful assistant that can convert colors."),
    .user("What's the hex code for yellow?")
]

// First turn - model calls the tool
let response1 = try await client.chat(
    model: "llama3.1",
    messages: messages,
    tools: [rgbToHexTool]
)

enum ToolError {
    case invalidParameters
}

// Add tool response to conversation
if let toolCall = response1.message.toolCalls?.first {
    // Parse the tool arguments
    guard let args = toolCall.function.arguments,
          let redValue = args["red"],
          let greenValue = args["green"],
          let blueValue = args["blue"],
          let red = Double(redValue, strict: false),
          let green = Double(greenValue, strict: false),
          let blue = Double(blueValue, strict: false)
    else {
        throw ToolError.invalidParameters
    }

    let input = HexColorInput(
        red: red,
        green: green,
        blue: blue
    )

    // Execute the tool with the input
    let hexColor = try await rgbToHexTool(input)

    // Add the tool result to the conversation
    messages.append(.tool(hexColor))
}

// Continue conversation with tool result
messages.append(.user("What other colors are similar?"))
let response2 = try await client.chat(
    model: "llama3.1",
    messages: messages,
    tools: [rgbToHexTool]
)
```

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

### Thinking Models (Chain-of-Thought) with Ollama Swift

Source: https://context7.com/mattt/ollama-swift/llms.txt

Enable chain-of-thought reasoning for models that support it by setting `think: true`. The reasoning trace is available in `response.message.thinking`. Always check model capabilities before enabling.

```swift
import Ollama

let client = Client.default

// Check capability before enabling thinking
let info = try await client.showModel("deepseek-r1:8b")
guard info.capabilities.contains(.thinking) else {
    print("Model does not support thinking")
    exit(0)
}

let response = try await client.chat(
    model: "deepseek-r1:8b",
    messages: [
        .system("You are a precise mathematician."),
        .user("Is 2^31 - 1 a Mersenne prime? Show full reasoning.")
    ],
    think: true,
    keepAlive: .minutes(15)
)

print("=== Thinking ===")
print(response.message.thinking ?? "(none)")
print("=== Answer ===")
print(response.message.content)
```

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

### Stream Chat Responses with Tools

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Stream chat responses when using tools. Check for tool calls and print content as it streams. Identify the final chunk to know when the response is complete.

```swift
do {
    let stream = try await client.chatStream(
        model: "llama3.2",
        messages: [
            .system("You are a helpful assistant that can check the weather."),
            .user("What's the weather like in Portland?")
        ],
        tools: [weatherTool]
    )

    for try await chunk in stream {
        // Check if the model is making tool calls
        if let toolCalls = chunk.message.toolCalls, !toolCalls.isEmpty {
            print("Model is requesting tool: \(toolCalls[0].function.name)")
        }

        // Print content from the message as it streams
        if let content = chunk.message.content {
            print(content, terminator: "")
        }

        // Check if this is the final chunk
        if chunk.done {
            print("\nResponse complete")
        }
    }
} catch {
    print("Error: \(error)")
}
```

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

### Enable Thinking Mode in Chat

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Use `think: true` in chat conversations to have the model explain its reasoning. Check `response.message.thinking` for the reasoning output.

```swift
let response = try await client.chat(
    model: "deepseek-r1:8b",
    messages: [
        .system("You are a helpful mathematician."),
        .user("Calculate 9.9 + 9.11 and explain your reasoning.")
    ],
    think: true
)

print("Thinking: \(response.message.thinking ?? \"None\")")
print("Response: \(response.message.content)")
```

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

### Request Structured JSON Output

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Use the `format` parameter with "json" to receive a JSON string response. Ensure the model supports JSON output.

```swift
let response = try await client.chat(
    model: "llama3.2",
    messages: [.user("List 3 colors.")],
    format: "json"
)
```

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

### Manage Model Memory with Keep-Alive (Forever)

Source: https://github.com/mattt/ollama-swift/blob/main/README.md

Keep a model loaded indefinitely using `keepAlive: .forever`.

```swift
let response = try await client.chat(
    model: "llama3.2",
    messages: [.user("Hello!")],
    keepAlive: .forever
)
```