# 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

```go
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`

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