ollama

package module
v1.0.3 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)

Error Handling

API errors retain Ollama's original status, message, and response body. Common conditions also support errors.Is with stable sentinel errors:

res, err := client.Generate.New(ctx, params)
if errors.Is(err, ollama.ErrContextLengthExceeded) {
	// Shorten the prompt, increase num_ctx, or enable truncation/shift.
}

var apiErr *ollama.APIError
if errors.As(err, &apiErr) {
	fmt.Println(apiErr.StatusCode, apiErr.Message)
}

Available classifications are ErrContextLengthExceeded, ErrModelNotFound, ErrUnauthorized, ErrRateLimited, ErrServerBusy, and ErrUnsupportedCapability.

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

View Source
var (
	// ErrContextLengthExceeded indicates that an input or prompt does not fit
	// within the model's available context window.
	ErrContextLengthExceeded = errors.New("ollama: context length exceeded")

	// ErrModelNotFound indicates that the requested model is not available.
	ErrModelNotFound = errors.New("ollama: model not found")

	// ErrUnauthorized indicates that authentication is required or was rejected.
	ErrUnauthorized = errors.New("ollama: unauthorized")

	// ErrRateLimited indicates that the server or an upstream service applied a
	// request rate limit.
	ErrRateLimited = errors.New("ollama: rate limited")

	// ErrServerBusy indicates that Ollama cannot currently schedule the request.
	ErrServerBusy = errors.New("ollama: server busy")

	// ErrUnsupportedCapability indicates that the selected model does not
	// support a capability required by the request.
	ErrUnsupportedCapability = errors.New("ollama: unsupported capability")
)

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

func (*APIError) Unwrap added in v1.0.3

func (e *APIError) Unwrap() error

Unwrap returns a stable semantic classification for known Ollama errors. The APIError remains available through errors.As for status and response details, while errors.Is can be used with the exported sentinel errors.

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

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

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

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

List calls GET /api/tags.

func (*ModelService) ListRunning

ListRunning calls GET /api/ps.

func (*ModelService) Pull

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

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

Get calls GET /api/version.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL