feat(ocr): Test-connection action + actionable local-endpoint errors (Ollama/LM Studio) #7
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!7
Loading…
Reference in a new issue
No description provided.
Delete branch "agent/ocr-endpoint-test-connection"
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?
Part of #3 (Part of #2). The code half of #3: make the vision-endpoint path diagnosable so a misconfigured local server tells the user exactly what is wrong instead of silently falling back to image-only.
Red gate (reproduce first)
Today, at import,
src/main.ts:803doesawait this.transcribeStrokes(request).catch(() => null)— every endpoint failure is swallowed and the remark silently comes back image-only, with zero guidance. There is no way for a user to find out why their endpoint produced no text. Confirm this is the current behaviour before changing anything; the Test-connection action is what makes the failure visible.What to build (one focused change)
1. Pure helpers in
src/transport/ocr.ts(testable over the injectedHttpClient)listModels(http, config): Promise<string[]>—GET {endpoint}/models(OpenAI route; Ollama/LM Studio both serve/v1/models). Parse thedata[].idarray. Map failures toTransportErrorwith the same actionable messages as below.checkConnection(http, config): Promise<{ models: string[]; probe: string | null }>(or a small result struct) — orchestrates the Test-connection flow: (a)listModels, (b) assertconfig.modelis present (TransportError "Model "X" is not served by this endpoint — pull it (ollama pull X) or pick one of: …" listing what/modelsreturned), (c) send a tiny probe PNG throughtranscribe()and return its result. Keep a 1×1 (or small) PNG as aconstbase64 → ArrayBuffer in the module.2. Extend error mapping — status codes and network errors
Current
transcribe()only maps HTTP status (401/403→"refused the API key", 404, generic). Two gaps:requestUrl({throw:false})suppresses non-2xx status throws but still rejects on connection refused / DNS / timeout — so a stopped server throws a raw error out oftranscribe(today swallowed by the import.catch). Wrap thehttp(...)call: on a thrown/rejected request, raiseTransportError("Could not reach the OCR endpoint at {endpoint} — is the server running? (connection refused)"). Detect refused/timeout by message where possible but fall back to a generic "could not reach" so no failure is lost.config.apiKeyis set:TransportError("The endpoint refused the request's origin (app://obsidian.md). For Ollama, set OLLAMA_ORIGINS=app://obsidian.md (or *) and restart it. See docs/ocr-endpoint-setup.md.")checkConnectionchecks/modelsfirst, prefer the clearer "model not served / not pulled" message from step 1 when the model is simply absent.Honesty / verification note for the implementer: the exact failure signature of an Ollama origin rejection via Obsidian's
requestUrl(desktoprequestUrlis a Node-side request and may send noOriginheader at all, in which case Ollama does not 403) is not yet empirically confirmed — that uncertainty is the "untested because of setup difficulties" gap itself. So: always surface the raw HTTP status and a short snippet of the response body in the failure message (e.g.… (HTTP 403: <first 200 chars of body>)), and layer the specific hints above on top of known signatures. The raw passthrough guarantees the action is useful even for a signature we did not anticipate; do not rely solely on guessed status codes. Record what you actually observe against a live Ollama in an MR comment.3. "Test connection" action in OCR settings
Add it in
src/settings.ts, not as a new schemacontrol.type. The existingaction:+visible:pattern (seehandwritingActions(), L125–182, and theButtonComponenthelper) already supports exactly this and is the lowest-risk path:SettingDefinitionwithname: "Test connection",descexplaining it pings the endpoint and sends a probe image,visible: () => this.plugin.settings.ocrMode === "endpoint", and anactionthat builds aButtonComponentwhoseonClickrunscheckConnection(obsidianHttp, { endpoint, model, apiKey })and reports vianotify(...): success → "Connected to {model} at {endpoint} — probe read OK." / failure → theTransportError.message.handwritingActions()is spliced ingetSettingDefinitions()(thesection.heading === "Handwriting"branch at L117) — add a parallel branch for the OCR section heading"Reading handwriting (OCR)"returning anocrActions()list.obsidianHttpis currently a module-private const inmain.ts(L2336). Export it (or expose a smallplugin.testOcrConnection()method on the plugin that settings.ts calls, mirroring how handwriting actions callthis.plugin.*). Prefer aplugin.testOcrConnection()method — it keeps theobsidianHttpedge and the{endpoint,model,apiKey}assembly (already done ininkedge.ts:ocr) out of the settings UI.4. Defaults — verify only
settingsmodel.tsL159–164: endpointhttp://localhost:11434/v1, modelqwen2.5vl:7b, examples 3. These are current/good (confirmed). No change expected; only correct if you find the Ollama tag has changed.5. Tests (required by the validation contract)
Add
src/__tests__/ocr.test.tswith a fakeHttpClient:listModelsparsesdata[].id.checkConnectionthrows the model-not-served message whenconfig.modelis absent from/models.OLLAMA_ORIGINS; 403 with apiKey set → "API key" message.Scope boundary (do NOT do here)
docs/ocr-endpoint-setup.md, the README link, and the settings-note mention are the sibling MR (agent/ocr-endpoint-setup-docs, MR !6). This MR only references that doc path in error strings — it does not create it. No ordering dependency: both land independently (a referenced-but-not-yet-merged doc path in an error string is harmless)..catch(() => null)fallback behaviour (silent image-only on failure is intentional for unattended imports); the Test-connection action is the surfacing path. If you want import-time failures logged, log to console only — do not block the import.Validation contract
nix develop -c npx vitest run src/__tests__→ PASS, including the newocr.test.ts. Red first: write the 403-origin and connection-refused assertions, watch them fail against the currenttranscribe, then implement the mapping.qwen2.5vlpulled → Test connection reports success; Ollama stopped → "connection refused / could not reach"; model not pulled → "not served / pull it"; wrong endpoint (no/v1) → 404 route message.✅ Agent run completed
8m27s · 71 turns · $3.56 · pushed
agent/ocr-endpoint-test-connection· session saved — new comments resume this runclaude referenced this pull request2026-10-20 15:18:28 +02:00
claude referenced this pull request2026-10-20 15:21:52 +02:00
What changed
src/transport/ocr.ts— addedlistModels()(GET/models, parsesdata[].id) andcheckConnection()(lists models → assertsconfig.modelis served → sends a 1×1 probe PNG through the realtranscribe()path). Extendedtranscribe()mapping: a rejected request (stopped server / DNS / timeout) now becomesCould not reach … (connection refused)instead of propagating raw; 401/403 branches on whether an API key is set so a local403points atOLLAMA_ORIGINS=app://obsidian.mdwhile a keyed endpoint keeps the "refused the API key" message; every non-2xx now appends the raw(HTTP <status>: <first 200 chars of body>)so an unanticipated signature is still actionable.src/main.ts— exposedplugin.testOcrConnection()over the module-privateobsidianHttp(keeps the edge +{endpoint,model,apiKey}assembly out of the UI).src/settings.ts— "Test connection" action spliced into theReading handwriting (OCR)section via a parallelocrActions()branch (sameaction:/visible:pattern ashandwritingActions()); reports success (Connected to {model} at {endpoint} — probe read OK.) or theTransportError.messagevianotify()..catch(() => null)atmain.ts:803left untouched (silent image-only fallback is intentional; Test connection is the surfacing path). Defaults verified unchanged.Verify
transcribe(403→"refused the API key"; raw rejection propagated), then the mapping was implemented.npx vitest run src/__tests__/ocr.test.ts→ 10 PASS (parse, model-not-served, 403 both ways, raw-status passthrough, connection-refused, opaque-reject, success + NO_TEXT probe).npx vitest run src/__tests__→ 663 PASS;tsc -noEmit -skipLibCheck→ clean;eslinton changed files → clean; productionesbuild+check-bundle.mjs→ clean.upstream-syncscheduled +releaseon tag), so there is no pipeline to gate on — verification rests on the local runs above.Honesty / live-Ollama note
The manual matrix (Ollama running→success, stopped→reachability, model-not-pulled→"not served", no-
/v1→404 route) could not be run — there is no live Ollama in this sandbox. Per the hand-off's verification note, the exact failure signature of an Ollama origin rejection via Obsidian's desktoprequestUrl(which may send noOriginheader, in which case Ollama does not 403) remains empirically unconfirmed. The implementation does not rely on the guessed status alone: it always passes through the raw HTTP status + body snippet, and layers theOLLAMA_ORIGINS/ "model not served" / 404-route hints on top, so the action stays useful even for a signature we did not anticipate. A reviewer with a live Ollama should confirm the 403-origin path end-to-end.Follow-ups
docs/ocr-endpoint-setup.md(referenced by the error strings) is the sibling MR !6 (agent/ocr-endpoint-setup-docs) — no ordering dependency; a referenced-but-unmerged doc path is harmless.claude referenced this pull request2026-10-20 16:34:09 +02:00
claude referenced this pull request2026-10-20 16:34:09 +02:00
claude referenced this pull request2026-10-20 18:57:21 +02:00
claude referenced this pull request2026-10-20 18:57:24 +02:00
claude referenced this pull request2026-10-20 19:02:05 +02:00
claude referenced this pull request2026-10-20 19:02:19 +02:00
claude referenced this pull request2026-10-20 19:02:19 +02:00