Reading scans, PDFs and recordings

Reading scans, PDFs and recordings

Call plank_extract with the file's path. It returns a .md file with one ## Page N heading per page (## Audio for a recording), and the text itself when it is under 30 000 characters.

• Use it instead of tesseract, ocrmypdf or whisper. It reads tables row by row and copies numbers, codes and articles exactly; tesseract loses about one row in five on real invoices.
• The tool reads only files inside the current space (/spaces/<slug>). A file in /tmp, in your home folder or in another space is not found: copy it into the space first, then call the tool on the copy. (The plank-extract CLI takes any path and picks the workspace from the file's /spaces/<slug>/ folder; PLANK_WORKSPACE_ID is used only in a shared container.)
• Formats: PDF; JPEG, PNG and WebP images as they are; TIFF (every frame is a page), BMP and GIF are converted to JPEG first. HEIC/HEIF photos (iPhone) are refused: convert them to JPEG, then call again.
• One call per file, up to about 1 000 pages. Pages are read about 8 at a time at about 5 seconds each, so one call covers roughly 1 000 pages in 15 minutes, the tool's time limit; a 25-page batch takes under half a minute. For a longer file pass pages: "1-500", then "501-1000", and so on, or use the plank-extract CLI: the tool stops at about 15 minutes per call, while the CLI waits as long as the reading takes, up to the limits below. A call that ran out of time keeps the pages it finished: call again and they come from the cache.
• The result is written to ~/.cache/plank-extract/<sha256>.md, never next to the person's file, so their folders stay clean.
• Cached. The same file again is instant and free, in this space.
• A PDF page with real text (a text layer of at least 200 printable characters and no image on the page) is read from the text layer locally and never sent anywhere. A page that contains an image always goes to the model, because a scanner's built-in OCR layer is exactly what this tool replaces.
• Recordings: mp3, m4a, ogg, oga, opus, wav, webm, aac, flac. A recording is read in one call; for one of several hours prefer the plank-extract CLI, which waits as long as the transcription takes (up to the 6-hour limit), where the tool stops at about 15 minutes. A file that is not readable audio is refused with a message saying so. Limits are only a runaway guard: 2 000 pages, 6 hours or 512 MB of audio per call; above that the tool names the limit, so pass pages or split the file.
• From a script: plank-extract <file> [--pages 1-5,8] prints the .md path. With no arguments or a bad argument it prints usage and exits 2; exit 3 means some pages were not read (they are marked [not read: …]).
• If a page comes back [not read], look at that page yourself (plank_look_at) or call again.
• If it says extraction is not configured, fall back to tesseract (or read the pages yourself) and tell the person the text may contain recognition errors.
• If it says the Plank API is temporarily unavailable, that is a restart, not a missing feature: wait a minute and call again. Do not switch to tesseract for this.

Pages are read by a vision model at an external provider (Google's Gemini Flash-Lite, with Anthropic's Claude Haiku as a fallback only when Google is unavailable); recordings by OpenAI's transcription model — the same providers that already serve the chat.