ollama/ollama

Start with AGENTS.md and docs/development.md. Build Go-only via `go build .`/`go run . serve`; full builds need CMake (native payload under build/lib/ollama). Tests: `go test ./...` (race: `go test -race ./...`), vitest under app/ui/app, integration/ needs a live server. Read cmd/cmd.go, server/routes.go, server/sched.go, llm/llama_server.go first. Traps: dual runner paths (GGUF subprocess vs MLX self-runner), removed features that still error loudly, scheduler panics, and env-var-driven behavior.

• Authoritative onboarding docs: AGENTS.md (build commands), docs/development.md (prereqs, GPU backends, platform notes), docs/api.md (REST reference)
  AGENTS.mddocs/development.mddocs/api.md
• Read-first files for server changes: cmd/cmd.go (CLI+RunServer), server/routes.go (GenerateRoutes + handlers), server/sched.go (Scheduler lifecycle), server/images.go (Model + pull/create/prune), llm/llama_server.go (runner subprocess)
  cmd/cmd.goserver/routes.goserver/sched.goserver/images.gollm/llama_server.go
• Shared types live in api/types.go and are the contract between CLI client, server handlers, and the generated TypeScript (checked by api/types_typescript_test.go) — change them carefully
  api/types.goapi/client.go#L1-L14api/types_typescript_test.go
• Model support additions typically touch four places: model/parsers (output), model/renderers (prompt), template/ (named .gotmpl), and server/images.go capability/template selection — plus create/ for safetensors architectures (inferred)
  model/parsers/parsers.gomodel/renderers/renderer.gotemplate/index.jsonserver/images.go#L362-L432
• Safe edit boundaries: middleware/ translators and model/{parsers,renderers} are well-isolated and heavily tested; sched.go and llm/llama_server.go are high-blast-radius (concurrency + subprocess lifecycle) — add tests in the same package's *_test.go (inferred)
  server/sched.gollm/llama_server.goserver/sched_test.go
• Known traps: (a) LoRA adapters and typical_p are removed and error on use; (b) NumGPU==-1 means auto, 0 means CPU-only — don't collapse; (c) num_ctx auto-detection is VRAM-tiered (numCtxAuto flag) and OOM retry reduces it once; (d) scheduler model keys join shard paths with NUL
  cmd/cmd.go#L292-L296llm/llama_server.go#L404-L411server/sched.go#L43-L49server/sched.go#L111-L120
• Environment knobs for debugging: OLLAMA_DEBUG=1 (log level), OLLAMA_DEBUG_LOG_REQUESTS (request replay logs to temp dir), OLLAMA_LOAD_TIMEOUT (stall detection), OLLAMA_NOPRUNE (disable startup deletion), OLLAMA_HOST/OLLAMA_MODELS (paths/bind)
  envconfig/config.go#L201-L240envconfig/config.go#L315-L340server/inference_request_log.go
• Test commands: `go test -count=1 ./...` locally (some packages need CGO/native payload), `go test -race ./...` mirrors CI race job, `npm test`/`npm run build` under app/ui/app; integration tests are opt-in (need pulled models + running server)
  .github/workflows/test.yaml#L451-L501integration/README.mdapp/ui/app/package.json
• Platform-conditional code uses file-suffix build tags (llm_linux.go, llm_darwin.go, llm_windows.go, editor_unix.go, start_darwin.go) — edit the right variant and keep signatures identical across OSes
  llm/llm_linux.gollm/llm_darwin.gocmd/editor_unix.gocmd/start_darwin.go
• Gin runs in DebugMode by default (mode var = gin.DebugMode with a defensive switch); don't rely on release-mode assumptions in handlers
  server/routes.go#L95-L114
• The repo mixes vendored native code (llama/ llama.cpp fork, mlx/) with Go; changes under llama/server or cmake/ trigger the `patches` CI job verifying patches apply — avoid touching unless intentional
  .github/workflows/test.yaml#L35-L80LLAMA_CPP_VERSIONMLX_VERSION
• Progress reporting convention: long operations (pull/create/push) emit api.ProgressResponse structs over a channel consumed by streamResponse — new streaming endpoints should reuse that pattern
  server/routes.go#L1161-L1193server/download.go#L446-L476