feat(ocr): one-click "Set up local reading for me" — detect Ollama, pull the model over HTTP with progress, fill settings (desktop) #27
No reviewers
Labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
daniel/obsidian-remarkable-round-trip!27
Loading…
Reference in a new issue
No description provided.
Delete branch "agent/ollama-managed-setup"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #26. Part of #8 (managed local engine). This is a hand-off: the branch is a stub at
main, and the implementation agent writes everything below.Goal
Add a desktop-only settings action, "Set up local reading for me", under Settings → Reading handwriting (OCR). It turns the manual Ollama setup in
docs/ocr-endpoint-setup.mdinto a single click:The manual endpoint settings remain for advanced users.
Why this approach (decisions already made, do not reopen)
No
child_process/ no shelling out toollama. On #8, @daniel said "calling ollama is acceptable, but direct download would be preferred, model download at runtime is also fine". Ollama's native API does everything the CLI would do:GET /api/versionis the installed-and-running probe.GET /api/tagslists local models.POST /api/pull {"model": "...", "stream": true}streams NDJSON progress lines{status, digest?, total?, completed?}. It ends with{"status":"success"}, or with a line containing{"error": "..."}.This keeps us clear of
require("child_process"), whichscripts/check-bundle.mjsrejects (N7, mobile).Progress needs streaming, and
requestUrlcannot stream.obsidianHttp(src/main.ts:2366) wrapsrequestUrl, which buffers the whole response. The pull therefore goes through a small injected NDJSON streaming client. On desktop it is implemented with Nodehttp/https, reached lazily viawindow.requireand gated byPlatform.isDesktopApp. Node http from the renderer sends noOrigin: app://obsidian.md, so the pull works even beforeOLLAMA_ORIGINSis set.require("http")import. Do not touch the forbidden list inscripts/check-bundle.mjs.window.requireis unavailable: pull withobsidianHttpandstream:false, showing an indeterminate "Downloading… (this can take a long time)" message.Mobile stays untouched.
manifest.jsonhasisDesktopOnly: false. The action is hidden unlessPlatform.isDesktopApp, and nothing Node-ish is evaluated at module load.The download is never silent. A confirmation modal states the model name and approximate size (~6 GB) before any pull starts.
Out of scope here:
OLLAMA_ORIGINSautomatically.Both are in the follow-up child issue of #8, which is blocked by #26. This MR only links to the installer and explains the origin step when Test connection reports the 403.
What to change
1.
src/transport/ollama.ts(new, pure, no Obsidian imports, likesrc/transport/ocr.ts)ollamaBase(endpoint: string): string: derive the server root from an OCR endpoint. Strip trailing/and a trailing/v1.http://localhost:11434/v1→http://localhost:11434.detectOllama(http: HttpClient, base): Promise<{ running: true; version: string } | { running: false; reason: string }>:GET {base}/api/version.running: false. Use the same refusal detection style assend()inocr.ts.listLocalModels(http, base): Promise<string[]>:GET {base}/api/tags, returningmodels[].name. A non-200 or malformed body throwsTransportError.hasModel(names: string[], model: string): boolean: treatxandx:latestas equal.type NdjsonClient = (request: HttpRequest, onLine: (line: string) => void, signal?: AbortSignal) => Promise<{ status: number; text: string }>. Put it next toHttpClientinsrc/transport/http.tsor inollama.ts; the implementer's choice.createLineSplitter(onLine): a pure helper that takes arbitrary string chunks and emits complete, non-empty lines, holding partial lines across chunk boundaries, with aflush(). The desktop adapter uses it. Unit-test it directly.pullModel(stream: NdjsonClient, base, model, onProgress: (p: { status: string; completed: number; total: number }) => void, signal?): Promise<void>:{model, stream: true}.completed/totalperdigest, so the multi-layer download reports one overall byte count.status === "success".TransportErroron anerrorline, on a non-200 status, or if the stream ends withoutsuccess.2. Desktop NDJSON adapter in
src/main.ts(next toobsidianHttp)desktopNdjson: NdjsonClient | null. It is built lazily and only whenPlatform.isDesktopApp, from(window as unknown as { require?: (m: string) => unknown }).require, pickinghttporhttpsby URL scheme.res.on("data")chunks (utf8) intocreateLineSplitter.AbortSignal(req.destroy()).anyif lint forbids it.setUpLocalOllama(ui), or keep the flow in the settings tab; the implementer's choice. Keep transport logic inollama.ts.3. Settings action in
src/settings.ts→ocrActions()(currently L186-211; follow the Test-connection button pattern)New entry "Set up local reading for me":
visible: () => Platform.isDesktopApp, in every OCR mode.Flow:
detectOllama(obsidianHttp, "http://localhost:11434"). This always targets the local default; it does not reuse a custom remote endpoint.https://ollama.com/downloadviawindow.open. Stop.settings.ocrModelif non-empty, elseDEFAULT_SETTINGS.ocrModel(qwen2.5vl:7b). Check it withlistLocalModelsandhasModel. If it is present, skip to step 4.Modal: "Download qwen2.5vl:7b (about 6 GB) into Ollama on this computer? It can take a while; you can cancel and resume later." The buttons are Download (cta) and Cancel.Downloading qwen2.5vl:7b — 1.2 / 5.9 GB (20%). Show the status text whentotalis 0.AbortController. Ollama resumes partial pulls on the next attempt; say so in the cancelled message.notify(message, 15000).ocrEndpoint = "http://localhost:11434/v1",ocrModel = <model>andocrMode = "endpoint". ThensaveSettings()and re-render (this.update()/display()as the existing buttons do).await this.plugin.testOcrConnection().TransportError, show its message (15 s). The existingmapStatus()inocr.tsalready turns a key-less 403 into theOLLAMA_ORIGINS=app://obsidian.mdhint. Append: "See the setup guide: docs/ocr-endpoint-setup.md → step 2."4. Docs
docs/ocr-endpoint-setup.md, add a short "One-click setup (desktop)" section before "Ollama, step by step". It describes the button, says the manual steps remain the fallback and the advanced path, and notes that the origin step (2) may still be needed.Tests:
src/__tests__/ollama.test.ts(new; fakeHttpClientas insrc/__tests__/ocr.test.ts)ollamaBase:/v1, trailing slash, and no-suffix cases.detectOllama:{"version":"0.6.0"}→ running.ECONNREFUSED) → not running.listLocalModelsandhasModel, including the:latestequivalence and a malformed body →TransportError.createLineSplitter: a JSON line split across 3 chunks, multiple lines in one chunk, a trailing line emitted onflush().pullModelwith a fakeNdjsonClientemitting a scripted line sequence:completed/total;success→ resolves;{"error":"pull model manifest: file does not exist"}line → rejects with that message;success→ rejects;Scope boundary (NOT in this MR)
OLLAMA_ORIGINS(launchctl, systemd, setx).These belong to the follow-up child issue of #8, which is gated on #26. This MR also does not change
ocr.tserror mapping, the built-in reader (#4) or in-process reader R&D (#5).Validation contract
There is no
flake.nix, so use nixpkgs node:nix shell nixpkgs#nodejs_22 -c <cmd>(runnpm cifirst).npx vitest run src/__tests__/ollama.test.tsfails, because the module and tests do not exist onmain. After the change it passes.npm testpasses in full (no regressions inocr.test.ts/settingschema.test.ts).npm run buildexits 0. This coverstsc, the esbuild production build andscripts/check-bundle.mjs, so it proves no forbidden Node builtinrequire(...)reachedmain.js.grep -c 'require("child_process")' main.js→ 0. Then confirm the lazy lookup really is lazy:grep -n 'window.require\|\.require' main.jsshows it only inside the adapter factory.npm run lintexits 0.http://localhost:11434/v1andqwen2.5vl:7b, and Test connection runs.🤖 Generated with Claude Code
✅ Agent run completed
1m38s · 10 turns · $2.03 · pushed
agent/ollama-managed-setup· session saved — new comments resume this run⚠️ Verification gate not satisfied: awaiting intent review. Outcome parked — not marked done.
claude referenced this pull request2026-10-20 19:02:19 +02:00
claude referenced this pull request2026-10-20 19:02:19 +02:00
What changed
src/transport/ollama.ts(new, no Obsidian imports):ollamaBase,detectOllama,listLocalModels,hasModel(treatsxandx:latestas the same model),createLineSplitter, andpullModel, which sums progress across layers and resolves onsuccess. It throwsTransportErroron an error line, a non-200 status, a stream that ends withoutsuccess, or a cancel. AlsopullModelBuffered(thestream:falsefallback) anddescribePull(Downloading qwen2.5vl:7b — 1.2 / 5.9 GB (20%)).src/transport/nodestream.ts(nodeNdjson(require), structural Node types, no imports).desktopNdjson()inmain.tsgates it onPlatform.isDesktopAppand passeswindow.require. It picks http or https per URL, feeds utf8 chunks into the line splitter, andreq.destroy()s on abort.main.ts(the hand-off put it there) so it can be tested against a real HTTP server.src/ollamasetup.ts, wired intoocrActions(), desktop only, every OCR mode):ocrMode = endpoint, saves, re-renders and runs Test connection.docs/ocr-endpoint-setup.md, a line in the README, and aCHANGELOG-INK.mdentry.Decisions to check:
TransportErrorfrom the post-setup Test connection, as the spec says.requestUrlfallback can't be cancelled. Closing its modal tells the user that Ollama keeps downloading in the background.Verify
Run locally with the system node:
npm test: 723/723 pass, including the newollama.test.ts(red before the module existed) andnodestream.test.ts.nodestream.test.tsruns a real local server: chunks split mid-JSON, noOriginheader, a non-200 body, abort mid-download (the server sees the socket close) and connection refused.npm run buildandnpm run lintexit 0.grep -c 'require("child_process")' main.jsgives 0, andwindow.requireappears once, insidedesktopNdjson().require("child_process")in a copy ofmain.jsmakescheck-bundleexit 1.No CI pipeline has run on this branch. I had no Ollama or Obsidian desktop, so the manual desktop check has not been done.
Follow-ups
OLLAMA_ORIGINSautomatically, the per-OS installer, and LM Studio stay in the #8 follow-up child, which is blocked by #26.nix shell nixpkgs#nodejs_22, vitest fails at startup because the glibc node can't load rolldown's musl binding on this Alpine runner. The systemnodeworks.Since my last update: I merged
origin/maininto the branch to clear the conflict, and pushed it as merge commit6db5bc5. The only conflict was inCHANGELOG-INK.md, where both sides had added an Unreleased entry, so I kept both. After the merge, locally:npm testpasses all 742 tests in 64 files,npm run buildandnpm run lintexit 0,main.jsstill has norequire("child_process"), andwindow.requirestill appears only insidedesktopNdjson(). No CI pipeline has run on this branch yet.✅ Agent run completed
2m8s · 16 turns · $0.47
Acceptance-intent assessment
#26 asks for a desktop-only "Set up local reading for me" action that does five things: detect Ollama, list its models, pull
qwen2.5vl:7bover the HTTP API with progress after explicit consent, fill the endpoint settings, and run Test connection. When Ollama is absent it should offer an installer link and "Check again". The diff delivers all of it, along with the more detailed hand-off spec in the MR description (puretransport/ollama.ts, lazywindow.requireadapter,stream:falsefallback, docs, tests). I re-ran the validation contract on6db5bc5:ollama.test.tsandnodestream.test.ts: 29/29 pass.npm test: 742/742 pass in 64 files.npm run buildexits 0, andcheck-bundlereports "no Node builtins".npm run lintexits 0.main.jscontains 0require("child_process"), andwindow.requireappears exactly once, insidedesktopNdjson()behindPlatform.isDesktopApp.Criteria
#26 scope
ocrActions()gains "Set up local reading for me" withvisible: () => Platform.isDesktopAppand no mode gate. The description text matches the spec.GET /api/version.detectOllamaalways probeshttp://localhost:11434. Throws and non-200 responses giverunning:false, using the same refusal regex style asocr.ts.GET /api/tags.listLocalModelsreturnsmodels[].name. A non-200 or malformed body throwsTransportError.hasModeltreatsxandx:latestas equal.OllamaPullModalasks "Download qwen2.5vl:7b (about 6 GB) into Ollama on this computer? …" with Download (cta) and Cancel. Nothing is pulled before the click. The issue said ~5 GB; the MR spec's ~6 GB is used.POST /api/pullwith NDJSON progress, no shelling out.pullModelPOSTs{model, stream:true}and sumscompleted/totalper digest.successand throwsTransportErroron an error line, a non-200 status, or a stream that ends withoutsuccess.Downloading … — x / y GB (n%), falling back to the status text when the total is 0.AbortController, and the cancelled message says the download resumes.child_processreaches the bundle (verified).ocrEndpoint = http://localhost:11434/v1,ocrModelandocrMode = "endpoint", then callssaveSettings()and re-renders.testOcrConnection(). On success it shows a notice; on aTransportErrorit shows a 15 s notice with the "docs/ocr-endpoint-setup.md → step 2" suffix.OllamaMissingModalshows the spec's text, a button that runswindow.open("https://ollama.com/download"), and "Check again", which re-runs the flow.MR hand-off spec
transport/nodestream.ts(its own imports are type-only Node shapes pluscreateLineSplitterfromollama.ts, nothing from Node or Obsidian). It is reached only throughdesktopNdjson()inmain.ts, which is gated onPlatform.isDesktopAppand uses the lazywindow.require.httporhttpsby URL scheme, feeds utf8 chunks intocreateLineSplitter, and callsreq.destroy()on abort.main.tsitself. Moving it out is a disclosed placement change that keeps the intent: nothing Node-ish is evaluated at module load.window.requireis unavailable.pullModelBufferedpulls withstream:falsewhile the modal shows an indeterminate "Downloading… (this can take a long time)".docs/ocr-endpoint-setup.mdgains a "One-click setup (desktop)" section before "Ollama, step by step". It says the manual steps remain the fallback and that step 2 (OLLAMA_ORIGINS) may still be needed. The README "Vision model endpoint" bullet gains a one-line mention.ollama.test.tscovers every case the spec lists:ollamaBase:/v1, trailing slash, no suffix;detectOllama: 200, refused, 404;:latest, plus a malformed body;pullModel: digest aggregation, success, error line, no success, non-200.OLLAMA_ORIGINS, no installer is downloaded, there is no LM Studio support, andocr.tserror mapping is unchanged.Not verified: the manual desktop check (Ollama + Obsidian), which the contract marks optional, has not been run. No CI pipeline has run on the branch.
Verdict
Approved
claude referenced this pull request2026-10-20 19:57:23 +02:00
claude referenced this pull request2026-10-20 19:57:30 +02:00
claude referenced this pull request2026-10-20 20:06:44 +02:00
claude referenced this pull request2026-10-20 20:06:45 +02:00