Cap local-model Ollama serving envelope in compose

Context

Release classification: boardless production-hardening leaf under #13852; this does not replace the native-Ollama lifecycle work.

Operator cloud-health evidence showed the opt-in local Ollama provider can make the deployment container unhealthy under the current local-model serving envelope. The live code check found ai/deploy/docker-compose.yml sets OLLAMA_CONTEXT_LENGTH=${NEO_LOCAL_MODEL_CONTEXT_LENGTH:-262144} and OLLAMA_KEEP_ALIVE=${NEO_LOCAL_MODEL_KEEP_ALIVE:--1}, but does not expose the matching Ollama serving caps for request parallelism or loaded-model count.

Live latest-open sweep: checked latest 20 open issues at 2026-06-22T12:03:50Z; no equivalent leaf found. Closest related tickets were #13852 (broad native-Ollama lifecycle), #13854 (chat-model parity), and #13853 (MoE/provider JSON schema). A2A in-flight sweep over the latest 30 messages found only this agent's [lane-claim][#13852] cloud local-model Ollama resource caps in compose; no competing peer claim. KB ticket query for OLLAMA_NUM_PARALLEL OLLAMA_MAX_LOADED_MODELS NEO_LOCAL_MODEL_CONTEXT_LENGTH local-model compose returned #13854/#13852/#13853 but no existing compose-cap leaf.

The Problem

The compose profile documents and launches a very large context window without making the serving resource knobs explicit. Upstream Ollama exposes OLLAMA_NUM_PARALLEL, OLLAMA_CONTEXT_LENGTH, and OLLAMA_MAX_LOADED_MODELS; its FAQ documents that parallel request handling multiplies context/RAM requirements, and its env config source defines those environment keys.

That means the local-model profile can look structurally complete while the resource envelope stays implicit. In cloud deployments, implicit serving defaults are not an acceptable contract: the deployment file, operator cookbook, and compose unit test need to encode the cap intentionally.

The Architectural Reality

• ai/deploy/docker-compose.yml owns the opt-in local-model service profile and is the runnable cloud/local-provider substrate.
• learn/agentos/DeploymentCookbook.md is the operator-facing deployment contract for starting and tuning the local-model profile.
• test/playwright/unit/ai/scripts/diagnostics/mcpHealthcheck.spec.mjs already reads the production compose file and asserts the local-model profile contract.
• This is distinct from the parent #13852 lifecycle work: it does not add ollama serve supervision, model preload, or loaded num_ctx verification inside the orchestrator.

The Fix

1. Add explicit local-model compose environment defaults:
   • OLLAMA_NUM_PARALLEL=${NEO_LOCAL_MODEL_NUM_PARALLEL:-1}
   • OLLAMA_MAX_LOADED_MODELS=${NEO_LOCAL_MODEL_MAX_LOADED_MODELS:-2}
2. Mirror those knobs in DeploymentCookbook.md startup examples and environment inventory.
3. Extend the existing compose unit test so the deployment contract cannot silently drop the caps.

Contract Ledger Matrix

Decision Record impact

none. This is deployment-env parity and cookbook/test coverage; it does not change the cloud topology or accepted ADR authority.

Acceptance Criteria

• Compose local-model service exports OLLAMA_NUM_PARALLEL via NEO_LOCAL_MODEL_NUM_PARALLEL with default 1.
• Compose local-model service exports OLLAMA_MAX_LOADED_MODELS via NEO_LOCAL_MODEL_MAX_LOADED_MODELS with default 2.
• Deployment cookbook documents both knobs in the startup example, native Ollama example, resource-pressure guidance, and env inventory.
• Focused unit coverage asserts the compose env contract.

Out of Scope

• Starting or supervising native ollama serve from the orchestrator.
• Preloading models with num_ctx or verifying the loaded context window.
• Changing chat-model selection or provider JSON-schema behavior from #13853/#13854.

Avoided Traps

• Do not close #13852 from this patch. The parent ticket's lifecycle/readiness ACs remain broader than compose env parity.
• Do not add a filesystem or orchestration fallback for unhealthy deployments here. This leaf only makes the runnable provider envelope explicit and test-covered.

Related

Parent: #13852 Related: #13853, #13854

Retrieval Hint: OLLAMA_NUM_PARALLEL OLLAMA_MAX_LOADED_MODELS NEO_LOCAL_MODEL_CONTEXT_LENGTH local-model compose cloud-health