Add a PaddleOCR-VL provider (paddleocr-vl) for images, multi-page TIFF included

Add a paddleocr-vl OCR provider that sends images to a PaddleOCR-VL /layout-parsing service, the same pipeline @happyvertical/pdf uses for PDFs (happyvertical/pdf#142, and the provider: 'paddleocr' reader in happyvertical/pdf#145). With it, a consumer that OCRs bare images through getOCR() (for example @happyvertical/smrt-ingestion's image step, which builds its OCR client in a child process from a provider name and options) can use the same model as its PDF reads.

Scope

getOCR({ provider: 'paddleocr-vl' }) / HAVE_OCR_PROVIDER=paddleocr-vl, plus PaddleOCRVLProvider for direct use.
Request: one POST to {baseUrl}/layout-parsing per image page, with fileType: 1 (image), useLayoutDetection: true and visualize: false. Results are joined in order. No retries.
Formats: PNG and JPEG are sent unchanged. TIFF, WebP, GIF and BMP are converted to PNG with sharp, which is already a dependency. Every page of a multi-page TIFF (a common scanner output) becomes its own request, in page order. Raw pixel buffers (width/height/channels) are encoded through sharp too. Unknown or undecodable input throws OCRProcessingError; it is never silently skipped.
Configuration: providerConfig['paddleocr-vl'] takes { baseUrl, apiKey, timeout }. These fall back to HAVE_OCR_PADDLEOCR_URL / HAVE_OCR_PADDLEOCR_API_KEY / HAVE_OCR_PADDLEOCR_TIMEOUT, then to HAVE_PDF_PADDLEOCR_URL / HAVE_PDF_PADDLEOCR_API_KEY, so one service setting serves both packages. The default timeout is 65 minutes, which covers an on-demand cold start (the same as the pdf client).
Explicit only: the provider is not in the auto priority list, because it sends images to a remote service. Without a base URL, checkDependencies() reports it unavailable. The service itself is not probed, since a proxy /health is not model readiness.
Result: text is the service's Markdown, with tables as HTML. confidence is 100 for any text and 0 otherwise, as with unlimited-ocr. detections has one entry per page. metadata.provider is paddleocr-vl, and metadata.pages gives the page count.
Errors never echo the response body, the request, or document text, because they can contain private data.

Acceptance

Contract tests against a local HTTP stub cover: request shape, PNG/JPEG passthrough, TIFF (multi-page), WebP and raw-pixel conversion, order, env fallbacks, timeout, HTTP and API errors, the service's response-envelope validation, and that it is absent from auto.
README section, generated API docs, changeset (minor), and the coverage gate.

Consumer: teamworksfab/teamworks-os, replacing Unlimited-OCR with PaddleOCR-VL-1.6 (scanner TIFFs and phone photos in document intake).

Claimed by Claude Code (Opus 5.5) · session 76470e05-25d2-4beb-a744-0e470777b27f · branch claude/paddleocr-vl-146 (fork chadtalsma-svg/ocr) · 2026-10-16
Status: implementing. (No triage permission here, so the agent: implementation label could not be added.)

Claimed by Claude Code (Opus 5.5) · session 76470e05-25d2-4beb-a744-0e470777b27f · branch claude/paddleocr-vl-146 (fork chadtalsma-svg/ocr) · 2026-10-16
Status: review — PR #147 at 0b89579. Lint, docs:api:check, typecheck, build, test:coverage (139 tests, gate met) and test:vite-consumer pass. Independent review CLEAN after 2 passes. Next: maintainer workflow approval for the fork PR, required CI, approval and merge, release. Handed off: this session holds no claim.

Claimed by Codex · session 01a14206-ba60-7572-8206-248e9cba339f · branch codex/paddleocr-release · 2026-10-16

Status: released — feature v0.62.0 and final fixes v0.62.1, PRs #148/#150 merged through green CI and queue checks. Publish run 38922815120 succeeded. No remaining action.

Review budget ledger (maintained by hv-review-dispatch; do not edit).

{
  "dispatches": [
    {
      "counted": true,
      "dispatch_id": "native-5495041df368",
      "disposition": "findings",
      "escalation_reason": null,
      "finished_at": "2026-10-16T14:49:00Z",
      "head": "23a88f5236c016d04fe64dfb945632044bff02c9",
      "phase": "final",
      "reconciliation": null,
      "review_base": "0864ba80292b35648d635896a13fd7a843e1299d",
      "review_cycle": "6216801526",
      "review_round": 1,
      "target": "contributor-reported:claude-opus-5-5",
      "total_tokens": null,
      "user_approval": null
    },
    {
      "counted": true,
      "dispatch_id": "native-32a083f24f18",
      "disposition": "clean",
      "escalation_reason": null,
      "finished_at": "2026-10-16T14:49:04Z",
      "head": "0b89579c97220545e70f4b13ab6333fb5f5f8ed6",
      "phase": "recall",
      "reconciliation": null,
      "review_base": "0864ba80292b35648d635896a13fd7a843e1299d",
      "review_cycle": "6216801526",
      "review_round": 2,
      "target": "contributor-reported:claude-opus-5-5",
      "total_tokens": null,
      "user_approval": null
    },
    {
      "counted": true,
      "dispatch_id": "be73a8b3-620f-4002-80ea-c5ae7ff6d140",
      "disposition": "findings",
      "escalation_reason": "Contributor coverage artifacts unavailable; preserve reported rounds and review complete maintained revision.",
      "finished_at": "2026-10-16T14:52:18Z",
      "head": "f4fb66ec3b9247f590ea38ea2be33e7bb7eefe2b",
      "phase": "final",
      "reconciliation": null,
      "review_base": "0864ba80292b35648d635896a13fd7a843e1299d",
      "review_cycle": "6216801526",
      "review_round": 3,
      "target": "claude-opus",
      "total_tokens": 244253,
      "user_approval": null
    },
    {
      "counted": true,
      "dispatch_id": "7f19ee25-84d8-45a7-97fc-e7d362719a33",
      "disposition": "clean",
      "escalation_reason": null,
      "finished_at": "2026-10-16T14:55:15Z",
      "head": "04f9616b5b7c46af7106730d0791a32222164197",
      "phase": "recall",
      "reconciliation": null,
      "review_base": "0864ba80292b35648d635896a13fd7a843e1299d",
      "review_cycle": "6216801526",
      "review_round": 4,
      "target": "claude-opus",
      "total_tokens": 120445,
      "user_approval": null
    },
    {
      "counted": true,
      "dispatch_id": "a98d4d30-cdf3-43f0-b044-b28c4d72084c",
      "disposition": "clean",
      "escalation_reason": null,
      "finished_at": "2026-10-16T15:03:23Z",
      "head": "24f5c973b10cc511d1bbe9f58049c9fd3b29df07",
      "phase": "recall",
      "reconciliation": null,
      "review_base": "0864ba80292b35648d635896a13fd7a843e1299d",
      "review_cycle": "6216801526",
      "review_round": 5,
      "target": "claude-opus",
      "total_tokens": 67608,
      "user_approval": null
    },
    {
      "counted": true,
      "dispatch_id": "26e55c93-fad4-4c55-aa30-5bc8108635f2",
      "disposition": "clean",
      "escalation_reason": null,
      "finished_at": "2026-10-16T15:10:10Z",
      "head": "b851773ac0dcfce38cc32be16de1b49503603906",
      "phase": "recall",
      "reconciliation": null,
      "review_base": "ea837ed0651d07417d8319c1a764272cccb85a19",
      "review_cycle": "6216801526",
      "review_round": 6,
      "target": "claude-opus",
      "total_tokens": 227926,
      "user_approval": null
    }
  ],
  "final_pass_cap": 6,
  "issue": 146,
  "repository": "happyvertical/ocr",
  "schema": "https://happyvertical.com/schemas/review-budget/v1"
}

fix(ocr): validate PaddleOCR image inputs and responses

fix(ocr): preserve blank page detection positions

fix(ocr): orient converted pages and omit unused image assets

Navigation Menu

Repository navigation

Add a PaddleOCR-VL provider (paddleocr-vl) for images, multi-page TIFF included #146

Scope

Acceptance

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add a PaddleOCR-VL provider (paddleocr-vl) for images, multi-page TIFF included #146

Description

Scope

Acceptance

Activity

chadtalsma-svg commented on Oct 16, 2026

chadtalsma-svg commented on Oct 16, 2026

willgriffin commented on Oct 16, 2026

willgriffin commented on Oct 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions