@effortlessmotion/pdf-to-md 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (189) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +157 -0
  3. package/bin/cli.js +9 -0
  4. package/dist/cjs/analyze.d.cts +35 -0
  5. package/dist/cjs/analyze.d.ts +35 -0
  6. package/dist/cjs/analyze.js +620 -0
  7. package/dist/cjs/analyze.js.map +1 -0
  8. package/dist/cjs/audit.d.cts +38 -0
  9. package/dist/cjs/audit.d.ts +38 -0
  10. package/dist/cjs/audit.js +252 -0
  11. package/dist/cjs/audit.js.map +1 -0
  12. package/dist/cjs/cli/audit.d.cts +3 -0
  13. package/dist/cjs/cli/audit.d.ts +3 -0
  14. package/dist/cjs/cli/audit.js +269 -0
  15. package/dist/cjs/cli/audit.js.map +1 -0
  16. package/dist/cjs/cli/extract.d.cts +3 -0
  17. package/dist/cjs/cli/extract.d.ts +3 -0
  18. package/dist/cjs/cli/extract.js +704 -0
  19. package/dist/cjs/cli/extract.js.map +1 -0
  20. package/dist/cjs/cli/index.d.cts +5 -0
  21. package/dist/cjs/cli/index.d.ts +5 -0
  22. package/dist/cjs/cli/index.js +58 -0
  23. package/dist/cjs/cli/index.js.map +1 -0
  24. package/dist/cjs/cli/render.d.cts +3 -0
  25. package/dist/cjs/cli/render.d.ts +3 -0
  26. package/dist/cjs/cli/render.js +361 -0
  27. package/dist/cjs/cli/render.js.map +1 -0
  28. package/dist/cjs/cli/types.d.cts +10 -0
  29. package/dist/cjs/cli/types.d.ts +10 -0
  30. package/dist/cjs/cli/types.js +7 -0
  31. package/dist/cjs/cli/types.js.map +1 -0
  32. package/dist/cjs/cli.d.cts +2 -0
  33. package/dist/cjs/cli.d.ts +2 -0
  34. package/dist/cjs/cli.js +345 -0
  35. package/dist/cjs/cli.js.map +1 -0
  36. package/dist/cjs/collect.d.cts +6 -0
  37. package/dist/cjs/collect.d.ts +6 -0
  38. package/dist/cjs/collect.js +370 -0
  39. package/dist/cjs/collect.js.map +1 -0
  40. package/dist/cjs/dict.d.cts +8 -0
  41. package/dist/cjs/dict.d.ts +8 -0
  42. package/dist/cjs/dict.js +55 -0
  43. package/dist/cjs/dict.js.map +1 -0
  44. package/dist/cjs/emit.d.cts +27 -0
  45. package/dist/cjs/emit.d.ts +27 -0
  46. package/dist/cjs/emit.js +187 -0
  47. package/dist/cjs/emit.js.map +1 -0
  48. package/dist/cjs/engines/tesseract.d.cts +30 -0
  49. package/dist/cjs/engines/tesseract.d.ts +30 -0
  50. package/dist/cjs/engines/tesseract.js +650 -0
  51. package/dist/cjs/engines/tesseract.js.map +1 -0
  52. package/dist/cjs/errors.d.cts +21 -0
  53. package/dist/cjs/errors.d.ts +21 -0
  54. package/dist/cjs/errors.js +124 -0
  55. package/dist/cjs/errors.js.map +1 -0
  56. package/dist/cjs/extract.d.cts +88 -0
  57. package/dist/cjs/extract.d.ts +88 -0
  58. package/dist/cjs/extract.js +436 -0
  59. package/dist/cjs/extract.js.map +1 -0
  60. package/dist/cjs/geometry.d.cts +63 -0
  61. package/dist/cjs/geometry.d.ts +63 -0
  62. package/dist/cjs/geometry.js +521 -0
  63. package/dist/cjs/geometry.js.map +1 -0
  64. package/dist/cjs/index.d.cts +15 -0
  65. package/dist/cjs/index.d.ts +15 -0
  66. package/dist/cjs/index.js +56 -0
  67. package/dist/cjs/index.js.map +1 -0
  68. package/dist/cjs/lines.d.cts +3 -0
  69. package/dist/cjs/lines.d.ts +3 -0
  70. package/dist/cjs/lines.js +181 -0
  71. package/dist/cjs/lines.js.map +1 -0
  72. package/dist/cjs/markdown.d.cts +2 -0
  73. package/dist/cjs/markdown.d.ts +2 -0
  74. package/dist/cjs/markdown.js +222 -0
  75. package/dist/cjs/markdown.js.map +1 -0
  76. package/dist/cjs/package.json +1 -0
  77. package/dist/cjs/page-marker.d.cts +16 -0
  78. package/dist/cjs/page-marker.d.ts +16 -0
  79. package/dist/cjs/page-marker.js +85 -0
  80. package/dist/cjs/page-marker.js.map +1 -0
  81. package/dist/cjs/pdf-open.d.cts +12 -0
  82. package/dist/cjs/pdf-open.d.ts +12 -0
  83. package/dist/cjs/pdf-open.js +257 -0
  84. package/dist/cjs/pdf-open.js.map +1 -0
  85. package/dist/cjs/raster.d.cts +26 -0
  86. package/dist/cjs/raster.d.ts +26 -0
  87. package/dist/cjs/raster.js +262 -0
  88. package/dist/cjs/raster.js.map +1 -0
  89. package/dist/cjs/render-analysis.d.cts +25 -0
  90. package/dist/cjs/render-analysis.d.ts +25 -0
  91. package/dist/cjs/render-analysis.js +319 -0
  92. package/dist/cjs/render-analysis.js.map +1 -0
  93. package/dist/cjs/report.d.cts +12 -0
  94. package/dist/cjs/report.d.ts +12 -0
  95. package/dist/cjs/report.js +392 -0
  96. package/dist/cjs/report.js.map +1 -0
  97. package/dist/cjs/resolve.d.cts +1 -0
  98. package/dist/cjs/resolve.d.ts +1 -0
  99. package/dist/cjs/resolve.js +18 -0
  100. package/dist/cjs/resolve.js.map +1 -0
  101. package/dist/cjs/types.d.cts +171 -0
  102. package/dist/cjs/types.d.ts +171 -0
  103. package/dist/cjs/types.js +9 -0
  104. package/dist/cjs/types.js.map +1 -0
  105. package/dist/cjs/validate.d.cts +14 -0
  106. package/dist/cjs/validate.d.ts +14 -0
  107. package/dist/cjs/validate.js +96 -0
  108. package/dist/cjs/validate.js.map +1 -0
  109. package/dist/esm/analyze.d.ts +35 -0
  110. package/dist/esm/analyze.js +270 -0
  111. package/dist/esm/analyze.js.map +1 -0
  112. package/dist/esm/audit.d.ts +38 -0
  113. package/dist/esm/audit.js +113 -0
  114. package/dist/esm/audit.js.map +1 -0
  115. package/dist/esm/cli/audit.d.ts +3 -0
  116. package/dist/esm/cli/audit.js +20 -0
  117. package/dist/esm/cli/audit.js.map +1 -0
  118. package/dist/esm/cli/extract.d.ts +3 -0
  119. package/dist/esm/cli/extract.js +313 -0
  120. package/dist/esm/cli/extract.js.map +1 -0
  121. package/dist/esm/cli/index.d.ts +5 -0
  122. package/dist/esm/cli/index.js +7 -0
  123. package/dist/esm/cli/index.js.map +1 -0
  124. package/dist/esm/cli/render.d.ts +3 -0
  125. package/dist/esm/cli/render.js +77 -0
  126. package/dist/esm/cli/render.js.map +1 -0
  127. package/dist/esm/cli/types.d.ts +10 -0
  128. package/dist/esm/cli/types.js +3 -0
  129. package/dist/esm/cli/types.js.map +1 -0
  130. package/dist/esm/cli.d.ts +2 -0
  131. package/dist/esm/cli.js +90 -0
  132. package/dist/esm/cli.js.map +1 -0
  133. package/dist/esm/collect.d.ts +6 -0
  134. package/dist/esm/collect.js +80 -0
  135. package/dist/esm/collect.js.map +1 -0
  136. package/dist/esm/dict.d.ts +8 -0
  137. package/dist/esm/dict.js +28 -0
  138. package/dist/esm/dict.js.map +1 -0
  139. package/dist/esm/emit.d.ts +27 -0
  140. package/dist/esm/emit.js +131 -0
  141. package/dist/esm/emit.js.map +1 -0
  142. package/dist/esm/engines/tesseract.d.ts +30 -0
  143. package/dist/esm/engines/tesseract.js +190 -0
  144. package/dist/esm/engines/tesseract.js.map +1 -0
  145. package/dist/esm/errors.d.ts +21 -0
  146. package/dist/esm/errors.js +9 -0
  147. package/dist/esm/errors.js.map +1 -0
  148. package/dist/esm/extract.d.ts +88 -0
  149. package/dist/esm/extract.js +147 -0
  150. package/dist/esm/extract.js.map +1 -0
  151. package/dist/esm/geometry.d.ts +63 -0
  152. package/dist/esm/geometry.js +279 -0
  153. package/dist/esm/geometry.js.map +1 -0
  154. package/dist/esm/index.d.ts +15 -0
  155. package/dist/esm/index.js +10 -0
  156. package/dist/esm/index.js.map +1 -0
  157. package/dist/esm/lines.d.ts +3 -0
  158. package/dist/esm/lines.js +67 -0
  159. package/dist/esm/lines.js.map +1 -0
  160. package/dist/esm/markdown.d.ts +2 -0
  161. package/dist/esm/markdown.js +153 -0
  162. package/dist/esm/markdown.js.map +1 -0
  163. package/dist/esm/package.json +1 -0
  164. package/dist/esm/page-marker.d.ts +16 -0
  165. package/dist/esm/page-marker.js +40 -0
  166. package/dist/esm/page-marker.js.map +1 -0
  167. package/dist/esm/pdf-open.d.ts +12 -0
  168. package/dist/esm/pdf-open.js +61 -0
  169. package/dist/esm/pdf-open.js.map +1 -0
  170. package/dist/esm/raster.d.ts +26 -0
  171. package/dist/esm/raster.js +60 -0
  172. package/dist/esm/raster.js.map +1 -0
  173. package/dist/esm/render-analysis.d.ts +25 -0
  174. package/dist/esm/render-analysis.js +115 -0
  175. package/dist/esm/render-analysis.js.map +1 -0
  176. package/dist/esm/report.d.ts +12 -0
  177. package/dist/esm/report.js +182 -0
  178. package/dist/esm/report.js.map +1 -0
  179. package/dist/esm/resolve.d.ts +1 -0
  180. package/dist/esm/resolve.js +7 -0
  181. package/dist/esm/resolve.js.map +1 -0
  182. package/dist/esm/types.d.ts +171 -0
  183. package/dist/esm/types.js +6 -0
  184. package/dist/esm/types.js.map +1 -0
  185. package/dist/esm/validate.d.ts +14 -0
  186. package/dist/esm/validate.js +56 -0
  187. package/dist/esm/validate.js.map +1 -0
  188. package/package.json +67 -0
  189. package/skills/pdf-to-md/SKILL.md +102 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Kevin Malakoff
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,157 @@
1
+ # pdf-to-md
2
+
3
+ > Convert PDFs — born-digital or scanned — into markdown you can trust, under an explicit
4
+ > contract: recognized text is never silently lost, unrecoverable structure is marked rather
5
+ > than guessed, and every claim the output makes is mechanically checkable. When the defaults
6
+ > misread your document, you get the measured knobs, the detectors that point at exactly what to
7
+ > distrust, and the raw analysis to converge on a lossless conversion yourself.
8
+
9
+ Pure TypeScript, runs anywhere `npm install` works. No system dependencies, no cloud calls: the
10
+ OCR engine ([tesseract.js](https://www.npmjs.com/package/tesseract.js)) and its recognition model
11
+ install with the package and run fully offline.
12
+
13
+ ```bash
14
+ npm install pdf-to-md
15
+ ```
16
+
17
+ Requires Node >=22.13.0 — below that, the OCR path silently finds no words instead of
18
+ erroring (see Development for the measured reason).
19
+
20
+ ## CLI
21
+
22
+ ```bash
23
+ npx pdf-to-md book.pdf # text layer -> book.md (auto-OCR if pages are images)
24
+ npx pdf-to-md scan.pdf out.md --ocr # force the OCR path
25
+ ```
26
+
27
+ ```
28
+ pdf-to-md <file.pdf> [out.md] [flags...] convert (implicit `extract`)
29
+ pdf-to-md render <file.pdf> <page>[-<page>] render a page to PNG for eyeballing
30
+ pdf-to-md audit <words.jsonl> <file.md> severity-1 check: every recognized word present?
31
+ pdf-to-md --help | --version
32
+ ```
33
+
34
+ Everyday flags: `--ocr`, `--no-ocr`, `--pages N[-M]`, `--stdout`, `--json` (QA report),
35
+ `--format md|txt|raw` (default `md`; `raw` = the full `Analysis` as JSON, report included; `txt` =
36
+ reading-order plain text — line-granular on the text path with no paragraph reflow, block-granular
37
+ on the OCR path), `--debug-words=FILE` (severity-1 audit input, see below), `--dpi=N`
38
+ (OCR render resolution). Usage errors exit 2; runtime errors exit 1.
39
+
40
+ ## Library
41
+
42
+ ```ts
43
+ import { pdfToMarkdown } from 'pdf-to-md';
44
+
45
+ const { markdown, report, warnings } = await pdfToMarkdown('book.pdf');
46
+ ```
47
+
48
+ `pdfToMarkdown` is the headline API: text layer first, falling back to OCR on its own when the
49
+ pages are images of text. For explicit control over which path runs (hybrid pages — a real text
50
+ layer plus a large embedded image — are a class the tool itself flags, and reading both requires
51
+ naming the path), the engine-agnostic word-input seam, and the `analyze`/`toMarkdown`/`toText`
52
+ raw-analysis API described below, every exported function and option is documented at its
53
+ declaration — `extractText`, `extractOcr`, `analyze`, `toMarkdown`, `toText`, `auditWords`,
54
+ `DEFAULT_TUNING`, and the rest — visible in editor hover and in the [API Docs](https://kmalakoff.github.io/pdf-to-md/).
55
+ TSDoc is the source of truth for per-option prose; this file stays a map, not a mirror.
56
+
57
+ All library functions throw a typed `PdfToMdError` (`code: 'PDF_OPEN' | 'PAGE_RANGE' |
58
+ 'PAGE_RENDER' | 'OCR_PAGE_FAILED' | 'WORDS_INPUT' | 'ANALYSIS_INPUT'`) and never write to
59
+ stdout/stderr or exit the process; warnings are returned data (plus an `onWarning` callback for
60
+ streaming them).
61
+
62
+ ## Design contract
63
+
64
+ What this tool promises about errors, in severity order — each with the instrument that enforces it:
65
+
66
+ 1. **Silent text loss is forbidden.** Every word the engine recognizes lands in the output — body,
67
+ heading, or a visible `> [floats]` aside. **Enforced by:** `--debug-words=FILE` dumps every
68
+ recognized word as clean JSON lines (`{page, text, x, y, w, h, confidence?}`); the shipped
69
+ `auditWords()` (or `pdf-to-md audit words.jsonl out.md`) checks the dump against the markdown
70
+ and exits 1 on any loss (`MISSING > 0`) — a first-class part of the product, usable as a CI
71
+ gate, not a path into the source tree.
72
+ 2. **Invisible corruption is minimized and made detectable.** Right-words-wrong-order failures
73
+ (column braiding, mid-sentence splits) are what the geometry works hardest to prevent; a second
74
+ class — right order, WRONG VALUE (an OCR misread spliced into otherwise word-like prose) — is
75
+ what confidence scoring catches. **Enforced by:** `report.danglingLong` (the order-failure
76
+ detector no output-only check can prove), `report.reviewBlocks` (blocks the geometry couldn't
77
+ order, labeled rather than guessed at), and `report.lowConfidenceWords` /
78
+ `pageStats[].lowConfidenceSample` (words the engine itself scored below confidence 60 — see
79
+ `LOW_CONFIDENCE_THRESHOLD`'s test in `test/unit/review-blocks.test.ts` for the measured derivation).
80
+ 3. **Visible misplacement is acceptable.** A fragment in the floats aside, a `> [review: ...]`
81
+ block, or an odd paragraph break is something a caller can see and edit; the two classes above
82
+ are not. **Enforced by:** the `> [floats]` / `> [review: reason]` markers themselves — regular
83
+ enough (`^> \[(floats|review: [^\]]+)\] (.*)$`) for a downstream agent to find and handle
84
+ without guessing — surfaced in `--json` as `report.floats` / `report.reviewBlocks`.
85
+
86
+ The QA report (`--json`) exists to make 2 and 3 reviewable: per-page stats flag suspect pages, and
87
+ `pdf-to-md render` shows you the page as printed — the only real ground truth.
88
+
89
+ **Why there's no `--floats=drop`:** an earlier version offered one, filtering `> [floats]` lines
90
+ out of the output. Measured against a real 100-page document, floats held real sentence tails on
91
+ pages 29, 48, and 94 — "drop" invited exactly the silent loss rule 1 forbids, so the knob was cut.
92
+ Filtering them back out downstream is one line (`^> \[floats\]`) a caller can write when floats
93
+ truly are noise for their document; the tool won't make that call for you.
94
+
95
+ **`closedHyphens` as a cross-check, not a target:** the text path's `report.closedHyphens` counts
96
+ line-final hyphens closed against a dictionary (e.g. "creat-" + "ive" → "creative"). It exists to
97
+ explain the auditor's `strict_deficits` count, not to be optimized directly: a strict deficit is
98
+ usually a hyphen-rejoin firing (a word split across two lines, correctly closed into one), not lost
99
+ text — `MISSING` is the loss signal, and `closedHyphens` is what explains the difference.
100
+
101
+ ## Tuning
102
+
103
+ OCR-path heuristics run on constants measured against real documents — the derivation for each
104
+ lives beside its value in `src/geometry.ts`'s `DEFAULT_TUNING` (the canonical source; typedoc
105
+ renders it). Override per run instead of editing source:
106
+
107
+ | flag | controls | default |
108
+ |---|---|---|
109
+ | `--float-max-words` | fragments with more words than this are body text, not decoration | `3` |
110
+ | `--float-max-width` | fraction of page width above which a fragment is too wide to be decoration | `0.15` |
111
+ | `--float-margin` | how far a fragment's left edge must sit from its column edge to be decoration | `0.008` |
112
+ | `--para-gap` | a vertical gap this many times the line pitch is a paragraph break | `1.6` |
113
+ | `--heading-scale` | lines taller than this times body height are headings | `2.0` |
114
+ | `--col-max-width` | boxes wider than this are excluded from gutter detection | `0.55` |
115
+ | `--col-split` | fractional x of the two-column midpoint | `0.5` |
116
+ | `--line-y-tol` | vertical distance within which two boxes are the same line | `0.006` |
117
+ | `--line-height-ratio` | same-line boxes with a larger height ratio don't merge | `2.4` |
118
+ | `--dpi` | OCR page-render resolution; raise for tiny print or chart/label pages, `>~400` measured worse on ordinary prose pages (`test/unit/sparse-retry.test.ts`) | `288` |
119
+
120
+ **Hybrid pages:** raising `--dpi` fixes chart/label corruption but can make scattered numerals on
121
+ the same page WORSE, not better (measured: a chart page's numerals recognized at `288` dpi, then
122
+ none at `600`, while the page's own text layer already had them all) — `--dpi` is a chart-LABEL
123
+ fix, not a scattered-numeral fix. For hybrid pages, compare (or merge, via `analyze()`) the
124
+ text-layer and OCR readings rather than trusting one dpi setting to fix everything on the page.
125
+
126
+ Typical loop: run with `--json`, find suspect pages in `pageStats`, `pdf-to-md render` them, then
127
+ re-extract just those pages with `--pages` and an adjusted flag — or use `--format=raw` to get the
128
+ full `Analysis` (words + blocks + report) and converge programmatically.
129
+
130
+ ## For AI agents
131
+
132
+ ```bash
133
+ npx skills add kmalakoff/pdf-to-md # -g for global, -a claude-code to target
134
+ ```
135
+
136
+ One skill: `pdf-to-md` for driving the QA loop above (reading `pageStats`, rendering pages as
137
+ ground truth, targeted re-extraction, the severity-1 audit, and the `> [floats]` / `> [review:
138
+ ...]` markers) instead of trusting the first conversion.
139
+
140
+ ## Development
141
+
142
+ ```bash
143
+ npm run build # tsds build -> dist/cjs + dist/esm (pretest step; plain `npm test` builds first)
144
+ npm test # synthetic fixtures (ground truth by construction), a fetched+sha256-pinned
145
+ # public corpus (skips offline), real engine runs, plus self-skipping
146
+ # private-document extras when available locally
147
+ npm run prepublishOnly # tsds validate: build + biome + depcheck + docs
148
+ ```
149
+
150
+ Source is TypeScript; the published package ships a built `dist/` (dual CJS + ESM via `tsds
151
+ build`) because Node's native type-stripping refuses to run `.ts` files once they're under
152
+ `node_modules`. Tests still run directly against source; the CLI test helper spawns the built
153
+ `bin/cli.js`, which is why a build has to happen first.
154
+
155
+ `engines.node` is `>=22.13.0`, measured (not assumed): `pdfjs-dist`'s CJS build needs Node's
156
+ stable synchronous `require(esm)`, and its rendering path uses a V8 `ArrayBuffer` API missing
157
+ before Node 22. Don't lower this floor without re-running that measurement.
package/bin/cli.js ADDED
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+
3
+ // biome-ignore lint/security/noGlobalEval: dual esm and cjs
4
+ if (typeof require === 'undefined') eval("import('../dist/esm/cli.js').then((cli) => cli.default(process.argv.slice(2), 'pdf-to-md')).catch((err) => { console.error(err); process.exit(-1); });");
5
+ else
6
+ require('../dist/cjs/cli.js')(process.argv.slice(2), 'pdf-to-md').catch((err) => {
7
+ console.error(err);
8
+ process.exit(-1);
9
+ });
@@ -0,0 +1,35 @@
1
+ import type { ExtractOcrOptions, ExtractTextOptions, OcrWordInput } from './extract.js';
2
+ import type { Analysis, AnalysisPage } from './types.js';
3
+ /** analyze(pdf) with the default/'text' path — OCR-only fields don't exist
4
+ * on this branch, so passing e.g. `tuning` without `path: 'ocr'` is a compile error. */
5
+ export type AnalyzeTextOptions = ExtractTextOptions & {
6
+ path?: 'text';
7
+ };
8
+ /** analyze(pdf, {path:'ocr'}) — same fields as {@link ExtractOcrOptions},
9
+ * unlocked only once `path: 'ocr'` is set. */
10
+ export type AnalyzeOcrOptions = ExtractOcrOptions & {
11
+ path: 'ocr';
12
+ };
13
+ /** Options for {@link analyze}: which fields type-check depends on `path`
14
+ * (ignored, forced 'ocr', when `input` is a `{ words }` replay). */
15
+ export type AnalyzeOptions = AnalyzeTextOptions | AnalyzeOcrOptions;
16
+ /** The OCR-path core shared by extractOcr and analyze(..., {path:'ocr'}):
17
+ * recognizes (or replays) words and runs the unchanged buildPageOCR/emitPage pipeline. Word IDENTITY (object reference), not value, carries indices through into the emitted blocks — see `geometry.ts`'s OcrLine.words. */
18
+ export declare function buildOcrAnalysisPages(input: {
19
+ pdfPath: string;
20
+ } | {
21
+ words: OcrWordInput[];
22
+ }, opts: ExtractOcrOptions, warn: (m: string) => void): Promise<{
23
+ pages: AnalysisPage[];
24
+ words: OcrWordInput[];
25
+ }>;
26
+ /**
27
+ * Analyze a PDF (or replay an already-recognized OCR word dump) into
28
+ * `Analysis`: plain, JSON-serializable per-page `words`/`blocks` plus the same QA `report` the other entry points return. Render with toMarkdown()/toText(), or hand-edit/splice it (no merge API — see toMarkdown's doc comment).
29
+ *
30
+ * @param input a bare pdf path, or `{ words }` to replay a dump (always analyzed as OCR) — unlike extractOcr, never `{ pdfPath }`
31
+ * @param opts see {@link AnalyzeOptions}; for a pdf path, `opts.path` picks 'text' (default) or 'ocr' — analyze() makes no auto-fallback decision (that's pdfToMarkdown's job)
32
+ */
33
+ export declare function analyze(input: string | {
34
+ words: OcrWordInput[];
35
+ }, opts?: AnalyzeOptions): Promise<Analysis>;
@@ -0,0 +1,35 @@
1
+ import type { ExtractOcrOptions, ExtractTextOptions, OcrWordInput } from './extract.js';
2
+ import type { Analysis, AnalysisPage } from './types.js';
3
+ /** analyze(pdf) with the default/'text' path — OCR-only fields don't exist
4
+ * on this branch, so passing e.g. `tuning` without `path: 'ocr'` is a compile error. */
5
+ export type AnalyzeTextOptions = ExtractTextOptions & {
6
+ path?: 'text';
7
+ };
8
+ /** analyze(pdf, {path:'ocr'}) — same fields as {@link ExtractOcrOptions},
9
+ * unlocked only once `path: 'ocr'` is set. */
10
+ export type AnalyzeOcrOptions = ExtractOcrOptions & {
11
+ path: 'ocr';
12
+ };
13
+ /** Options for {@link analyze}: which fields type-check depends on `path`
14
+ * (ignored, forced 'ocr', when `input` is a `{ words }` replay). */
15
+ export type AnalyzeOptions = AnalyzeTextOptions | AnalyzeOcrOptions;
16
+ /** The OCR-path core shared by extractOcr and analyze(..., {path:'ocr'}):
17
+ * recognizes (or replays) words and runs the unchanged buildPageOCR/emitPage pipeline. Word IDENTITY (object reference), not value, carries indices through into the emitted blocks — see `geometry.ts`'s OcrLine.words. */
18
+ export declare function buildOcrAnalysisPages(input: {
19
+ pdfPath: string;
20
+ } | {
21
+ words: OcrWordInput[];
22
+ }, opts: ExtractOcrOptions, warn: (m: string) => void): Promise<{
23
+ pages: AnalysisPage[];
24
+ words: OcrWordInput[];
25
+ }>;
26
+ /**
27
+ * Analyze a PDF (or replay an already-recognized OCR word dump) into
28
+ * `Analysis`: plain, JSON-serializable per-page `words`/`blocks` plus the same QA `report` the other entry points return. Render with toMarkdown()/toText(), or hand-edit/splice it (no merge API — see toMarkdown's doc comment).
29
+ *
30
+ * @param input a bare pdf path, or `{ words }` to replay a dump (always analyzed as OCR) — unlike extractOcr, never `{ pdfPath }`
31
+ * @param opts see {@link AnalyzeOptions}; for a pdf path, `opts.path` picks 'text' (default) or 'ocr' — analyze() makes no auto-fallback decision (that's pdfToMarkdown's job)
32
+ */
33
+ export declare function analyze(input: string | {
34
+ words: OcrWordInput[];
35
+ }, opts?: AnalyzeOptions): Promise<Analysis>;