0
# Convenience Functions
1

2
Module-level functions that provide direct access to Ollama functionality without requiring explicit client instantiation. These functions use a default Client instance created when importing the ollama module, making them ideal for simple scripts and quick interactions.
3

4
**Type Imports**: The signatures in this documentation use these typing imports:
5
```python
6
from typing import Union, Sequence, Mapping, Callable, Literal, Any, Iterator
7
from pydantic.json_schema import JsonSchemaValue
8
```
9

10
## Capabilities
11

12
### Text Generation Functions
13

14
Direct access to Ollama's text generation capabilities using module-level functions.
15

16
```python { .api }
17
def generate(
18
    model: str = '',
19
    prompt: str = '',
20
    suffix: str = None,
21
    *,
22
    system: str = None,
23
    template: str = None,
24
    context: Sequence[int] = None,
25
    stream: bool = False,
26
    think: bool = None,
27
    raw: bool = None,
28
    format: str = None,
29
    images: Sequence[Union[str, bytes, Image]] = None,
30
    options: Union[Mapping[str, Any], Options] = None,
31
    keep_alive: Union[float, str] = None
32
) -> Union[GenerateResponse, Iterator[GenerateResponse]]:
33
    """
34
    Generate text from a prompt using the default client.
35
    
36
    Parameters:
37
    - model (str): Model name to use for generation. Default: ''
38
    - prompt (str, optional): Text prompt for generation. Default: None
39
    - suffix (str, optional): Text to append after generation
40
    - system (str, optional): System message to set context
41
    - template (str, optional): Custom prompt template
42
    - context (list[int], optional): Token context from previous generation
43
    - stream (bool): Return streaming responses. Default: False
44
    - think (bool): Enable thinking mode for reasoning models
45
    - raw (bool): Use raw mode (no template processing)
46
    - format (str, optional): Response format ('json', etc.)
47
    - images (list[Image], optional): Images for multimodal models
48
    - options (Options, optional): Model configuration options
49
    - keep_alive (str, optional): Keep model loaded duration
50
    
51
    Returns:
52
    GenerateResponse or Iterator[GenerateResponse] if streaming
53
    """
54

55
def chat(
56
    model: str = '',
57
    messages: Sequence[Union[Mapping[str, Any], Message]] = None,
58
    *,
59
    tools: Sequence[Union[Mapping[str, Any], Tool, Callable]] = None,
60
    stream: bool = False,
61
    think: Union[bool, Literal['low', 'medium', 'high']] = None,
62
    format: Union[Literal['', 'json'], JsonSchemaValue] = None,
63
    options: Union[Mapping[str, Any], Options] = None,
64
    keep_alive: Union[float, str] = None
65
) -> Union[ChatResponse, Iterator[ChatResponse]]:
66
    """
67
    Chat with a model using conversation history.
68
    
69
    Parameters:
70
    - model (str): Model name to use for chat. Default: ''
71
    - messages (Sequence[Union[Mapping, Message]], optional): Conversation messages. Default: None
72
    - tools (Sequence[Union[Mapping, Tool, Callable]], optional): Available tools for function calling
73
    - stream (bool): Return streaming responses. Default: False
74
    - think (Union[bool, Literal['low', 'medium', 'high']], optional): Enable thinking mode for reasoning models
75
    - format (str, optional): Response format ('json', etc.)
76
    - options (Options, optional): Model configuration options
77
    - keep_alive (str, optional): Keep model loaded duration
78
    
79
    Returns:
80
    ChatResponse or Iterator[ChatResponse] if streaming
81
    """
82
```
83

84
### Embedding Functions
85

86
Generate vector embeddings from text inputs for semantic analysis and search.
87

88
```python { .api }
89
def embed(
90
    model: str = '',
91
    input: Union[str, Sequence[str]] = '',
92
    truncate: bool = None,
93
    options: Options = None,
94
    keep_alive: str = None
95
) -> EmbedResponse:
96
    """
97
    Generate embeddings for input text(s).
98
    
99
    Parameters:
100
    - model (str): Embedding model name
101
    - input (str | list[str]): Text or list of texts to embed
102
    - truncate (bool, optional): Truncate inputs that exceed model limits
103
    - options (Options, optional): Model configuration options
104
    - keep_alive (str, optional): Keep model loaded duration
105
    
106
    Returns:
107
    EmbedResponse containing embedding vectors
108
    """
109

110
def embeddings(
111
    model: str,
112
    prompt: str,
113
    options: Options = None,
114
    keep_alive: str = None
115
) -> EmbeddingsResponse:
116
    """
117
    Generate embeddings (deprecated - use embed instead).
118
    
119
    Parameters:
120
    - model (str): Embedding model name
121
    - prompt (str): Text to embed
122
    - options (Options, optional): Model configuration options
123
    - keep_alive (str, optional): Keep model loaded duration
124
    
125
    Returns:
126
    EmbeddingsResponse containing single embedding vector
127
    """
128
```
129

130
### Model Management Functions
131

132
Download, upload, create, and manage Ollama models with progress tracking.
133

134
```python { .api }
135
def pull(
136
    model: str,
137
    *,
138
    insecure: bool = False,
139
    stream: bool = False
140
) -> ProgressResponse | Iterator[ProgressResponse]:
141
    """
142
    Download a model from a model library.
143
    
144
    Parameters:
145
    - model (str): Model name to download
146
    - insecure (bool): Allow insecure connections. Default: False
147
    - stream (bool): Return streaming progress. Default: False
148
    
149
    Returns:
150
    ProgressResponse or Iterator[ProgressResponse] if streaming
151
    """
152

153
def push(
154
    model: str,
155
    *,
156
    insecure: bool = False,
157
    stream: bool = False
158
) -> ProgressResponse | Iterator[ProgressResponse]:
159
    """
160
    Upload a model to a model library.
161
    
162
    Parameters:
163
    - model (str): Model name to upload
164
    - insecure (bool): Allow insecure connections. Default: False
165
    - stream (bool): Return streaming progress. Default: False
166
    
167
    Returns:
168
    ProgressResponse or Iterator[ProgressResponse] if streaming
169
    """
170

171
def create(
172
    model: str,
173
    quantize: str = None,
174
    from_: str = None,
175
    files: dict = None,
176
    adapters: dict[str, str] = None,
177
    template: str = None,
178
    license: Union[str, list[str]] = None,
179
    system: str = None,
180
    parameters: dict = None,
181
    messages: list[Message] = None,
182
    *,
183
    stream: bool = False
184
) -> ProgressResponse | Iterator[ProgressResponse]:
185
    """
186
    Create a new model from a Modelfile.
187
    
188
    Parameters:
189
    - model (str): Name for the new model
190
    - quantize (str, optional): Quantization method
191
    - from_ (str, optional): Base model to inherit from
192
    - files (dict, optional): Additional files to include
193
    - adapters (list[str], optional): Model adapters to apply
194
    - template (str, optional): Prompt template
195
    - license (str, optional): Model license
196
    - system (str, optional): System message template
197
    - parameters (dict, optional): Model parameters
198
    - messages (list[Message], optional): Example messages
199
    - stream (bool): Return streaming progress. Default: False
200
    
201
    Returns:
202
    ProgressResponse or Iterator[ProgressResponse] if streaming
203
    """
204

205
def delete(
206
    model: str
207
) -> StatusResponse:
208
    """
209
    Delete a model.
210
    
211
    Parameters:
212
    - model (str): Name of model to delete
213
    
214
    Returns:
215
    StatusResponse with deletion status
216
    """
217

218
def copy(
219
    source: str,
220
    destination: str
221
) -> StatusResponse:
222
    """
223
    Copy a model.
224
    
225
    Parameters:
226
    - source (str): Source model name
227
    - destination (str): Destination model name
228
    
229
    Returns:
230
    StatusResponse with copy status
231
    """
232
```
233

234
### Model Information Functions
235

236
Retrieve information about available and running models.
237

238
```python { .api }
239
def list() -> ListResponse:
240
    """
241
    List available models.
242
    
243
    Returns:
244
    ListResponse containing model information
245
    """
246

247
def show(
248
    model: str
249
) -> ShowResponse:
250
    """
251
    Show information about a specific model.
252
    
253
    Parameters:
254
    - model (str): Model name to show information for
255
    
256
    Returns:
257
    ShowResponse with detailed model information
258
    """
259

260
def ps() -> ProcessResponse:
261
    """
262
    List running models and their resource usage.
263
    
264
    Returns:
265
    ProcessResponse with currently running models
266
    """
267
```
268

269
## Usage Examples
270

271
### Basic Text Generation
272

273
```python
274
import ollama
275

276
# Simple text generation
277
response = ollama.generate(
278
    model='llama3.2',
279
    prompt='Explain quantum computing in simple terms'
280
)
281
print(response['response'])
282

283
# With options
284
response = ollama.generate(
285
    model='llama3.2',
286
    prompt='Write a poem about autumn',
287
    options={'temperature': 0.8, 'top_p': 0.9}
288
)
289
print(response['response'])
290
```
291

292
### Streaming Generation
293

294
```python
295
import ollama
296

297
# Stream text generation
298
print("Generating story...")
299
for chunk in ollama.generate(
300
    model='llama3.2',
301
    prompt='Tell me a story about a brave knight',
302
    stream=True
303
):
304
    if chunk.get('response'):
305
        print(chunk['response'], end='', flush=True)
306
print()  # New line after streaming
307
```
308

309
### Chat Conversations
310

311
```python
312
import ollama
313

314
# Simple chat
315
messages = [
316
    {'role': 'user', 'content': 'Hello! What can you help me with?'}
317
]
318

319
response = ollama.chat(
320
    model='llama3.2',
321
    messages=messages
322
)
323
print(response['message']['content'])
324

325
# Multi-turn conversation
326
messages.append(response['message'])
327
messages.append({
328
    'role': 'user', 
329
    'content': 'Tell me about machine learning'
330
})
331

332
response = ollama.chat(
333
    model='llama3.2',
334
    messages=messages
335
)
336
print(response['message']['content'])
337
```
338

339
### Function Calling
340

341
```python
342
import ollama
343
from ollama import Tool
344

345
def get_current_time() -> str:
346
    """Get the current time."""
347
    from datetime import datetime
348
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
349

350
def calculate_tip(bill_amount: float, tip_percentage: float = 15.0) -> float:
351
    """Calculate tip amount."""
352
    return bill_amount * (tip_percentage / 100)
353

354
# Create tools from functions  
355
from ollama._utils import convert_function_to_tool
356

357
tools = [
358
    convert_function_to_tool(get_current_time),
359
    convert_function_to_tool(calculate_tip)
360
]
361

362
# Chat with function calling
363
response = ollama.chat(
364
    model='llama3.2',
365
    messages=[{
366
        'role': 'user',
367
        'content': 'What time is it and what would be a 20% tip on a $45 bill?'
368
    }],
369
    tools=tools
370
)
371

372
print(response['message']['content'])
373
```
374

375
### Embeddings for Semantic Search
376

377
```python
378
import ollama
379
import numpy as np
380

381
# Generate embeddings for documents
382
documents = [
383
    "The cat sat on the mat",
384
    "A dog played in the park",  
385
    "The feline rested on the rug",
386
    "Birds flew in the sky"
387
]
388

389
# Get embeddings
390
embeddings = []
391
for doc in documents:
392
    response = ollama.embed(
393
        model='nomic-embed-text',
394
        input=doc
395
    )
396
    embeddings.append(response['embeddings'][0])
397

398
# Query embedding
399
query = "A cat lying down"
400
query_response = ollama.embed(
401
    model='nomic-embed-text',
402
    input=query
403
)
404
query_embedding = query_response['embeddings'][0]
405

406
# Calculate similarities
407
similarities = []
408
for emb in embeddings:
409
    similarity = np.dot(query_embedding, emb) / (
410
        np.linalg.norm(query_embedding) * np.linalg.norm(emb)
411
    )
412
    similarities.append(similarity)
413

414
# Find most similar document
415
most_similar_idx = np.argmax(similarities)
416
print(f"Most similar: {documents[most_similar_idx]}")
417
print(f"Similarity: {similarities[most_similar_idx]:.3f}")
418
```
419

420
### Model Management
421

422
```python
423
import ollama
424

425
# List available models
426
models = ollama.list()
427
print("Available models:")
428
for model in models['models']:
429
    print(f"- {model['name']} ({model['size']})")
430

431
# Pull a new model
432
print("Downloading model...")
433
for progress in ollama.pull('phi3', stream=True):
434
    if progress.get('completed') and progress.get('total'):
435
        percent = (progress['completed'] / progress['total']) * 100
436
        print(f"Progress: {percent:.1f}%", end='\r')
437
print("\nDownload complete!")
438

439
# Show model details
440
details = ollama.show('phi3')
441
print(f"Model: {details.get('details', {}).get('family', 'Unknown')}")
442
print(f"Parameters: {details.get('details', {}).get('parameter_size', 'Unknown')}")
443

444
# Check running models
445
running = ollama.ps()
446
if running['models']:
447
    print("Currently running models:")
448
    for model in running['models']:
449
        print(f"- {model['name']}")
450
else:
451
    print("No models currently running")
452
```
453

454
### Image Analysis (Multimodal)
455

456
```python
457
import ollama
458
from ollama import Image
459

460
# Analyze an image
461
response = ollama.generate(
462
    model='llava',  # or another vision-capable model
463
    prompt='Describe what you see in this image',
464
    images=[Image(value='path/to/image.jpg')]
465
)
466
print(response['response'])
467

468
# Compare multiple images
469
response = ollama.chat(
470
    model='llava',
471
    messages=[{
472
        'role': 'user',
473
        'content': 'What are the differences between these two images?',
474
        'images': [
475
            Image(value='image1.jpg'),
476
            Image(value='image2.jpg')
477
        ]
478
    }]
479
)
480
print(response['message']['content'])
481
```