types.go 33.7 KB
Newer Older
Jeffrey Morgan's avatar
Jeffrey Morgan committed
1
2
package api

3
import (
Michael Yang's avatar
Michael Yang committed
4
	"encoding/json"
5
	"fmt"
6
	"log/slog"
Michael Yang's avatar
Michael Yang committed
7
	"math"
8
	"os"
9
	"reflect"
10
	"strconv"
11
	"strings"
12
	"time"
13

14
15
	"github.com/google/uuid"

16
	"github.com/ollama/ollama/envconfig"
17
	"github.com/ollama/ollama/types/model"
18
)
Michael Yang's avatar
Michael Yang committed
19

20
// StatusError is an error with an HTTP status code and message.
Patrick Devine's avatar
Patrick Devine committed
21
type StatusError struct {
22
23
24
	StatusCode   int
	Status       string
	ErrorMessage string `json:"error"`
Patrick Devine's avatar
Patrick Devine committed
25
26
27
}

func (e StatusError) Error() string {
28
29
30
31
32
33
34
35
36
37
	switch {
	case e.Status != "" && e.ErrorMessage != "":
		return fmt.Sprintf("%s: %s", e.Status, e.ErrorMessage)
	case e.Status != "":
		return e.Status
	case e.ErrorMessage != "":
		return e.ErrorMessage
	default:
		// this should not happen
		return "something went wrong, please see the ollama server logs for details"
Patrick Devine's avatar
Patrick Devine committed
38
39
40
	}
}

41
42
43
type AuthorizationError struct {
	StatusCode int
	Status     string
44
	SigninURL  string `json:"signin_url"`
45
46
47
48
49
50
51
52
53
}

func (e AuthorizationError) Error() string {
	if e.Status != "" {
		return e.Status
	}
	return "something went wrong, please see the ollama server logs for details"
}

54
// ImageData represents the raw binary data of an image file.
Patrick Devine's avatar
Patrick Devine committed
55
56
type ImageData []byte

57
58
59
// GenerateRequest describes a request sent by [Client.Generate]. While you
// have to specify the Model and Prompt fields, all the other fields have
// reasonable defaults for basic uses.
60
type GenerateRequest struct {
61
62
63
	// Model is the model name; it should be a name familiar to Ollama from
	// the library at https://ollama.com/library
	Model string `json:"model"`
64

65
66
67
	// Prompt is the textual prompt to send to the model.
	Prompt string `json:"prompt"`

68
69
70
	// Suffix is the text that comes after the inserted text.
	Suffix string `json:"suffix"`

71
72
73
74
75
76
77
	// System overrides the model's default system message/prompt.
	System string `json:"system"`

	// Template overrides the model's default prompt template.
	Template string `json:"template"`

	// Context is the context parameter returned from a previous call to
78
	// [Client.Generate]. It can be used to keep a short conversational memory.
79
80
81
82
83
84
85
86
87
	Context []int `json:"context,omitempty"`

	// Stream specifies whether the response is streaming; it is true by default.
	Stream *bool `json:"stream,omitempty"`

	// Raw set to true means that no formatting will be applied to the prompt.
	Raw bool `json:"raw,omitempty"`

	// Format specifies the format to return a response in.
88
	Format json.RawMessage `json:"format,omitempty"`
89
90
91
92
93

	// KeepAlive controls how long the model will stay loaded in memory following
	// this request.
	KeepAlive *Duration `json:"keep_alive,omitempty"`

94
	// Images is an optional list of raw image bytes accompanying this
95
96
97
98
99
	// request, for multimodal models.
	Images []ImageData `json:"images,omitempty"`

	// Options lists model-specific options. For example, temperature can be
	// set through this field, if the model supports it.
100
	Options map[string]any `json:"options"`
101
102

	// Think controls whether thinking/reasoning models will think before
Michael Yang's avatar
Michael Yang committed
103
104
	// responding. Can be a boolean (true/false) or a string ("high", "medium", "low")
	// for supported models. Needs to be a pointer so we can distinguish between false
105
106
	// (request that thinking _not_ be used) and unset (use the old behavior
	// before this option was introduced)
Michael Yang's avatar
Michael Yang committed
107
	Think *ThinkValue `json:"think,omitempty"`
108

109
110
111
112
113
114
115
116
	// Truncate is a boolean that, when set to true, truncates the chat history messages
	// if the rendered prompt exceeds the context length limit.
	Truncate *bool `json:"truncate,omitempty"`

	// Shift is a boolean that, when set to true, shifts the chat history
	// when hitting the context length limit instead of erroring.
	Shift *bool `json:"shift,omitempty"`

117
118
119
	// DebugRenderOnly is a debug option that, when set to true, returns the rendered
	// template instead of calling the model.
	DebugRenderOnly bool `json:"_debug_render_only,omitempty"`
120
121
122
123
124
125
126
127

	// Logprobs specifies whether to return log probabilities of the output tokens.
	Logprobs bool `json:"logprobs,omitempty"`

	// TopLogprobs is the number of most likely tokens to return at each token position,
	// each with an associated log probability. Only applies when Logprobs is true.
	// Valid values are 0-20. Default is 0 (only return the selected token's logprob).
	TopLogprobs int `json:"top_logprobs,omitempty"`
128
129
}

130
// ChatRequest describes a request sent by [Client.Chat].
Bruce MacDonald's avatar
Bruce MacDonald committed
131
type ChatRequest struct {
132
133
134
135
136
137
	// Model is the model name, as in [GenerateRequest].
	Model string `json:"model"`

	// Messages is the messages of the chat - can be used to keep a chat memory.
	Messages []Message `json:"messages"`

138
	// Stream enables streaming of returned responses; true by default.
139
140
141
	Stream *bool `json:"stream,omitempty"`

	// Format is the format to return the response in (e.g. "json").
142
	Format json.RawMessage `json:"format,omitempty"`
143
144

	// KeepAlive controls how long the model will stay loaded into memory
145
	// following the request.
146
	KeepAlive *Duration `json:"keep_alive,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
147

Michael Yang's avatar
tools  
Michael Yang committed
148
	// Tools is an optional list of tools the model has access to.
149
	Tools `json:"tools,omitempty"`
Michael Yang's avatar
tools  
Michael Yang committed
150

151
	// Options lists model-specific options.
152
	Options map[string]any `json:"options"`
153
154

	// Think controls whether thinking/reasoning models will think before
Michael Yang's avatar
Michael Yang committed
155
156
157
	// responding. Can be a boolean (true/false) or a string ("high", "medium", "low")
	// for supported models.
	Think *ThinkValue `json:"think,omitempty"`
158

159
160
161
162
163
164
165
166
	// Truncate is a boolean that, when set to true, truncates the chat history messages
	// if the rendered prompt exceeds the context length limit.
	Truncate *bool `json:"truncate,omitempty"`

	// Shift is a boolean that, when set to true, shifts the chat history
	// when hitting the context length limit instead of erroring.
	Shift *bool `json:"shift,omitempty"`

167
168
169
	// DebugRenderOnly is a debug option that, when set to true, returns the rendered
	// template instead of calling the model.
	DebugRenderOnly bool `json:"_debug_render_only,omitempty"`
170
171
172
173
174
175
176
177

	// Logprobs specifies whether to return log probabilities of the output tokens.
	Logprobs bool `json:"logprobs,omitempty"`

	// TopLogprobs is the number of most likely tokens to return at each token position,
	// each with an associated log probability. Only applies when Logprobs is true.
	// Valid values are 0-20. Default is 0 (only return the selected token's logprob).
	TopLogprobs int `json:"top_logprobs,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
178
179
}

180
181
182
183
184
185
186
type Tools []Tool

func (t Tools) String() string {
	bts, _ := json.Marshal(t)
	return string(bts)
}

187
188
189
190
191
func (t Tool) String() string {
	bts, _ := json.Marshal(t)
	return string(bts)
}

192
193
194
// Message is a single message in a chat sequence. The message contains the
// role ("system", "user", or "assistant"), the content and an optional list
// of images.
Bruce MacDonald's avatar
Bruce MacDonald committed
195
type Message struct {
196
197
198
199
	Role    string `json:"role"`
	Content string `json:"content"`
	// Thinking contains the text that was inside thinking tags in the
	// original model output when ChatRequest.Think is enabled.
Grace's avatar
Grace committed
200
201
202
203
204
	Thinking   string      `json:"thinking,omitempty"`
	Images     []ImageData `json:"images,omitempty"`
	ToolCalls  []ToolCall  `json:"tool_calls,omitempty"`
	ToolName   string      `json:"tool_name,omitempty"`
	ToolCallID string      `json:"tool_call_id,omitempty"`
Michael Yang's avatar
tools  
Michael Yang committed
205
206
}

207
208
209
210
211
212
213
214
215
216
217
218
func (m *Message) UnmarshalJSON(b []byte) error {
	type Alias Message
	var a Alias
	if err := json.Unmarshal(b, &a); err != nil {
		return err
	}

	*m = Message(a)
	m.Role = strings.ToLower(m.Role)
	return nil
}

219
type ToolCall struct {
Grace's avatar
Grace committed
220
	ID       string           `json:"id,omitempty"`
221
222
223
224
	Function ToolCallFunction `json:"function"`
}

type ToolCallFunction struct {
225
	Index     int                       `json:"index"`
226
227
228
229
230
231
232
233
234
235
236
237
238
	Name      string                    `json:"name"`
	Arguments ToolCallFunctionArguments `json:"arguments"`
}

type ToolCallFunctionArguments map[string]any

func (t *ToolCallFunctionArguments) String() string {
	bts, _ := json.Marshal(t)
	return string(bts)
}

type Tool struct {
	Type     string       `json:"type"`
239
	Items    any          `json:"items,omitempty"`
240
241
242
	Function ToolFunction `json:"function"`
}

243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
// PropertyType can be either a string or an array of strings
type PropertyType []string

// UnmarshalJSON implements the json.Unmarshaler interface
func (pt *PropertyType) UnmarshalJSON(data []byte) error {
	// Try to unmarshal as a string first
	var s string
	if err := json.Unmarshal(data, &s); err == nil {
		*pt = []string{s}
		return nil
	}

	// If that fails, try to unmarshal as an array of strings
	var a []string
	if err := json.Unmarshal(data, &a); err != nil {
		return err
	}
	*pt = a
	return nil
}

// MarshalJSON implements the json.Marshaler interface
func (pt PropertyType) MarshalJSON() ([]byte, error) {
	if len(pt) == 1 {
		// If there's only one type, marshal as a string
		return json.Marshal(pt[0])
	}
	// Otherwise marshal as an array
	return json.Marshal([]string(pt))
}

// String returns a string representation of the PropertyType
func (pt PropertyType) String() string {
	if len(pt) == 0 {
		return ""
	}
	if len(pt) == 1 {
		return pt[0]
	}
	return fmt.Sprintf("%v", []string(pt))
}

Devon Rifkin's avatar
Devon Rifkin committed
285
type ToolProperty struct {
286
287
288
289
290
291
	AnyOf       []ToolProperty          `json:"anyOf,omitempty"`
	Type        PropertyType            `json:"type,omitempty"`
	Items       any                     `json:"items,omitempty"`
	Description string                  `json:"description,omitempty"`
	Enum        []any                   `json:"enum,omitempty"`
	Properties  map[string]ToolProperty `json:"properties,omitempty"`
Devon Rifkin's avatar
Devon Rifkin committed
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
}

// ToTypeScriptType converts a ToolProperty to a TypeScript type string
func (tp ToolProperty) ToTypeScriptType() string {
	if len(tp.AnyOf) > 0 {
		var types []string
		for _, anyOf := range tp.AnyOf {
			types = append(types, anyOf.ToTypeScriptType())
		}
		return strings.Join(types, " | ")
	}

	if len(tp.Type) == 0 {
		return "any"
	}

	if len(tp.Type) == 1 {
		return mapToTypeScriptType(tp.Type[0])
	}

	var types []string
	for _, t := range tp.Type {
		types = append(types, mapToTypeScriptType(t))
	}
	return strings.Join(types, " | ")
}

// mapToTypeScriptType maps JSON Schema types to TypeScript types
func mapToTypeScriptType(jsonType string) string {
	switch jsonType {
	case "string":
		return "string"
	case "number", "integer":
		return "number"
	case "boolean":
		return "boolean"
	case "array":
		return "any[]"
	case "object":
		return "Record<string, any>"
	case "null":
		return "null"
	default:
		return "any"
	}
}

339
340
341
342
type ToolFunctionParameters struct {
	Type       string                  `json:"type"`
	Defs       any                     `json:"$defs,omitempty"`
	Items      any                     `json:"items,omitempty"`
343
	Required   []string                `json:"required,omitempty"`
344
345
346
347
348
349
350
351
	Properties map[string]ToolProperty `json:"properties"`
}

func (t *ToolFunctionParameters) String() string {
	bts, _ := json.Marshal(t)
	return string(bts)
}

352
type ToolFunction struct {
353
	Name        string                 `json:"name"`
354
	Description string                 `json:"description,omitempty"`
355
	Parameters  ToolFunctionParameters `json:"parameters"`
356
357
358
359
360
361
362
}

func (t *ToolFunction) String() string {
	bts, _ := json.Marshal(t)
	return string(bts)
}

363
364
365
366
367
368
369
// TokenLogprob represents log probability information for a single token alternative.
type TokenLogprob struct {
	// Token is the text representation of the token.
	Token string `json:"token"`

	// Logprob is the log probability of this token.
	Logprob float64 `json:"logprob"`
370
371
372

	// Bytes contains the raw byte representation of the token
	Bytes []int `json:"bytes,omitempty"`
373
374
375
376
377
378
379
380
381
382
383
}

// Logprob contains log probability information for a generated token.
type Logprob struct {
	TokenLogprob

	// TopLogprobs contains the most likely tokens and their log probabilities
	// at this position, if requested via TopLogprobs parameter.
	TopLogprobs []TokenLogprob `json:"top_logprobs,omitempty"`
}

384
385
// ChatResponse is the response returned by [Client.Chat]. Its fields are
// similar to [GenerateResponse].
Bruce MacDonald's avatar
Bruce MacDonald committed
386
type ChatResponse struct {
387
388
389
390
391
392
393
394
	// Model is the model name that generated the response.
	Model string `json:"model"`

	// RemoteModel is the name of the upstream model that generated the response.
	RemoteModel string `json:"remote_model,omitempty"`

	// RemoteHost is the URL of the upstream Ollama host that generated the response.
	RemoteHost string `json:"remote_host,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
395

396
397
398
399
400
401
402
	// CreatedAt is the timestamp of the response.
	CreatedAt time.Time `json:"created_at"`

	// Message contains the message or part of a message from the model.
	Message Message `json:"message"`

	// Done specifies if the response is complete.
Bruce MacDonald's avatar
Bruce MacDonald committed
403
404
	Done bool `json:"done"`

405
406
407
408
409
	// DoneReason is the reason the model stopped generating text.
	DoneReason string `json:"done_reason,omitempty"`

	DebugInfo *DebugInfo `json:"_debug_info,omitempty"`

410
411
412
413
	// Logprobs contains log probability information for the generated tokens,
	// if requested via the Logprobs parameter.
	Logprobs []Logprob `json:"logprobs,omitempty"`

Bruce MacDonald's avatar
Bruce MacDonald committed
414
415
416
	Metrics
}

417
418
419
420
421
422
// DebugInfo contains debug information for template rendering
type DebugInfo struct {
	RenderedTemplate string `json:"rendered_template"`
	ImageCount       int    `json:"image_count,omitempty"`
}

Bruce MacDonald's avatar
Bruce MacDonald committed
423
424
425
426
427
428
429
430
431
type Metrics struct {
	TotalDuration      time.Duration `json:"total_duration,omitempty"`
	LoadDuration       time.Duration `json:"load_duration,omitempty"`
	PromptEvalCount    int           `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration time.Duration `json:"prompt_eval_duration,omitempty"`
	EvalCount          int           `json:"eval_count,omitempty"`
	EvalDuration       time.Duration `json:"eval_duration,omitempty"`
}

432
433
// Options specified in [GenerateRequest].  If you add a new option here, also
// add it to the API docs.
434
435
436
437
438
439
440
441
442
type Options struct {
	Runner

	// Predict options used at runtime
	NumKeep          int      `json:"num_keep,omitempty"`
	Seed             int      `json:"seed,omitempty"`
	NumPredict       int      `json:"num_predict,omitempty"`
	TopK             int      `json:"top_k,omitempty"`
	TopP             float32  `json:"top_p,omitempty"`
443
	MinP             float32  `json:"min_p,omitempty"`
444
445
446
447
448
449
450
451
452
453
454
	TypicalP         float32  `json:"typical_p,omitempty"`
	RepeatLastN      int      `json:"repeat_last_n,omitempty"`
	Temperature      float32  `json:"temperature,omitempty"`
	RepeatPenalty    float32  `json:"repeat_penalty,omitempty"`
	PresencePenalty  float32  `json:"presence_penalty,omitempty"`
	FrequencyPenalty float32  `json:"frequency_penalty,omitempty"`
	Stop             []string `json:"stop,omitempty"`
}

// Runner options which must be set when the model is loaded into memory
type Runner struct {
455
456
457
458
459
460
	NumCtx    int   `json:"num_ctx,omitempty"`
	NumBatch  int   `json:"num_batch,omitempty"`
	NumGPU    int   `json:"num_gpu,omitempty"`
	MainGPU   int   `json:"main_gpu,omitempty"`
	UseMMap   *bool `json:"use_mmap,omitempty"`
	NumThread int   `json:"num_thread,omitempty"`
461
462
}

463
464
465
466
467
468
469
470
471
472
473
474
// EmbedRequest is the request passed to [Client.Embed].
type EmbedRequest struct {
	// Model is the model name.
	Model string `json:"model"`

	// Input is the input to embed.
	Input any `json:"input"`

	// KeepAlive controls how long the model will stay loaded in memory following
	// this request.
	KeepAlive *Duration `json:"keep_alive,omitempty"`

475
	// Truncate truncates the input to fit the model's max sequence length.
476
477
	Truncate *bool `json:"truncate,omitempty"`

478
479
480
	// Dimensions truncates the output embedding to the specified dimension.
	Dimensions int `json:"dimensions,omitempty"`

481
	// Options lists model-specific options.
482
	Options map[string]any `json:"options"`
483
484
485
486
487
}

// EmbedResponse is the response from [Client.Embed].
type EmbedResponse struct {
	Model      string      `json:"model"`
488
	Embeddings [][]float32 `json:"embeddings"`
489
490
491
492

	TotalDuration   time.Duration `json:"total_duration,omitempty"`
	LoadDuration    time.Duration `json:"load_duration,omitempty"`
	PromptEvalCount int           `json:"prompt_eval_count,omitempty"`
493
494
}

495
// EmbeddingRequest is the request passed to [Client.Embeddings].
Bruce MacDonald's avatar
Bruce MacDonald committed
496
type EmbeddingRequest struct {
497
498
499
500
501
502
503
504
	// Model is the model name.
	Model string `json:"model"`

	// Prompt is the textual prompt to embed.
	Prompt string `json:"prompt"`

	// KeepAlive controls how long the model will stay loaded in memory following
	// this request.
505
	KeepAlive *Duration `json:"keep_alive,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
506

507
	// Options lists model-specific options.
508
	Options map[string]any `json:"options"`
Bruce MacDonald's avatar
Bruce MacDonald committed
509
510
}

511
// EmbeddingResponse is the response from [Client.Embeddings].
Bruce MacDonald's avatar
Bruce MacDonald committed
512
513
514
515
type EmbeddingResponse struct {
	Embedding []float64 `json:"embedding"`
}

516
// CreateRequest is the request passed to [Client.Create].
517
type CreateRequest struct {
518
519
520
521
522
523
524
	// Model is the model name to create.
	Model string `json:"model"`

	// Stream specifies whether the response is streaming; it is true by default.
	Stream *bool `json:"stream,omitempty"`

	// Quantize is the quantization format for the model; leave blank to not change the quantization level.
525
526
	Quantize string `json:"quantize,omitempty"`

527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
	// From is the name of the model or file to use as the source.
	From string `json:"from,omitempty"`

	// RemoteHost is the URL of the upstream ollama API for the model (if any).
	RemoteHost string `json:"remote_host,omitempty"`

	// Files is a map of files include when creating the model.
	Files map[string]string `json:"files,omitempty"`

	// Adapters is a map of LoRA adapters to include when creating the model.
	Adapters map[string]string `json:"adapters,omitempty"`

	// Template is the template used when constructing a request to the model.
	Template string `json:"template,omitempty"`

	// License is a string or list of strings for licenses.
	License any `json:"license,omitempty"`

	// System is the system prompt for the model.
	System string `json:"system,omitempty"`

	// Parameters is a map of hyper-parameters which are applied to the model.
	Parameters map[string]any `json:"parameters,omitempty"`

	// Messages is a list of messages added to the model before chat and generation requests.
	Messages []Message `json:"messages,omitempty"`

	Renderer string `json:"renderer,omitempty"`
	Parser   string `json:"parser,omitempty"`

	// Info is a map of additional information for the model
	Info map[string]any `json:"info,omitempty"`
559

Michael Yang's avatar
Michael Yang committed
560
	// Deprecated: set the model name with Model instead
Michael Yang's avatar
Michael Yang committed
561
	Name string `json:"name"`
Michael Yang's avatar
Michael Yang committed
562
	// Deprecated: use Quantize instead
563
	Quantization string `json:"quantization,omitempty"`
564
565
}

566
// DeleteRequest is the request passed to [Client.Delete].
567
type DeleteRequest struct {
Michael Yang's avatar
Michael Yang committed
568
569
	Model string `json:"model"`

Michael Yang's avatar
Michael Yang committed
570
	// Deprecated: set the model name with Model instead
571
572
573
	Name string `json:"name"`
}

574
// ShowRequest is the request passed to [Client.Show].
Patrick Devine's avatar
Patrick Devine committed
575
type ShowRequest struct {
576
577
	Model  string `json:"model"`
	System string `json:"system"`
Patrick Devine's avatar
Patrick Devine committed
578
579

	// Template is deprecated
580
	Template string `json:"template"`
581
	Verbose  bool   `json:"verbose"`
582

583
	Options map[string]any `json:"options"`
Michael Yang's avatar
Michael Yang committed
584

Michael Yang's avatar
Michael Yang committed
585
	// Deprecated: set the model name with Model instead
Michael Yang's avatar
Michael Yang committed
586
	Name string `json:"name"`
Patrick Devine's avatar
Patrick Devine committed
587
588
}

589
// ShowResponse is the response returned from [Client.Show].
Patrick Devine's avatar
Patrick Devine committed
590
type ShowResponse struct {
591
592
593
594
595
	License       string             `json:"license,omitempty"`
	Modelfile     string             `json:"modelfile,omitempty"`
	Parameters    string             `json:"parameters,omitempty"`
	Template      string             `json:"template,omitempty"`
	System        string             `json:"system,omitempty"`
Devon Rifkin's avatar
Devon Rifkin committed
596
597
	Renderer      string             `json:"renderer,omitempty"`
	Parser        string             `json:"parser,omitempty"`
598
599
	Details       ModelDetails       `json:"details,omitempty"`
	Messages      []Message          `json:"messages,omitempty"`
600
601
	RemoteModel   string             `json:"remote_model,omitempty"`
	RemoteHost    string             `json:"remote_host,omitempty"`
602
603
604
605
606
	ModelInfo     map[string]any     `json:"model_info,omitempty"`
	ProjectorInfo map[string]any     `json:"projector_info,omitempty"`
	Tensors       []Tensor           `json:"tensors,omitempty"`
	Capabilities  []model.Capability `json:"capabilities,omitempty"`
	ModifiedAt    time.Time          `json:"modified_at,omitempty"`
Patrick Devine's avatar
Patrick Devine committed
607
608
}

609
// CopyRequest is the request passed to [Client.Copy].
Patrick Devine's avatar
Patrick Devine committed
610
611
612
613
614
type CopyRequest struct {
	Source      string `json:"source"`
	Destination string `json:"destination"`
}

615
// PullRequest is the request passed to [Client.Pull].
Bruce MacDonald's avatar
Bruce MacDonald committed
616
type PullRequest struct {
Michael Yang's avatar
Michael Yang committed
617
	Model    string `json:"model"`
618
619
620
	Insecure bool   `json:"insecure,omitempty"` // Deprecated: ignored
	Username string `json:"username"`           // Deprecated: ignored
	Password string `json:"password"`           // Deprecated: ignored
621
	Stream   *bool  `json:"stream,omitempty"`
Michael Yang's avatar
Michael Yang committed
622

Michael Yang's avatar
Michael Yang committed
623
	// Deprecated: set the model name with Model instead
Michael Yang's avatar
Michael Yang committed
624
	Name string `json:"name"`
Bruce MacDonald's avatar
Bruce MacDonald committed
625
626
}

627
628
// ProgressResponse is the response passed to progress functions like
// [PullProgressFunc] and [PushProgressFunc].
629
type ProgressResponse struct {
630
631
	Status    string `json:"status"`
	Digest    string `json:"digest,omitempty"`
Michael Yang's avatar
Michael Yang committed
632
633
	Total     int64  `json:"total,omitempty"`
	Completed int64  `json:"completed,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
634
635
}

636
// PushRequest is the request passed to [Client.Push].
637
type PushRequest struct {
Michael Yang's avatar
Michael Yang committed
638
	Model    string `json:"model"`
639
	Insecure bool   `json:"insecure,omitempty"`
640
641
642
	Username string `json:"username"`
	Password string `json:"password"`
	Stream   *bool  `json:"stream,omitempty"`
Michael Yang's avatar
Michael Yang committed
643

Michael Yang's avatar
Michael Yang committed
644
	// Deprecated: set the model name with Model instead
Michael Yang's avatar
Michael Yang committed
645
	Name string `json:"name"`
646
}
647

648
// ListResponse is the response from [Client.List].
Patrick Devine's avatar
Patrick Devine committed
649
type ListResponse struct {
650
	Models []ListModelResponse `json:"models"`
Patrick Devine's avatar
Patrick Devine committed
651
652
}

653
654
655
656
657
658
659
// ProcessResponse is the response from [Client.Process].
type ProcessResponse struct {
	Models []ProcessModelResponse `json:"models"`
}

// ListModelResponse is a single model description in [ListResponse].
type ListModelResponse struct {
660
661
662
663
664
665
666
667
	Name        string       `json:"name"`
	Model       string       `json:"model"`
	RemoteModel string       `json:"remote_model,omitempty"`
	RemoteHost  string       `json:"remote_host,omitempty"`
	ModifiedAt  time.Time    `json:"modified_at"`
	Size        int64        `json:"size"`
	Digest      string       `json:"digest"`
	Details     ModelDetails `json:"details,omitempty"`
668
669
670
671
}

// ProcessModelResponse is a single model description in [ProcessResponse].
type ProcessModelResponse struct {
672
673
674
675
676
677
678
679
	Name          string       `json:"name"`
	Model         string       `json:"model"`
	Size          int64        `json:"size"`
	Digest        string       `json:"digest"`
	Details       ModelDetails `json:"details,omitempty"`
	ExpiresAt     time.Time    `json:"expires_at"`
	SizeVRAM      int64        `json:"size_vram"`
	ContextLength int          `json:"context_length"`
Patrick Devine's avatar
Patrick Devine committed
680
681
}

Patrick Devine's avatar
Patrick Devine committed
682
683
684
685
type TokenResponse struct {
	Token string `json:"token"`
}

686
// GenerateResponse is the response passed into [GenerateResponseFunc].
Michael Yang's avatar
Michael Yang committed
687
type GenerateResponse struct {
688
689
690
	// Model is the model name that generated the response.
	Model string `json:"model"`

691
692
693
694
695
696
	// RemoteModel is the name of the upstream model that generated the response.
	RemoteModel string `json:"remote_model,omitempty"`

	// RemoteHost is the URL of the upstream Ollama host that generated the response.
	RemoteHost string `json:"remote_host,omitempty"`

Michael Yang's avatar
Michael Yang committed
697
	// CreatedAt is the timestamp of the response.
698
699
	CreatedAt time.Time `json:"created_at"`

700
701
702
	// Response is the textual response itself.
	Response string `json:"response"`

703
704
705
706
	// Thinking contains the text that was inside thinking tags in the
	// original model output when ChatRequest.Think is enabled.
	Thinking string `json:"thinking,omitempty"`

707
708
709
	// Done specifies if the response is complete.
	Done bool `json:"done"`

710
	// DoneReason is the reason the model stopped generating text.
Bruce MacDonald's avatar
Bruce MacDonald committed
711
	DoneReason string `json:"done_reason,omitempty"`
712

713
714
	// Context is an encoding of the conversation used in this response; this
	// can be sent in the next request to keep a conversational memory.
Michael Yang's avatar
Michael Yang committed
715
	Context []int `json:"context,omitempty"`
716

Bruce MacDonald's avatar
Bruce MacDonald committed
717
	Metrics
Michael Yang's avatar
Michael Yang committed
718
719

	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
Devon Rifkin's avatar
Devon Rifkin committed
720
721

	DebugInfo *DebugInfo `json:"_debug_info,omitempty"`
722
723
724
725

	// Logprobs contains log probability information for the generated tokens,
	// if requested via the Logprobs parameter.
	Logprobs []Logprob `json:"logprobs,omitempty"`
726
727
}

728
// ModelDetails provides details about a model.
Patrick Devine's avatar
Patrick Devine committed
729
type ModelDetails struct {
730
	ParentModel       string   `json:"parent_model"`
Patrick Devine's avatar
Patrick Devine committed
731
732
733
734
735
736
737
	Format            string   `json:"format"`
	Family            string   `json:"family"`
	Families          []string `json:"families"`
	ParameterSize     string   `json:"parameter_size"`
	QuantizationLevel string   `json:"quantization_level"`
}

738
739
740
741
742
743
744
745
746
747
748
749
// UserResponse provides information about a user.
type UserResponse struct {
	ID        uuid.UUID `json:"id"`
	Email     string    `json:"email"`
	Name      string    `json:"name"`
	Bio       string    `json:"bio,omitempty"`
	AvatarURL string    `json:"avatarurl,omitempty"`
	FirstName string    `json:"firstname,omitempty"`
	LastName  string    `json:"lastname,omitempty"`
	Plan      string    `json:"plan,omitempty"`
}

750
751
752
753
754
755
756
// Tensor describes the metadata for a given tensor.
type Tensor struct {
	Name  string   `json:"name"`
	Type  string   `json:"type"`
	Shape []uint64 `json:"shape"`
}

Bruce MacDonald's avatar
Bruce MacDonald committed
757
758
759
func (m *Metrics) Summary() {
	if m.TotalDuration > 0 {
		fmt.Fprintf(os.Stderr, "total duration:       %v\n", m.TotalDuration)
760
761
	}

Bruce MacDonald's avatar
Bruce MacDonald committed
762
763
	if m.LoadDuration > 0 {
		fmt.Fprintf(os.Stderr, "load duration:        %v\n", m.LoadDuration)
Michael Yang's avatar
Michael Yang committed
764
765
	}

Bruce MacDonald's avatar
Bruce MacDonald committed
766
767
	if m.PromptEvalCount > 0 {
		fmt.Fprintf(os.Stderr, "prompt eval count:    %d token(s)\n", m.PromptEvalCount)
768
769
	}

Bruce MacDonald's avatar
Bruce MacDonald committed
770
771
772
	if m.PromptEvalDuration > 0 {
		fmt.Fprintf(os.Stderr, "prompt eval duration: %s\n", m.PromptEvalDuration)
		fmt.Fprintf(os.Stderr, "prompt eval rate:     %.2f tokens/s\n", float64(m.PromptEvalCount)/m.PromptEvalDuration.Seconds())
773
774
	}

Bruce MacDonald's avatar
Bruce MacDonald committed
775
776
	if m.EvalCount > 0 {
		fmt.Fprintf(os.Stderr, "eval count:           %d token(s)\n", m.EvalCount)
777
778
	}

Bruce MacDonald's avatar
Bruce MacDonald committed
779
780
781
	if m.EvalDuration > 0 {
		fmt.Fprintf(os.Stderr, "eval duration:        %s\n", m.EvalDuration)
		fmt.Fprintf(os.Stderr, "eval rate:            %.2f tokens/s\n", float64(m.EvalCount)/m.EvalDuration.Seconds())
782
	}
783
784
}

785
func (opts *Options) FromMap(m map[string]any) error {
786
787
788
789
790
791
792
793
794
795
796
797
798
	valueOpts := reflect.ValueOf(opts).Elem() // names of the fields in the options struct
	typeOpts := reflect.TypeOf(opts).Elem()   // types of the fields in the options struct

	// build map of json struct tags to their types
	jsonOpts := make(map[string]reflect.StructField)
	for _, field := range reflect.VisibleFields(typeOpts) {
		jsonTag := strings.Split(field.Tag.Get("json"), ",")[0]
		if jsonTag != "" {
			jsonOpts[jsonTag] = field
		}
	}

	for key, val := range m {
799
800
		opt, ok := jsonOpts[key]
		if !ok {
801
			slog.Warn("invalid option provided", "option", key)
802
803
			continue
		}
Michael Yang's avatar
Michael Yang committed
804

805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
		field := valueOpts.FieldByName(opt.Name)
		if field.IsValid() && field.CanSet() {
			if val == nil {
				continue
			}

			switch field.Kind() {
			case reflect.Int:
				switch t := val.(type) {
				case int64:
					field.SetInt(t)
				case float64:
					// when JSON unmarshals numbers, it uses float64, not int
					field.SetInt(int64(t))
				default:
					return fmt.Errorf("option %q must be of type integer", key)
				}
			case reflect.Bool:
				val, ok := val.(bool)
				if !ok {
					return fmt.Errorf("option %q must be of type boolean", key)
				}
				field.SetBool(val)
			case reflect.Float32:
				// JSON unmarshals to float64
				val, ok := val.(float64)
				if !ok {
					return fmt.Errorf("option %q must be of type float32", key)
				}
				field.SetFloat(val)
			case reflect.String:
				val, ok := val.(string)
				if !ok {
					return fmt.Errorf("option %q must be of type string", key)
				}
				field.SetString(val)
			case reflect.Slice:
842
843
				// JSON unmarshals to []any, not []string
				val, ok := val.([]any)
844
845
846
				if !ok {
					return fmt.Errorf("option %q must be of type array", key)
				}
847
				// convert []any to []string
848
849
850
				slice := make([]string, len(val))
				for i, item := range val {
					str, ok := item.(string)
851
					if !ok {
852
						return fmt.Errorf("option %q must be of an array of strings", key)
853
					}
854
					slice[i] = str
855
				}
856
				field.Set(reflect.ValueOf(slice))
857
858
859
860
861
862
863
864
865
866
867
			case reflect.Pointer:
				var b bool
				if field.Type() == reflect.TypeOf(&b) {
					val, ok := val.(bool)
					if !ok {
						return fmt.Errorf("option %q must be of type boolean", key)
					}
					field.Set(reflect.ValueOf(&val))
				} else {
					return fmt.Errorf("unknown type loading config params: %v %v", field.Kind(), field.Type())
				}
868
869
			default:
				return fmt.Errorf("unknown type loading config params: %v", field.Kind())
870
871
872
			}
		}
	}
873

874
875
876
	return nil
}

877
878
// DefaultOptions is the default set of options for [GenerateRequest]; these
// values are used unless the user specifies other values explicitly.
Michael Yang's avatar
Michael Yang committed
879
880
func DefaultOptions() Options {
	return Options{
881
		// options set on request to runner
882
883
884
885
		NumPredict: -1,

		// set a minimal num_keep to avoid issues on context shifts
		NumKeep:          4,
Michael Yang's avatar
Michael Yang committed
886
887
888
889
		Temperature:      0.8,
		TopK:             40,
		TopP:             0.9,
		TypicalP:         1.0,
890
891
892
893
894
		RepeatLastN:      64,
		RepeatPenalty:    1.1,
		PresencePenalty:  0.0,
		FrequencyPenalty: 0.0,
		Seed:             -1,
Michael Yang's avatar
Michael Yang committed
895

896
897
		Runner: Runner{
			// options set when the model is loaded
898
			NumCtx:    int(envconfig.ContextLength()),
Michael Yang's avatar
Michael Yang committed
899
900
			NumBatch:  512,
			NumGPU:    -1, // -1 here indicates that NumGPU should be set dynamically
901
			NumThread: 0,  // let the runtime decide
902
			UseMMap:   nil,
903
		},
Michael Yang's avatar
Michael Yang committed
904
	}
Jeffrey Morgan's avatar
Jeffrey Morgan committed
905
}
Michael Yang's avatar
Michael Yang committed
906

Michael Yang's avatar
Michael Yang committed
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
// ThinkValue represents a value that can be a boolean or a string ("high", "medium", "low")
type ThinkValue struct {
	// Value can be a bool or string
	Value interface{}
}

// IsValid checks if the ThinkValue is valid
func (t *ThinkValue) IsValid() bool {
	if t == nil || t.Value == nil {
		return true // nil is valid (means not set)
	}

	switch v := t.Value.(type) {
	case bool:
		return true
	case string:
		return v == "high" || v == "medium" || v == "low"
	default:
		return false
	}
}

// IsBool returns true if the value is a boolean
func (t *ThinkValue) IsBool() bool {
	if t == nil || t.Value == nil {
		return false
	}
	_, ok := t.Value.(bool)
	return ok
}

// IsString returns true if the value is a string
func (t *ThinkValue) IsString() bool {
	if t == nil || t.Value == nil {
		return false
	}
	_, ok := t.Value.(string)
	return ok
}

947
948
// Bool returns the value as a bool (true if enabled in any way)
func (t *ThinkValue) Bool() bool {
Michael Yang's avatar
Michael Yang committed
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
	if t == nil || t.Value == nil {
		return false
	}

	switch v := t.Value.(type) {
	case bool:
		return v
	case string:
		// Any string value ("high", "medium", "low") means thinking is enabled
		return v == "high" || v == "medium" || v == "low"
	default:
		return false
	}
}

964
965
// String returns the value as a string
func (t *ThinkValue) String() string {
Michael Yang's avatar
Michael Yang committed
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
	if t == nil || t.Value == nil {
		return ""
	}

	switch v := t.Value.(type) {
	case string:
		return v
	case bool:
		if v {
			return "medium" // Default level when just true
		}
		return ""
	default:
		return ""
	}
}

// UnmarshalJSON implements json.Unmarshaler
func (t *ThinkValue) UnmarshalJSON(data []byte) error {
	// Try to unmarshal as bool first
	var b bool
	if err := json.Unmarshal(data, &b); err == nil {
		t.Value = b
		return nil
	}

	// Try to unmarshal as string
	var s string
	if err := json.Unmarshal(data, &s); err == nil {
		// Validate string values
		if s != "high" && s != "medium" && s != "low" {
			return fmt.Errorf("invalid think value: %q (must be \"high\", \"medium\", \"low\", true, or false)", s)
		}
		t.Value = s
		return nil
	}

1003
	return fmt.Errorf("think must be a boolean or string (\"high\", \"medium\", \"low\", true, or false)")
Michael Yang's avatar
Michael Yang committed
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
}

// MarshalJSON implements json.Marshaler
func (t *ThinkValue) MarshalJSON() ([]byte, error) {
	if t == nil || t.Value == nil {
		return []byte("null"), nil
	}
	return json.Marshal(t.Value)
}

Michael Yang's avatar
Michael Yang committed
1014
1015
1016
1017
type Duration struct {
	time.Duration
}

1018
1019
1020
1021
1022
1023
1024
func (d Duration) MarshalJSON() ([]byte, error) {
	if d.Duration < 0 {
		return []byte("-1"), nil
	}
	return []byte("\"" + d.Duration.String() + "\""), nil
}

Michael Yang's avatar
Michael Yang committed
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
func (d *Duration) UnmarshalJSON(b []byte) (err error) {
	var v any
	if err := json.Unmarshal(b, &v); err != nil {
		return err
	}

	d.Duration = 5 * time.Minute

	switch t := v.(type) {
	case float64:
		if t < 0 {
bnorick's avatar
bnorick committed
1036
			d.Duration = time.Duration(math.MaxInt64)
1037
		} else {
Michael Yang's avatar
Michael Yang committed
1038
			d.Duration = time.Duration(t * float64(time.Second))
Michael Yang's avatar
Michael Yang committed
1039
1040
1041
1042
1043
1044
		}
	case string:
		d.Duration, err = time.ParseDuration(t)
		if err != nil {
			return err
		}
1045
		if d.Duration < 0 {
bnorick's avatar
bnorick committed
1046
			d.Duration = time.Duration(math.MaxInt64)
1047
		}
1048
1049
	default:
		return fmt.Errorf("Unsupported type: '%s'", reflect.TypeOf(v))
Michael Yang's avatar
Michael Yang committed
1050
1051
1052
1053
	}

	return nil
}
1054
1055

// FormatParams converts specified parameter options to their correct types
1056
func FormatParams(params map[string][]string) (map[string]any, error) {
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
	opts := Options{}
	valueOpts := reflect.ValueOf(&opts).Elem() // names of the fields in the options struct
	typeOpts := reflect.TypeOf(opts)           // types of the fields in the options struct

	// build map of json struct tags to their types
	jsonOpts := make(map[string]reflect.StructField)
	for _, field := range reflect.VisibleFields(typeOpts) {
		jsonTag := strings.Split(field.Tag.Get("json"), ",")[0]
		if jsonTag != "" {
			jsonOpts[jsonTag] = field
		}
	}

1070
	out := make(map[string]any)
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
	// iterate params and set values based on json struct tags
	for key, vals := range params {
		if opt, ok := jsonOpts[key]; !ok {
			return nil, fmt.Errorf("unknown parameter '%s'", key)
		} else {
			field := valueOpts.FieldByName(opt.Name)
			if field.IsValid() && field.CanSet() {
				switch field.Kind() {
				case reflect.Float32:
					floatVal, err := strconv.ParseFloat(vals[0], 32)
					if err != nil {
						return nil, fmt.Errorf("invalid float value %s", vals)
					}

					out[key] = float32(floatVal)
				case reflect.Int:
					intVal, err := strconv.ParseInt(vals[0], 10, 64)
					if err != nil {
						return nil, fmt.Errorf("invalid int value %s", vals)
					}

					out[key] = intVal
				case reflect.Bool:
					boolVal, err := strconv.ParseBool(vals[0])
					if err != nil {
						return nil, fmt.Errorf("invalid bool value %s", vals)
					}

					out[key] = boolVal
				case reflect.String:
					out[key] = vals[0]
				case reflect.Slice:
					// TODO: only string slices are supported right now
					out[key] = vals
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
				case reflect.Pointer:
					var b bool
					if field.Type() == reflect.TypeOf(&b) {
						boolVal, err := strconv.ParseBool(vals[0])
						if err != nil {
							return nil, fmt.Errorf("invalid bool value %s", vals)
						}
						out[key] = &boolVal
					} else {
						return nil, fmt.Errorf("unknown type %s for %s", field.Kind(), key)
					}
1116
1117
1118
1119
1120
1121
1122
1123
1124
				default:
					return nil, fmt.Errorf("unknown type %s for %s", field.Kind(), key)
				}
			}
		}
	}

	return out, nil
}