---
id: 12285
title: Restore native Ollama local-provider residency parity
state: CLOSED
labels:
  - bug
  - ai
  - regression
  - architecture
  - performance
assignees:
  - neo-gpt
createdAt: '2026-06-01T04:43:30Z'
updatedAt: '2026-06-01T11:28:25Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12285'
author: neo-gpt
commentsCount: 0
parentIssue: 12264
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-06-01T11:28:25Z'
---
# Restore native Ollama local-provider residency parity

## Context

PR #12274 fixed the LM Studio / OpenAI-compatible preload path for #12264 and was merged on 2026-06-01. The operator then raised an out-of-scope parity concern: if OpenAI-compatible local providers now get explicit startup model-residency handling, native `ollama` must not silently fall behind.

Duplicate sweep:
- #12090 delivered the original multi-model coexistence mandate and is closed.
- #12264 remains open for the broader LMS preload/config-SSOT regression.
- No open issue was found for `Ollama residency parity chat embedding`.

## The Problem

Local Agent OS operation needs both configured roles available together: chat for summaries/graph work and embeddings for Memory Core/KB vectors. #12274 improves the OpenAI-compatible/LM Studio lane by actively deriving the required chat + embedding model set and context lengths, then treating preload failures as degraded readiness.

Native Ollama currently has the older coexistence probe/warning behavior, but not an equivalent active readiness/warmup contract. That leaves a provider-parity drift: `openAiCompatible` gets role-aware startup handling, while `ollama` can still look merely reachable even when the chat/embedding residency invariant is not satisfied.

## The Architectural Reality

- `ai/config.template.mjs` exposes `ollama.{model,embeddingModel,keep_alive,requireParallelModels}` and `openAiCompatible.{model,embeddingModel,keep_alive,requireParallelModels}` as parallel local-provider config surfaces.
- `ai/services/graph/ProviderReadinessHelper.mjs` builds the current graph-provider target and checks required chat + embedding model names, but `probeProviderParallelModelCapacity()` is explicitly observability-only and only warns for insufficient Ollama residency.
- `ai/provider/Ollama.mjs` has native chat and embedding routes with `keepAlive: -1`, including native `/api/embed`, but no startup path equivalent to the #12274 OpenAI-compatible preload/degraded-readiness lane.

## The Fix

Add a native Ollama readiness path that preserves provider parity without routing Ollama through LM Studio. The implementation shape is intentionally left to the owner, but it must use native Ollama semantics and keep `ollama`/`openAiCompatible` as equal local-provider choices:

- Resolve chat + embedding role requirements from `aiConfig.ollama` when the selected local roles use native `ollama`.
- Warm, verify, or explicitly fail/degrade both roles using Ollama-native endpoints/options, not `lms load`.
- Surface a degraded readiness state when the configured Ollama chat or embedding model is missing/unusable, rather than only emitting a best-effort warning.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `aiConfig.ollama.model` / `embeddingModel` | `ai/config.template.mjs` | These are required local role models when native Ollama is selected for chat/graph/embedding roles. | Missing values degrade with a clear operator message; no hidden provider default. | Config comments + shared deployment docs. | Unit tests for missing chat and missing embedding roles. |
| Native Ollama readiness helper | `ProviderReadinessHelper.mjs` + `Ollama.mjs` | Startup readiness verifies both configured roles are resident/usable under native Ollama semantics. | If Ollama cannot expose true residency, perform minimal native warmup/probe and report degraded with remediation. | Helper JSDoc. | Tests mock Ollama `/api/ps` and native warmup/probe calls. |
| OpenAI-compatible parity | #12274 / #12264 | OpenAI-compatible remains role-aware; Ollama reaches the same operator contract without LMS-specific commands. | None; parity drift is this ticket's failure condition. | PR/ticket body. | Tests cover both providers side by side. |

## Decision Record Impact

None. This aligns with #12090's local-provider coexistence mandate and #12264's unresolved preload/config-SSOT work; it does not amend an ADR.

## Acceptance Criteria

- [ ] Native `ollama` has an explicit startup/readiness path for configured chat + embedding roles; provider reachability alone is not treated as healthy when either required role is unavailable.
- [ ] The implementation does not invoke `lms` commands for native Ollama.
- [ ] Degraded readiness includes actionable remediation for `OLLAMA_MAX_LOADED_MODELS`, missing model names, or failed native warmup/probe.
- [ ] Tests cover the parity matrix: OpenAI-compatible role-aware preload remains intact; native Ollama resolves its own chat + embedding roles; remote providers are excluded.
- [ ] Tests cover at least one failure case where Ollama can serve one role but not the other.
- [ ] Documentation/config comments explain the equal local-provider invariant: both chat and embedding roles must stay available in parallel.

## Out of Scope

- Retuning `localModels.embedding.*` numeric defaults. That is a separate config-SSOT issue.
- Changing the default provider selection.
- Replacing native Ollama with its OpenAI-compatible surface.

## Avoided Traps

- Do not hide `ollama` behind `openAiCompatible` just because the transport can be compatible. Native Ollama was intentionally wired as an active provider path.
- Do not treat a warning-only probe as parity with active startup readiness.
- Do not mark the local model surface healthy when only one of the two required roles is available.

## Related

- Parent: #12264
- Delivered mandate: #12090
- Merged triggering PR: #12274
- Native Ollama runtime routing: #11965 / #11966

Origin Session ID: d9b4a887-57aa-43aa-8cec-a260ec35ce12

Handoff Retrieval Hints: `Ollama provider readiness parallel model capacity local chat embedding openAiCompatible LMS preload`; `#12274 native Ollama provider parity drift`; `ProviderReadinessHelper probeProviderParallelModelCapacity observability-only`

## Timeline

- 2026-06-01T04:43:31Z @neo-gpt added the `bug` label
- 2026-06-01T04:43:32Z @neo-gpt added the `ai` label
- 2026-06-01T04:43:32Z @neo-gpt added the `regression` label
- 2026-06-01T04:43:32Z @neo-gpt added the `architecture` label
- 2026-06-01T04:43:32Z @neo-gpt added the `performance` label
- 2026-06-01T04:44:00Z @neo-gpt cross-referenced by #12286
- 2026-06-01T04:44:15Z @neo-gpt added parent issue #12264
- 2026-06-01T08:35:49Z @neo-gpt assigned to @neo-gpt
- 2026-06-01T09:29:34Z @neo-gpt cross-referenced by PR #12299
- 2026-06-01T11:28:26Z @tobiu referenced in commit `c6dd402` - "fix(ai): restore ollama residency readiness (#12285) (#12299)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-06-01T11:28:26Z @tobiu closed this issue
- 2026-06-01T12:53:51Z @neo-gpt cross-referenced by #12264

