0
# Ollama
1

2
The official Python client library for Ollama, providing both synchronous and asynchronous interfaces for text generation, chat interactions, embeddings, and model management. Built on httpx for HTTP operations and pydantic for data validation, it offers comprehensive functionality for integrating with local or remote Ollama instances.
3

4
## Package Information
5

6
- **Package Name**: ollama
7
- **Language**: Python
8
- **Installation**: `pip install ollama`
9
- **Dependencies**: httpx>=0.27, pydantic>=2.9
10
- **License**: MIT
11

12
## Core Imports
13

14
```python
15
import ollama
16
from ollama import Client, AsyncClient
17
```
18

19
For data types and models:
20

21
```python
22
from ollama import (
23
    Message, Options, Tool, Image,
24
    GenerateResponse, ChatResponse, EmbedResponse,
25
    RequestError, ResponseError
26
)
27
```
28

29
For utility functions:
30

31
```python
32
from ollama._utils import convert_function_to_tool
33
```
34

35
For type annotations (when needed):
36

37
```python
38
from typing import Union, Sequence, Mapping, Callable, Literal, Any
39
```
40

41
## Basic Usage
42

43
### Using Module-Level Functions
44

45
```python
46
import ollama
47

48
# Generate text
49
response = ollama.generate(
50
    model='llama3.2',
51
    prompt='Tell me about artificial intelligence'
52
)
53
print(response['response'])
54

55
# Chat with the model
56
messages = [
57
    {'role': 'user', 'content': 'What is the capital of France?'}
58
]
59
response = ollama.chat(
60
    model='llama3.2',
61
    messages=messages
62
)
63
print(response['message']['content'])
64

65
# Create embeddings
66
response = ollama.embed(
67
    model='nomic-embed-text',
68
    input=['Hello world', 'Goodbye world']
69
)
70
print(response['embeddings'])
71

72
# List available models
73
models = ollama.list()
74
for model in models['models']:
75
    print(model['name'])
76
```
77

78
### Using Client Classes
79

80
```python
81
from ollama import Client
82

83
# Create a client instance
84
client = Client(host='http://localhost:11434')
85

86
# Generate text with streaming
87
for chunk in client.generate(
88
    model='llama3.2',
89
    prompt='Explain quantum computing',
90
    stream=True
91
):
92
    print(chunk['response'], end='', flush=True)
93

94
# Chat with function calling
95
from ollama._utils import convert_function_to_tool
96

97
def get_weather(city: str) -> str:
98
    """Get the weather for a city."""
99
    return f"The weather in {city} is sunny, 22°C"
100

101
response = client.chat(
102
    model='llama3.2',
103
    messages=[
104
        {'role': 'user', 'content': 'What is the weather in Paris?'}
105
    ],
106
    tools=[convert_function_to_tool(get_weather)]
107
)
108
```
109

110
### Async Usage
111

112
```python
113
import asyncio
114
from ollama import AsyncClient
115

116
async def main():
117
    client = AsyncClient()
118
    
119
    # Async generate
120
    response = await client.generate(
121
        model='llama3.2',
122
        prompt='Write a haiku about programming'
123
    )
124
    print(response['response'])
125
    
126
    # Async streaming
127
    async for chunk in await client.chat(
128
        model='llama3.2',
129
        messages=[{'role': 'user', 'content': 'Tell me a story'}],
130
        stream=True
131
    ):
132
        print(chunk['message']['content'], end='', flush=True)
133

134
asyncio.run(main())
135
```
136

137
## Architecture
138

139
The ollama client library is built around these key components:
140

141
- **Client Classes**: `Client` (sync) and `AsyncClient` (async) provide the core API interface
142
- **Module Functions**: Convenience functions bound to a default client instance for simple usage
143
- **Data Models**: Pydantic models for all requests, responses, and configuration
144
- **Type System**: Complete type definitions for all API components
145

146
The dual architecture allows both simple module-level usage (`ollama.generate()`) and advanced client-based usage (`Client().generate()`) depending on your needs.
147

148
## Capabilities
149

150
### Client Operations
151

152
Complete synchronous and asynchronous client classes providing the full Ollama API with configurable hosts, custom headers, timeouts, and comprehensive error handling.
153

154
```python { .api }
155
class Client:
156
    def __init__(self, host: str = None, **kwargs): ...
157
    def generate(self, model: str = '', prompt: str = '', **kwargs): ...
158
    def chat(self, model: str = '', messages: Sequence[Union[Mapping, Message]] = None, **kwargs): ...
159
    def embed(self, model: str = '', input: Union[str, Sequence[str]] = '', **kwargs): ...
160
    def pull(self, model: str, **kwargs): ...
161
    def list(self): ...
162

163
class AsyncClient:
164
    def __init__(self, host: str = None, **kwargs): ...
165
    async def generate(self, model: str = '', prompt: str = '', **kwargs): ...
166
    async def chat(self, model: str = '', messages: Sequence[Union[Mapping, Message]] = None, **kwargs): ...
167
    async def embed(self, model: str = '', input: Union[str, Sequence[str]] = '', **kwargs): ...
168
    async def pull(self, model: str, **kwargs): ...
169
    async def list(self): ...
170
```
171

172
[Client Operations](./clients.md)
173

174
### Convenience Functions
175

176
Module-level functions that provide direct access to Ollama functionality without requiring explicit client instantiation, using a default client instance.
177

178
```python { .api }
179
def generate(model: str = '', prompt: str = '', **kwargs): ...
180
def chat(model: str = '', messages: Sequence[Union[Mapping, Message]] = None, **kwargs): ...
181
def embed(model: str = '', input: Union[str, Sequence[str]] = '', **kwargs): ...
182
def pull(model: str, **kwargs): ...
183
def push(model: str, **kwargs): ...
184
def create(model: str, **kwargs): ...
185
def delete(model: str): ...
186
def list(): ...
187
def copy(source: str, destination: str): ...
188
def show(model: str): ...
189
def ps(): ...
190
```
191

192
[Convenience Functions](./convenience-functions.md)
193

194
### Data Types and Models
195

196
Comprehensive Pydantic data models for all API interactions including requests, responses, configuration options, and type definitions for messages, tools, and images.
197

198
```python { .api }
199
class Message:
200
    role: str
201
    content: str
202
    images: list[Image] = None
203
    tool_calls: list[ToolCall] = None
204

205
class Options:
206
    temperature: float = None
207
    top_p: float = None
208
    num_predict: int = None
209
    # ... many more configuration options
210

211
class GenerateResponse:
212
    response: str
213
    context: list[int] = None
214
    done: bool
215
    # ... metadata fields
216

217
class ChatResponse:
218
    message: Message
219
    done: bool
220
    # ... metadata fields
221
```
222

223
[Data Types and Models](./data-types.md)