types.go 33.6 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
286
type ToolProperty struct {
	AnyOf       []ToolProperty `json:"anyOf,omitempty"`
287
	Type        PropertyType   `json:"type,omitempty"`
Devon Rifkin's avatar
Devon Rifkin committed
288
	Items       any            `json:"items,omitempty"`
289
	Description string         `json:"description,omitempty"`
Devon Rifkin's avatar
Devon Rifkin committed
290
291
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
	Enum        []any          `json:"enum,omitempty"`
}

// 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"
	}
}

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

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

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

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

362
363
364
365
366
367
368
// 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"`
369
370
371

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

// 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"`
}

383
384
// ChatResponse is the response returned by [Client.Chat]. Its fields are
// similar to [GenerateResponse].
Bruce MacDonald's avatar
Bruce MacDonald committed
385
type ChatResponse struct {
386
387
388
389
390
391
392
393
	// 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
394

395
396
397
398
399
400
401
	// 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
402
403
	Done bool `json:"done"`

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

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

409
410
411
412
	// 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
413
414
415
	Metrics
}

416
417
418
419
420
421
// 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
422
423
424
425
426
427
428
429
430
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"`
}

431
432
// Options specified in [GenerateRequest].  If you add a new option here, also
// add it to the API docs.
433
434
435
436
437
438
439
440
441
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"`
442
	MinP             float32  `json:"min_p,omitempty"`
443
444
445
446
447
448
449
450
451
452
453
	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 {
454
455
456
457
458
459
	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"`
460
461
}

462
463
464
465
466
467
468
469
470
471
472
473
// 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"`

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

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

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

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

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

494
// EmbeddingRequest is the request passed to [Client.Embeddings].
Bruce MacDonald's avatar
Bruce MacDonald committed
495
type EmbeddingRequest struct {
496
497
498
499
500
501
502
503
	// 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.
504
	KeepAlive *Duration `json:"keep_alive,omitempty"`
Bruce MacDonald's avatar
Bruce MacDonald committed
505

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

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

515
// CreateRequest is the request passed to [Client.Create].
516
type CreateRequest struct {
517
518
519
520
521
522
523
	// 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.
524
525
	Quantize string `json:"quantize,omitempty"`

526
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
	// 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"`
558

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

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

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

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

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

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

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

588
// ShowResponse is the response returned from [Client.Show].
Patrick Devine's avatar
Patrick Devine committed
589
type ShowResponse struct {
590
591
592
593
594
	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
595
596
	Renderer      string             `json:"renderer,omitempty"`
	Parser        string             `json:"parser,omitempty"`
597
598
	Details       ModelDetails       `json:"details,omitempty"`
	Messages      []Message          `json:"messages,omitempty"`
599
600
	RemoteModel   string             `json:"remote_model,omitempty"`
	RemoteHost    string             `json:"remote_host,omitempty"`
601
602
603
604
605
	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
606
607
}

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

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

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

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

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

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

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

652
653
654
655
656
657
658
// 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 {
659
660
661
662
663
664
665
666
	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"`
667
668
669
670
}

// ProcessModelResponse is a single model description in [ProcessResponse].
type ProcessModelResponse struct {
671
672
673
674
675
676
677
678
	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
679
680
}

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

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

690
691
692
693
694
695
	// 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
696
	// CreatedAt is the timestamp of the response.
697
698
	CreatedAt time.Time `json:"created_at"`

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

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

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

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

712
713
	// 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
714
	Context []int `json:"context,omitempty"`
715

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

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

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

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

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

737
738
739
740
741
742
743
744
745
746
747
748
// 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"`
}

749
750
751
752
753
754
755
// 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
756
757
758
func (m *Metrics) Summary() {
	if m.TotalDuration > 0 {
		fmt.Fprintf(os.Stderr, "total duration:       %v\n", m.TotalDuration)
759
760
	}

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

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

Bruce MacDonald's avatar
Bruce MacDonald committed
769
770
771
	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())
772
773
	}

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

Bruce MacDonald's avatar
Bruce MacDonald committed
778
779
780
	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())
781
	}
782
783
}

784
func (opts *Options) FromMap(m map[string]any) error {
785
786
787
788
789
790
791
792
793
794
795
796
797
	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 {
798
799
		opt, ok := jsonOpts[key]
		if !ok {
800
			slog.Warn("invalid option provided", "option", key)
801
802
			continue
		}
Michael Yang's avatar
Michael Yang committed
803

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
		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:
841
842
				// JSON unmarshals to []any, not []string
				val, ok := val.([]any)
843
844
845
				if !ok {
					return fmt.Errorf("option %q must be of type array", key)
				}
846
				// convert []any to []string
847
848
849
				slice := make([]string, len(val))
				for i, item := range val {
					str, ok := item.(string)
850
					if !ok {
851
						return fmt.Errorf("option %q must be of an array of strings", key)
852
					}
853
					slice[i] = str
854
				}
855
				field.Set(reflect.ValueOf(slice))
856
857
858
859
860
861
862
863
864
865
866
			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())
				}
867
868
			default:
				return fmt.Errorf("unknown type loading config params: %v", field.Kind())
869
870
871
			}
		}
	}
872

873
874
875
	return nil
}

876
877
// 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
878
879
func DefaultOptions() Options {
	return Options{
880
		// options set on request to runner
881
882
883
884
		NumPredict: -1,

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

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

Michael Yang's avatar
Michael Yang committed
906
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
// 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
}

946
947
// 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
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
	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
	}
}

963
964
// String returns the value as a string
func (t *ThinkValue) String() string {
Michael Yang's avatar
Michael Yang committed
965
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
	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
	}

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

// 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
1013
1014
1015
1016
type Duration struct {
	time.Duration
}

1017
1018
1019
1020
1021
1022
1023
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
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
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
1035
			d.Duration = time.Duration(math.MaxInt64)
1036
		} else {
Michael Yang's avatar
Michael Yang committed
1037
			d.Duration = time.Duration(t * float64(time.Second))
Michael Yang's avatar
Michael Yang committed
1038
1039
1040
1041
1042
1043
		}
	case string:
		d.Duration, err = time.ParseDuration(t)
		if err != nil {
			return err
		}
1044
		if d.Duration < 0 {
bnorick's avatar
bnorick committed
1045
			d.Duration = time.Duration(math.MaxInt64)
1046
		}
1047
1048
	default:
		return fmt.Errorf("Unsupported type: '%s'", reflect.TypeOf(v))
Michael Yang's avatar
Michael Yang committed
1049
1050
1051
1052
	}

	return nil
}
1053
1054

// FormatParams converts specified parameter options to their correct types
1055
func FormatParams(params map[string][]string) (map[string]any, error) {
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
	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
		}
	}

1069
	out := make(map[string]any)
1070
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
	// 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
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
				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)
					}
1115
1116
1117
1118
1119
1120
1121
1122
1123
				default:
					return nil, fmt.Errorf("unknown type %s for %s", field.Kind(), key)
				}
			}
		}
	}

	return out, nil
}