go-ollama/docs/project-specification.md

go-ollama — Project Specification

Module

• Path: gitea.neitzel.de/konrad/go-ollama
• Package: gollama
• Dependency: github.com/ollama/ollama/api (pinned in go.mod)

Thin wrapper around the official Ollama Go API. Adds ergonomic defaults, option builders, and tiered prompt helpers.

Client

client, _ := gollama.FromEnv()                    // OLLAMA_HOST
client, _ := gollama.New("http://localhost:11434")
client, _ := gollama.New(host, gollama.WithDefaultModel("llama3.2"))

Model management

Method	Purpose
ModelNames	Sorted local model names
Models	Local models with metadata
Pull / PullWithProgress	Download/load model
Show	Model details
ModelDefaults	Parse modelfile parameters to OptionSet
Delete	Remove model
RunningModels	Models loaded in memory

Prompt API tiers

Tier	Methods	Use case
1	Complete, CompleteWithSystem, CompleteRaw	Single prompt
2	Chat, ChatWithSystem	One chat turn
3	ChatMessages + User/System/Assistant	History + new message
4	Session.Send	Stateful multi-turn
5	CompleteJSON, ChatJSON	Structured output
6	CompleteStream, ChatStream	Streaming
7	Embed	Embeddings

Options

• NewOptions() / fluent builder (Temperature, NumCtx, Stop, …)
• KnownOptions() — documented option keys
• Precedence: per-call WithOptions > session > client defaults > server

Integration tests

Config load order: env vars → testconfig/local.toml → testconfig/defaults.toml.

Default host: http://debian:11434

go test -tags=integration ./...
OLLAMA_HOST=http://other:11434 go test -tags=integration ./...
GOLLAMA_TEST_PULL=1 go test -tags=integration -run Pull ./...