docs(ocr): bundled setup guide for the local vision endpoint (Ollama/LM Studio) #6

Merged
daniel merged 2 commits from agent/ocr-endpoint-setup-docs into main 2026-10-20 15:25:31 +02:00
Collaborator

Part of #3 (Part of #2). Docs-only, zero code risk — safe to land first.

What to do

Add a bundled setup guide that removes the first-read friction for the vision-model endpoint path, and link it from the two places a user looks.

1. New file docs/ocr-endpoint-setup.md

Sibling to the existing docs/ocr-corrections.md (match its tone — calm, second-person, concrete commands). Cover, in this order:

  • What this is / local-first note. The endpoint path sends only the cropped remark images to a model you run; with Ollama/LM Studio the ink never leaves your machine. It is an HTTP call to a local server, not a cloud API.
  • Ollama, step by step:
    • Install Ollama, then ollama pull qwen2.5vl:7b (the plugin's default model).
    • The one gotcha — origin/CORS. A local Ollama rejects requests whose Origin is Obsidian's app://obsidian.md unless you allow it. Set OLLAMA_ORIGINS=app://obsidian.md (or OLLAMA_ORIGINS=* for any origin) in Ollama's environment, then restart Ollama. Show how to set it per-OS: macOS launchctl setenv OLLAMA_ORIGINS "app://obsidian.md" (then restart the app); Linux systemd systemctl edit ollama.service → Environment="OLLAMA_ORIGINS=app://obsidian.md"; Windows via Edit the system environment variables. Mention OLLAMA_HOST only if the server must listen on a non-default address (e.g. a server on the LAN); for localhost the default 127.0.0.1:11434 is fine.
    • In the plugin: Settings → Reading handwriting (OCR) → Read handwriting with → Vision model endpoint, Endpoint http://localhost:11434/v1, Model qwen2.5vl:7b, API key empty.
    • Verify: use the Test connection action in settings (added by the sibling MR on branch agent/ocr-endpoint-test-connection) — or, as a fallback that works today, curl http://localhost:11434/v1/models to confirm the server answers and the model is listed.
  • LM Studio equivalent: download a vision model (e.g. a Qwen2.5-VL GGUF), start the local server (default http://localhost:1234/v1), enable the OpenAI-compatible server, use that endpoint + the model id LM Studio shows. Note LM Studio does not need an origin allowlist the way Ollama does.
  • Troubleshooting table mapping symptom → fix: connection refused (server not running / wrong port), 403 / forbidden (origin not allowed → OLLAMA_ORIGINS), 404 on /v1/chat/completions (endpoint missing the /v1 suffix, or not an OpenAI-compatible route), model not found (not pulled → ollama pull …, or wrong tag).

In README.md, in the OCR section at the Vision model endpoint bullet (~L171), add a sentence/link: "First time? See the endpoint setup guide."

In src/settingschema.ts, the "Reading handwriting (OCR)" section note (L397–405) ends describing the vision endpoint. Append one short sentence pointing to the guide, e.g. "First-time endpoint setup (Ollama/LM Studio): see docs/ocr-endpoint-setup.md." Keep it a plain-text mention (the note renders as text, so a bare relative path is fine — do not invent a markdown link control).

Why

Issue #2 reports the endpoint path is "untested because of setup difficulties." The dominant blocker is the Ollama origin/CORS allowlist, which is invisible until a request silently fails. A bundled guide is the lowest-risk half of #3 and gives users a path to a first successful read.

Scope boundary (do NOT do here)

  • No code/behaviour changes beyond the two one-line link additions (README + settings note string). The Test connection action, the transcribe() error-mapping, and the new ocr.ts helpers are the sibling MR on agent/ocr-endpoint-test-connection — do not implement them here.
  • Do not touch the built-in reader or WritePad.

Validation contract

  • nix develop -c npx vitest run src/__tests__ → PASS. The settings-note change is a plain string edit; settingschema.test.ts asserts schema keys/visibility, not note text, so it stays green. Confirm no snapshot test pins the note string (grep the tests for a fragment of the note before/after).
  • Visual: the new doc renders, and both links resolve to docs/ocr-endpoint-setup.md.
Part of #3 (Part of #2). **Docs-only, zero code risk — safe to land first.** ## What to do Add a bundled setup guide that removes the first-read friction for the vision-model endpoint path, and link it from the two places a user looks. ### 1. New file `docs/ocr-endpoint-setup.md` Sibling to the existing `docs/ocr-corrections.md` (match its tone — calm, second-person, concrete commands). Cover, in this order: - **What this is / local-first note.** The endpoint path sends only the cropped remark images to a model *you* run; with Ollama/LM Studio the ink never leaves your machine. It is an HTTP call to a local server, not a cloud API. - **Ollama, step by step:** - Install Ollama, then `ollama pull qwen2.5vl:7b` (the plugin's default model). - **The one gotcha — origin/CORS.** A local Ollama rejects requests whose `Origin` is Obsidian's `app://obsidian.md` unless you allow it. Set `OLLAMA_ORIGINS=app://obsidian.md` (or `OLLAMA_ORIGINS=*` for any origin) in Ollama's environment, then restart Ollama. Show how to set it per-OS: macOS `launchctl setenv OLLAMA_ORIGINS "app://obsidian.md"` (then restart the app); Linux systemd `systemctl edit ollama.service` → `Environment="OLLAMA_ORIGINS=app://obsidian.md"`; Windows via *Edit the system environment variables*. Mention `OLLAMA_HOST` only if the server must listen on a non-default address (e.g. a server on the LAN); for localhost the default `127.0.0.1:11434` is fine. - In the plugin: *Settings → Reading handwriting (OCR) → Read handwriting with → Vision model endpoint*, Endpoint `http://localhost:11434/v1`, Model `qwen2.5vl:7b`, API key empty. - **Verify:** use the *Test connection* action in settings (added by the sibling MR on branch `agent/ocr-endpoint-test-connection`) — or, as a fallback that works today, `curl http://localhost:11434/v1/models` to confirm the server answers and the model is listed. - **LM Studio equivalent:** download a vision model (e.g. a Qwen2.5-VL GGUF), start the local server (default `http://localhost:1234/v1`), enable the OpenAI-compatible server, use that endpoint + the model id LM Studio shows. Note LM Studio does not need an origin allowlist the way Ollama does. - **Troubleshooting table** mapping symptom → fix: *connection refused* (server not running / wrong port), *403 / forbidden* (origin not allowed → `OLLAMA_ORIGINS`), *404 on /v1/chat/completions* (endpoint missing the `/v1` suffix, or not an OpenAI-compatible route), *model not found* (not pulled → `ollama pull …`, or wrong tag). ### 2. Link it from the README In `README.md`, in the OCR section at the **Vision model endpoint** bullet (~L171), add a sentence/link: *"First time? See the [endpoint setup guide](docs/ocr-endpoint-setup.md)."* ### 3. Link it from the settings note In `src/settingschema.ts`, the "Reading handwriting (OCR)" section `note` (L397–405) ends describing the vision endpoint. Append one short sentence pointing to the guide, e.g. *"First-time endpoint setup (Ollama/LM Studio): see docs/ocr-endpoint-setup.md."* Keep it a plain-text mention (the note renders as text, so a bare relative path is fine — do not invent a markdown link control). ## Why Issue #2 reports the endpoint path is *"untested because of setup difficulties."* The dominant blocker is the Ollama origin/CORS allowlist, which is invisible until a request silently fails. A bundled guide is the lowest-risk half of #3 and gives users a path to a first successful read. ## Scope boundary (do NOT do here) - No code/behaviour changes beyond the two one-line link additions (README + settings note string). The *Test connection* action, the `transcribe()` error-mapping, and the new `ocr.ts` helpers are the **sibling MR** on `agent/ocr-endpoint-test-connection` — do not implement them here. - Do not touch the built-in reader or WritePad. ## Validation contract - `nix develop -c npx vitest run src/__tests__` → PASS. The settings-note change is a plain string edit; `settingschema.test.ts` asserts schema keys/visibility, not note text, so it stays green. Confirm no snapshot test pins the note string (grep the tests for a fragment of the note before/after). - Visual: the new doc renders, and both links resolve to `docs/ocr-endpoint-setup.md`.
claude self-assigned this 2026-10-20 15:16:25 +02:00
Hand-off stub for issue #3 (docs MR). See MR description.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
Author
Collaborator

✅ Agent run completed

2m54s · 21 turns · $1.25 · pushed agent/ocr-endpoint-setup-docs · session saved — new comments resume this run

✅ **Agent run completed** _2m54s · 21 turns · $1.25 · pushed `agent/ocr-endpoint-setup-docs` · session saved — new comments resume this run_
Author
Collaborator

What changed

  • Added docs/ocr-endpoint-setup.md — first-time setup guide for the vision-model endpoint: local-first note, Ollama step-by-step (pull qwen2.5vl:7b, the per-OS OLLAMA_ORIGINS origin/CORS gotcha, plugin settings, verify), LM Studio equivalent, and a symptom→fix troubleshooting table.
  • README.md (Vision model endpoint bullet) and the "Reading handwriting (OCR)" settings note in src/settingschema.ts each gained one line pointing to the guide. No behaviour change — the note edit is a plain-string append (renders as text, bare relative path as instructed).

Verify

npx vitest run src/__tests__ → 653 pass / 0 fail; tsc -noEmit -skipLibCheck → clean. Confirmed no snapshot test pins the note string (grepped src/__tests__ for note fragments — no match). No pipeline has run for the head SHA yet; the only recent CI run is a pre-existing failure on main, unrelated to this diff.

Follow-ups

  • The Test connection action, transcribe() error-mapping, and ocr.ts helpers are intentionally out of scope here — they land in the sibling MR on agent/ocr-endpoint-test-connection. The guide references Test connection as the primary verify step with a curl .../v1/models fallback that works today.
## What changed - Added `docs/ocr-endpoint-setup.md` — first-time setup guide for the vision-model endpoint: local-first note, Ollama step-by-step (pull `qwen2.5vl:7b`, the per-OS `OLLAMA_ORIGINS` origin/CORS gotcha, plugin settings, verify), LM Studio equivalent, and a symptom→fix troubleshooting table. - `README.md` (Vision model endpoint bullet) and the "Reading handwriting (OCR)" settings `note` in `src/settingschema.ts` each gained one line pointing to the guide. No behaviour change — the note edit is a plain-string append (renders as text, bare relative path as instructed). ## Verify `npx vitest run src/__tests__` → 653 pass / 0 fail; `tsc -noEmit -skipLibCheck` → clean. Confirmed no snapshot test pins the note string (grepped `src/__tests__` for note fragments — no match). No pipeline has run for the head SHA yet; the only recent CI run is a pre-existing `failure` on `main`, unrelated to this diff. ## Follow-ups - The *Test connection* action, `transcribe()` error-mapping, and `ocr.ts` helpers are intentionally **out of scope** here — they land in the sibling MR on `agent/ocr-endpoint-test-connection`. The guide references *Test connection* as the primary verify step with a `curl .../v1/models` fallback that works today.
daniel merged commit def61aa83c into main 2026-10-20 15:25:31 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
daniel/obsidian-remarkable-round-trip!6
No description provided.