ollama

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2026 License: MIT Imports: 10 Imported by: 0

README

Ollama Go SDK

A lightweight Go SDK for the Ollama API.

The client uses an OpenAI-style shape: services on the client, typed params for requests, and typed responses back.

res, err := client.Generate.New(ctx, ollama.GenerateNewParams{
	Model:  "gemma3",
	Prompt: "Why is the sky blue?",
})

Install

go get github.com/webdock-io/ollama-go-sdk

Quick Start

package main

import (
	"context"
	"fmt"
	"log"

	ollama "github.com/webdock-io/ollama-go-sdk"
)

func main() {
	ctx := context.Background()

	client, err := ollama.NewClient()
	if err != nil {
		log.Fatal(err)
	}

	res, err := client.Generate.New(ctx, ollama.GenerateNewParams{
		Model:  "gemma3",
		Prompt: "Explain DNS in one paragraph.",
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(res.Response)
}

By default, NewClient uses the local Ollama API at http://localhost:11434/api.

Cloud And Headers

Use NewCloud for Ollama Cloud, and pass auth or custom headers with WithHeaders.

client, err := ollama.NewCloud(
	ollama.WithHeaders(map[string]string{
		"Authorization": "Bearer " + os.Getenv("OLLAMA_API_KEY"),
	}),
)

You can also set the base URL explicitly:

client, err := ollama.NewClient(
	ollama.WithBaseURL("https://ollama.com/api"),
	ollama.WithHeaders(map[string]string{
		"Authorization": "Bearer " + os.Getenv("OLLAMA_API_KEY"),
	}),
)

Custom HTTP Client

Pass WithHTTPClient when you need custom timeouts, transports, proxies, or other net/http behavior.

httpClient := &http.Client{
	Timeout: 30 * time.Second,
}

client, err := ollama.NewClient(
	ollama.WithHTTPClient(httpClient),
)

Chat

res, err := client.Chat.New(ctx, ollama.ChatNewParams{
	Model: "gemma3",
	Messages: []ollama.Message{
		ollama.NewMessage(ollama.RoleSystem, "You are concise."),
		ollama.NewMessage(ollama.RoleUser, "Give me one fact about Saturn."),
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(res.Message.Content)

Streaming

Streaming methods set stream: true, parse Ollama's newline-delimited JSON, and skip chunks with no result payload.

err := client.Generate.NewStreaming(ctx, ollama.GenerateNewParams{
	Model:  "gemma3",
	Prompt: "Write a haiku about compilers.",
}, func(chunk ollama.GenerateResponse) error {
	fmt.Print(chunk.Response)
	return nil
})
if err != nil {
	log.Fatal(err)
}

Chat streaming works the same way:

err := client.Chat.NewStreaming(ctx, ollama.ChatNewParams{
	Model: "gemma3",
	Messages: []ollama.Message{
		ollama.NewMessage(ollama.RoleUser, "Tell me a short story."),
	},
}, func(chunk ollama.ChatResponse) error {
	fmt.Print(chunk.Message.Content)
	return nil
})

Context Limit Controls

Use pointers for optional booleans so an explicit false is sent instead of being omitted from the JSON request:

res, err := client.Chat.New(ctx, ollama.ChatNewParams{
	Model: "gemma3",
	Messages: []ollama.Message{
		ollama.NewMessage(ollama.RoleUser, "Summarize this conversation."),
	},
	Truncate: ollama.Bool(false),
	Shift:    ollama.Bool(false),
})

Runtime Options

Runtime options use enum-style keys instead of raw strings.

res, err := client.Generate.New(ctx, ollama.GenerateNewParams{
	Model:  "gemma3",
	Prompt: "Explain DNS in one paragraph.",
	Options: ollama.Options{
		ollama.Temperature:     0.2,
		ollama.NumCtx:          4096,
		ollama.TopP:            0.9,
		ollama.DraftNumPredict: 4,
	},
})

Models

models, err := client.Models.List(ctx)
running, err := client.Models.ListRunning(ctx)

details, err := client.Models.Show(ctx, ollama.ModelShowParams{
	Model: "gemma3",
})

status, err := client.Models.Pull(ctx, ollama.ModelPullParams{
	Model: "gemma3",
})

err = client.Models.Copy(ctx, ollama.ModelCopyParams{
	Source:      "gemma3",
	Destination: "gemma3-backup",
})

err = client.Models.Delete(ctx, ollama.ModelDeleteParams{
	Model: "gemma3-backup",
})

Embeddings

res, err := client.Embeddings.New(ctx, ollama.EmbeddingNewParams{
	Model:     "embeddinggemma",
	KeepAlive: "10m",
	Truncate:  ollama.Bool(false),
	Input: []string{
		"hello",
		"world",
	},
})
if err != nil {
	log.Fatal(err)
}

fmt.Println(len(res.Embeddings))

Version

version, err := client.Version.Get(ctx)

Local Examples

If you add a runnable example inside this repository, put it in a separate folder such as examples/quickstart.

Do not place a package main example file next to the SDK files, because Go requires one package per directory.

Documentation

Index

Constants

View Source 
const (
	// DefaultBaseURL is the local Ollama API URL documented by Ollama.
	DefaultBaseURL = "http://localhost:11434/api"

	// CloudBaseURL is the hosted Ollama API URL used with API-key auth.
	CloudBaseURL = "https://ollama.com/api"
)
View Source 
const (
	RoleSystem    = "system"
	RoleUser      = "user"
	RoleAssistant = "assistant"
	RoleTool      = "tool"
)

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a bool pointer for optional params.

func Int 

func Int(v int) *int

Int returns an int pointer for optional params.

Types

type APIError 

type APIError struct {
	StatusCode int
	Status     string
	Message    string
	Body       []byte
}

APIError represents an error response from the Ollama API.

func (*APIError) Error 

func (e *APIError) Error() string

type ChatNewParams 

type ChatNewParams struct {
	Model       string    `json:"model"`
	Messages    []Message `json:"messages"`
	Tools       []Tool    `json:"tools,omitempty"`
	Format      any       `json:"format,omitempty"`
	Options     Options   `json:"options,omitempty"`
	Stream      *bool     `json:"stream,omitempty"`
	Think       any       `json:"think,omitempty"`
	KeepAlive   any       `json:"keep_alive,omitempty"`
	Truncate    *bool     `json:"truncate,omitempty"`
	Shift       *bool     `json:"shift,omitempty"`
	LogProbs    *bool     `json:"logprobs,omitempty"`
	TopLogProbs *int      `json:"top_logprobs,omitempty"`
}

ChatNewParams contains params for POST /api/chat.

type ChatResponse 

type ChatResponse struct {
	Model       string    `json:"model"`
	RemoteModel string    `json:"remote_model,omitempty"`
	RemoteHost  string    `json:"remote_host,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	Message     Message   `json:"message"`
	Done        bool      `json:"done"`
	DoneReason  string    `json:"done_reason,omitempty"`
	Metrics
	LogProbs []LogProb `json:"logprobs,omitempty"`
}

ChatResponse is returned by /api/chat.

type ChatService 

type ChatService struct {
	// contains filtered or unexported fields
}

ChatService handles /api/chat.

func (*ChatService) New 

func (s *ChatService) New(ctx context.Context, params ChatNewParams) (*ChatResponse, error)

New creates a non-streaming chat request.

func (*ChatService) NewStreaming 

func (s *ChatService) NewStreaming(ctx context.Context, params ChatNewParams, fn func(ChatResponse) error) error

NewStreaming creates a streaming chat request and calls fn for each chunk.

type Client 

type Client struct {
	Generate   *GenerateService
	Chat       *ChatService
	Embeddings *EmbeddingService
	Models     *ModelService
	Version    *VersionService
	// contains filtered or unexported fields
}

Client is an Ollama API client.

func MustNew 

func MustNew(opts ...Option) *Client

MustNew creates a client and panics if configuration is invalid.

func New 

func New(opts ...Option) (*Client, error)

New creates a client for the local Ollama API by default.

func NewClient 

func NewClient(opts ...Option) (*Client, error)

NewClient creates a client for the local Ollama API by default.

func NewCloud 

func NewCloud(opts ...Option) (*Client, error)

NewCloud creates a client for https://ollama.com/api.

type EmbedResponse 

type EmbedResponse struct {
	Model           string      `json:"model"`
	Embeddings      [][]float64 `json:"embeddings"`
	TotalDuration   int64       `json:"total_duration,omitempty"`
	LoadDuration    int64       `json:"load_duration,omitempty"`
	PromptEvalCount int         `json:"prompt_eval_count,omitempty"`
}

EmbedResponse is returned by /api/embed.

type EmbeddingNewParams 

type EmbeddingNewParams struct {
	Model      string  `json:"model"`
	Input      any     `json:"input"`
	KeepAlive  any     `json:"keep_alive,omitempty"`
	Truncate   *bool   `json:"truncate,omitempty"`
	Dimensions *int    `json:"dimensions,omitempty"`
	Options    Options `json:"options,omitempty"`
}

EmbeddingNewParams contains params for POST /api/embed.

type EmbeddingService 

type EmbeddingService struct {
	// contains filtered or unexported fields
}

EmbeddingService handles /api/embed.

func (*EmbeddingService) New 

func (s *EmbeddingService) New(ctx context.Context, params EmbeddingNewParams) (*EmbedResponse, error)

New creates an embedding request.

type FunctionCall 

type FunctionCall struct {
	Index       int            `json:"index,omitempty"`
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Arguments   map[string]any `json:"arguments,omitempty"`
}

FunctionCall contains function call details returned by the model.

type GenerateNewParams 

type GenerateNewParams struct {
	Model       string   `json:"model"`
	Prompt      string   `json:"prompt,omitempty"`
	Suffix      string   `json:"suffix,omitempty"`
	Images      []string `json:"images,omitempty"`
	Format      any      `json:"format,omitempty"`
	System      string   `json:"system,omitempty"`
	Template    string   `json:"template,omitempty"`
	Context     []int    `json:"context,omitempty"`
	Stream      *bool    `json:"stream,omitempty"`
	Think       any      `json:"think,omitempty"`
	Raw         *bool    `json:"raw,omitempty"`
	KeepAlive   any      `json:"keep_alive,omitempty"`
	Options     Options  `json:"options,omitempty"`
	Truncate    *bool    `json:"truncate,omitempty"`
	Shift       *bool    `json:"shift,omitempty"`
	LogProbs    *bool    `json:"logprobs,omitempty"`
	TopLogProbs *int     `json:"top_logprobs,omitempty"`
	Width       *int     `json:"width,omitempty"`
	Height      *int     `json:"height,omitempty"`
	Steps       *int     `json:"steps,omitempty"`
}

GenerateNewParams contains params for POST /api/generate.

type GenerateResponse 

type GenerateResponse struct {
	Model       string    `json:"model"`
	RemoteModel string    `json:"remote_model,omitempty"`
	RemoteHost  string    `json:"remote_host,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	Response    string    `json:"response"`
	Thinking    string    `json:"thinking,omitempty"`
	Done        bool      `json:"done"`
	DoneReason  string    `json:"done_reason,omitempty"`
	Metrics
	Context   []int      `json:"context,omitempty"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	LogProbs  []LogProb  `json:"logprobs,omitempty"`
	Image     string     `json:"image,omitempty"`
	Completed int64      `json:"completed,omitempty"`
	Total     int64      `json:"total,omitempty"`
}

GenerateResponse is returned by /api/generate.

type GenerateService 

type GenerateService struct {
	// contains filtered or unexported fields
}

GenerateService handles /api/generate.

func (*GenerateService) New 

func (s *GenerateService) New(ctx context.Context, params GenerateNewParams) (*GenerateResponse, error)

New creates a non-streaming generate request.

func (*GenerateService) NewStreaming 

func (s *GenerateService) NewStreaming(ctx context.Context, params GenerateNewParams, fn func(GenerateResponse) error) error

NewStreaming creates a streaming generate request and calls fn for each chunk.

type ListModelsResponse 

type ListModelsResponse struct {
	Models []Model `json:"models"`
}

ListModelsResponse is returned by /api/tags.

type ListRunningModelsResponse 

type ListRunningModelsResponse struct {
	Models []Model `json:"models"`
}

ListRunningModelsResponse is returned by /api/ps.

type LogProb 

type LogProb struct {
	Token       string       `json:"token"`
	LogProb     float64      `json:"logprob"`
	Bytes       []int        `json:"bytes,omitempty"`
	TopLogProbs []TopLogProb `json:"top_logprobs,omitempty"`
}

LogProb contains log probability information for an output token.

type Message 

type Message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content,omitempty"`
	Thinking   string     `json:"thinking,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
	Images     []string   `json:"images,omitempty"`
	ToolName   string     `json:"tool_name,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

Message is a chat message accepted and returned by /api/chat.

func NewMessage 

func NewMessage(role, content string) Message

NewMessage creates a chat message.

type Metrics 

type Metrics struct {
	TotalDuration      int64 `json:"total_duration,omitempty"`
	LoadDuration       int64 `json:"load_duration,omitempty"`
	PromptEvalCount    int   `json:"prompt_eval_count,omitempty"`
	PromptEvalDuration int64 `json:"prompt_eval_duration,omitempty"`
	EvalCount          int   `json:"eval_count,omitempty"`
	EvalDuration       int64 `json:"eval_duration,omitempty"`
}

Metrics contains timing and token usage fields returned by generation endpoints.

type MissingFieldError 

type MissingFieldError struct {
	Field string
}

MissingFieldError is returned before a request when a required builder field is empty.

func (*MissingFieldError) Error 

func (e *MissingFieldError) Error() string

type Model 

type Model struct {
	Name          string       `json:"name"`
	Model         string       `json:"model"`
	ModifiedAt    time.Time    `json:"modified_at,omitempty"`
	Size          int64        `json:"size,omitempty"`
	Digest        string       `json:"digest,omitempty"`
	Details       ModelDetails `json:"details,omitempty"`
	ExpiresAt     time.Time    `json:"expires_at,omitempty"`
	SizeVRAM      int64        `json:"size_vram,omitempty"`
	ContextLength int          `json:"context_length,omitempty"`
}

Model contains local or running model metadata.

type ModelCopyParams 

type ModelCopyParams struct {
	Source      string `json:"source"`
	Destination string `json:"destination"`
}

ModelCopyParams contains params for POST /api/copy.

type ModelCreateParams 

type ModelCreateParams struct {
	Model         string            `json:"model"`
	From          string            `json:"from,omitempty"`
	RemoteHost    string            `json:"remote_host,omitempty"`
	Files         map[string]string `json:"files,omitempty"`
	DraftFiles    map[string]string `json:"draft_files,omitempty"`
	Adapters      map[string]string `json:"adapters,omitempty"`
	Template      string            `json:"template,omitempty"`
	License       any               `json:"license,omitempty"`
	System        string            `json:"system,omitempty"`
	Parameters    map[string]any    `json:"parameters,omitempty"`
	Messages      []Message         `json:"messages,omitempty"`
	Renderer      string            `json:"renderer,omitempty"`
	Parser        string            `json:"parser,omitempty"`
	Requires      string            `json:"requires,omitempty"`
	Info          map[string]any    `json:"info,omitempty"`
	Quantize      string            `json:"quantize,omitempty"`
	DraftQuantize string            `json:"draft_quantize,omitempty"`
	Stream        *bool             `json:"stream,omitempty"`
}

ModelCreateParams contains params for POST /api/create.

type ModelDeleteParams 

type ModelDeleteParams struct {
	Model string `json:"model"`
}

ModelDeleteParams contains params for DELETE /api/delete.

type ModelDetails 

type ModelDetails struct {
	ParentModel       string   `json:"parent_model,omitempty"`
	Format            string   `json:"format,omitempty"`
	Family            string   `json:"family,omitempty"`
	Families          []string `json:"families,omitempty"`
	ParameterSize     string   `json:"parameter_size,omitempty"`
	QuantizationLevel string   `json:"quantization_level,omitempty"`
}

ModelDetails contains high-level model metadata.

type ModelPullParams 

type ModelPullParams struct {
	Model    string `json:"model"`
	Insecure *bool  `json:"insecure,omitempty"`
	Stream   *bool  `json:"stream,omitempty"`
}

ModelPullParams contains params for POST /api/pull.

type ModelPushParams 

type ModelPushParams struct {
	Model    string `json:"model"`
	Insecure *bool  `json:"insecure,omitempty"`
	Stream   *bool  `json:"stream,omitempty"`
}

ModelPushParams contains params for POST /api/push.

type ModelService 

type ModelService struct {
	// contains filtered or unexported fields
}

ModelService handles Ollama model endpoints.

func (*ModelService) Copy 

func (s *ModelService) Copy(ctx context.Context, params ModelCopyParams) error

Copy calls POST /api/copy.

func (*ModelService) Create 

func (s *ModelService) Create(ctx context.Context, params ModelCreateParams) (*StatusResponse, error)

Create calls POST /api/create.

func (*ModelService) CreateStreaming 

func (s *ModelService) CreateStreaming(ctx context.Context, params ModelCreateParams, fn func(StatusResponse) error) error

CreateStreaming calls POST /api/create with stream enabled.

func (*ModelService) Delete 

func (s *ModelService) Delete(ctx context.Context, params ModelDeleteParams) error

Delete calls DELETE /api/delete.

func (*ModelService) List 

func (s *ModelService) List(ctx context.Context) (*ListModelsResponse, error)

List calls GET /api/tags.

func (*ModelService) ListRunning 

func (s *ModelService) ListRunning(ctx context.Context) (*ListRunningModelsResponse, error)

ListRunning calls GET /api/ps.

func (*ModelService) Pull 

func (s *ModelService) Pull(ctx context.Context, params ModelPullParams) (*StatusResponse, error)

Pull calls POST /api/pull.

func (*ModelService) PullStreaming 

func (s *ModelService) PullStreaming(ctx context.Context, params ModelPullParams, fn func(StatusResponse) error) error

PullStreaming calls POST /api/pull with stream enabled.

func (*ModelService) Push 

func (s *ModelService) Push(ctx context.Context, params ModelPushParams) (*StatusResponse, error)

Push calls POST /api/push.

func (*ModelService) PushStreaming 

func (s *ModelService) PushStreaming(ctx context.Context, params ModelPushParams, fn func(StatusResponse) error) error

PushStreaming calls POST /api/push with stream enabled.

func (*ModelService) Show 

func (s *ModelService) Show(ctx context.Context, params ModelShowParams) (*ShowResponse, error)

Show calls POST /api/show.

type ModelShowParams 

type ModelShowParams struct {
	Model    string         `json:"model"`
	System   string         `json:"system,omitempty"`
	Template string         `json:"template,omitempty"`
	Verbose  *bool          `json:"verbose,omitempty"`
	Options  map[string]any `json:"options,omitempty"`
}

ModelShowParams contains params for POST /api/show.

type Option 

type Option func(*Client) error

Option configures a Client.

func WithBaseURL 

func WithBaseURL(rawURL string) Option

WithBaseURL sets the API base URL. If only a host is provided, /api is added.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the HTTP client used for requests.

func WithHeader 

func WithHeader(key, value string) Option

WithHeader sets a header on every request.

func WithHeaders 

func WithHeaders(headers map[string]string) Option

WithHeaders sets multiple headers on every request.

func WithUserAgent 

func WithUserAgent(userAgent string) Option

WithUserAgent sets the User-Agent header sent with requests.

type OptionKey 

type OptionKey string

OptionKey is an enum-style key for Ollama runtime options. 

const (
	NumCtx           OptionKey = "num_ctx"
	NumBatch         OptionKey = "num_batch"
	NumGPU           OptionKey = "num_gpu"
	MainGPU          OptionKey = "main_gpu"
	UseMMap          OptionKey = "use_mmap"
	NumThread        OptionKey = "num_thread"
	DraftNumPredict  OptionKey = "draft_num_predict"
	NumKeep          OptionKey = "num_keep"
	Seed             OptionKey = "seed"
	NumPredict       OptionKey = "num_predict"
	TopK             OptionKey = "top_k"
	TopP             OptionKey = "top_p"
	MinP             OptionKey = "min_p"
	TypicalP         OptionKey = "typical_p"
	RepeatLastN      OptionKey = "repeat_last_n"
	Temperature      OptionKey = "temperature"
	RepeatPenalty    OptionKey = "repeat_penalty"
	PresencePenalty  OptionKey = "presence_penalty"
	FrequencyPenalty OptionKey = "frequency_penalty"
	Stop             OptionKey = "stop"
)

func (OptionKey) String 

func (k OptionKey) String() string

type Options 

type Options map[OptionKey]any

Options contains Ollama runtime options keyed by OptionKey constants.

type ShowResponse 

type ShowResponse struct {
	Parameters   string         `json:"parameters,omitempty"`
	License      any            `json:"license,omitempty"`
	ModifiedAt   time.Time      `json:"modified_at,omitempty"`
	Details      ModelDetails   `json:"details,omitempty"`
	Template     string         `json:"template,omitempty"`
	Capabilities []string       `json:"capabilities,omitempty"`
	ModelInfo    map[string]any `json:"model_info,omitempty"`
}

ShowResponse is returned by /api/show.

type StatusResponse 

type StatusResponse struct {
	Status    string `json:"status"`
	Digest    string `json:"digest,omitempty"`
	Total     int64  `json:"total,omitempty"`
	Completed int64  `json:"completed,omitempty"`
}

StatusResponse is returned by model management endpoints that report progress.

type Tool 

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

Tool describes a callable function tool for chat requests.

type ToolCall 

type ToolCall struct {
	ID       string       `json:"id,omitempty"`
	Function FunctionCall `json:"function"`
}

ToolCall is a function call requested by the model.

type ToolFunction 

type ToolFunction struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Parameters  any    `json:"parameters,omitempty"`
}

ToolFunction describes a function exposed to the model.

type TopLogProb 

type TopLogProb struct {
	Token   string  `json:"token"`
	LogProb float64 `json:"logprob"`
	Bytes   []int   `json:"bytes,omitempty"`
}

TopLogProb is an alternate token probability.

type VersionResponse 

type VersionResponse struct {
	Version string `json:"version"`
}

VersionResponse is returned by /api/version.

type VersionService 

type VersionService struct {
	// contains filtered or unexported fields
}

VersionService handles /api/version.

func (*VersionService) Get 

func (s *VersionService) Get(ctx context.Context) (*VersionResponse, error)

Get calls GET /api/version.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.