pi-docparser 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project follows semantic versioning.
+
+## [1.0.0] - 2026-03-20
+
+Initial public release.
+
+### Added
+
+- `document_parse` pi extension powered by LiteParse for PDFs, Office documents, spreadsheets, CSV files, and common images
+- OCR support, text or JSON output, page targeting, and optional PDF screenshot extraction
+- `/docparser-doctor` command for host dependency checks and guided setup hints
+- `parse-document` skill, package docs, third-party notices, and preview assets
+- Bun-based validation scripts for formatting with `oxfmt`, linting with `oxlint`, and TypeScript type checks

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MaxedApps GmbH / Maximilian Schwarzmüller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# pi-docparser
+
+A standalone [pi](https://shittycodingagent.ai/) package that adds a `document_parse` tool plus a companion `parse-document` skill for extracting content from local documents.
+
+It wraps [`@llamaindex/liteparse`](https://github.com/run-llama/liteparse) so pi can parse PDFs, Office documents, spreadsheets, CSV files, and common image formats through a dedicated tool instead of ad-hoc shell commands. It can also perform OCR.
+
+When required host tools such as LibreOffice, ImageMagick, or Ghostscript are missing, the tool surfaces actionable install guidance instead of generic conversion failures and points users to `/docparser-doctor` for guided setup.
+
+## What this package provides
+
+### Extension
+
+Registers a `document_parse` tool that can:
+
+- parse local documents to `text` or `json`
+- use OCR for scanned or image-based documents
+- accept single-language OCR via `ocrLanguage` or multilingual OCR via `ocrLanguages`
+- limit parsing to selected page ranges
+- preserve layout alignment across page boundaries when needed
+- generate PNG screenshots for PDF pages, including `screenshotPages: "all"`
+- save full parsed output to temporary files for follow-up inspection with pi's `read` tool
+
+### Skill
+
+Ships a `parse-document` skill that helps pi use the tool efficiently:
+
+- prefer text output unless coordinates matter
+- use OCR deliberately
+- use screenshots only when visual layout matters
+- keep large parsed outputs out of the model context until needed
+
+## Supported inputs
+
+This package uses LiteParse and therefore supports the formats LiteParse supports locally, including:
+
+- PDF
+- DOC / DOCX / ODT / RTF
+- PPT / PPTX / ODP
+- XLS / XLSX / XLSM / ODS
+- CSV / TSV
+- PNG / JPG / JPEG / GIF / BMP / TIFF / WebP / SVG
+
+Support for non-PDF formats may depend on host tools such as LibreOffice or ImageMagick. See [Host dependencies](#host-dependencies).
+
+## Requirements
+
+- pi installed and working
+- Node.js 18+
+- local machine access to the files you want to parse
+
+## Installation
+
+### npm install
+
+```bash
+pi install npm:pi-docparser
+```
+
+### Install from GitHub
+
+```bash
+pi install git:github.com/maxedapps/pi-docparser
+```
+
+## Example model tool calls
+
+These are representative `document_parse` calls pi may make internally, depending on the user's request:
+
+### 1) Extract plain text from a PDF
+
+```text
+document_parse({
+  path: "./docs/contract.pdf"
+})
+```
+
+Useful when the user wants the document summarized, searched, or quoted and layout coordinates are not needed.
+
+### 2) OCR a scanned image or photo
+
+```text
+document_parse({
+  path: "./scans/receipt.jpg",
+  ocr: "auto",
+  ocrLanguage: "eng"
+})
+```
+
+Useful when the source is an image or scanned document and text must be recognized first.
+
+### 3) Extract structured JSON and PDF screenshots for selected pages
+
+```text
+document_parse({
+  path: "./reports/financial-report.pdf",
+  format: "json",
+  targetPages: "1-3",
+  screenshotPages: "1-2"
+})
+```
+
+Useful when the user cares about page layout, bounding boxes, or wants visual follow-up on specific PDF pages.
+
+## Tool behavior notes
+
+### OCR notes
+
+LiteParse's built-in Tesseract OCR is used by default when OCR is enabled and no `ocrServerUrl` is provided.
+
+Important details:
+
+- the first OCR run may download Tesseract language/model data
+- built-in Tesseract typically uses ISO 639-3 language codes such as `eng`, `deu`, `fra`, `jpn`
+- many HTTP OCR servers instead expect ISO 639-1 codes such as `en`, `de`, `fr`, `ja`
+- `ocrLanguages` is joined into a multilingual language string for built-in Tesseract
+- when `ocrServerUrl` is used, only the first entry from `ocrLanguages` is forwarded
+
+### Screenshots
+
+- screenshot rendering is PDF-only
+- screenshot output is PNG-only in this package
+- use `screenshotPages: "all"` to render every PDF page
+- use page selections like `"1-3,8"` to limit screenshot work
+
+## Host dependencies
+
+This package relies on LiteParse for local parsing and conversion. Depending on the input format, you may need additional host tools installed.
+
+The tool performs a lightweight preflight check for the most common host dependencies and also forwards LiteParse's original error messages when conversion fails.
+
+### LibreOffice
+
+Needed for many Office document and spreadsheet conversion paths.
+
+Examples from LiteParse documentation:
+
+```bash
+# macOS
+brew install --cask libreoffice
+
+# Ubuntu / Debian
+apt-get install libreoffice
+
+# Windows
+choco install libreoffice-fresh
+```
+
+### ImageMagick
+
+Needed for image-to-PDF conversion paths.
+
+```bash
+# macOS
+brew install imagemagick
+
+# Ubuntu / Debian
+apt-get install imagemagick
+
+# Windows
+choco install imagemagick.app
+```
+
+### Ghostscript
+
+Some image or vector conversion paths may also require Ghostscript.
+
+## Doctor command
+
+If parsing fails because a host dependency is missing, the extension points users to:
+
+```text
+/docparser-doctor
+```
+
+Run it inside pi to:
+
+- detect the current operating system
+- check whether LibreOffice, ImageMagick, and Ghostscript are available
+- optionally focus the check on a specific file path
+- suggest the most appropriate install commands for the current machine
+- optionally attempt those install commands after user confirmation when that looks safe to automate
+
+Examples:
+
+```text
+/docparser-doctor
+/docparser-doctor @./slides.pptx
+```
+
+## Known limitations
+
+- screenshot rendering is PDF-only and PNG-only
+- OCR quality depends on scan quality, page layout, and the chosen OCR language
+- some conversion paths depend on external host tools
+- output is written to temporary files, not directly into your repository
+
+## Third-party dependency: LiteParse
+
+This package depends on:
+
+- [`@llamaindex/liteparse`](https://github.com/run-llama/liteparse)
+- license: Apache-2.0
+- purpose: local document parsing, OCR, screenshots, and conversion support
+
+LiteParse itself documents its own upstream dependencies and platform requirements. See:
+
+- repository: https://github.com/run-llama/liteparse
+- npm package: https://www.npmjs.com/package/@llamaindex/liteparse
+- docs: https://developers.llamaindex.ai/liteparse/
+
+Additional attribution details are listed in [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## License
+
+This package is licensed under the MIT License. See [LICENSE](./LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-Party Notices
+
+## LiteParse
+
+This package depends on the following third-party library at runtime:
+
+- **Package:** `@llamaindex/liteparse`
+- **Version used by this package:** `1.0.0`
+- **Repository:** https://github.com/run-llama/liteparse
+- **License:** Apache-2.0
+- **Local license copy:** [`./licenses/LiteParse-APACHE-2.0.txt`](./licenses/LiteParse-APACHE-2.0.txt)
+- **Upstream license file:** https://github.com/run-llama/liteparse/blob/main/LICENSE
+
+### Usage in this package
+
+`pi-docparser` uses LiteParse as an npm dependency to provide:
+
+- local document parsing
+- OCR support
+- PDF screenshot generation
+- conversion support for Office and image inputs
+
+This package does **not** vendor LiteParse source code.
+It relies on the installed npm dependency at runtime.
+
+### Upstream attribution
+
+LiteParse is developed by LlamaIndex and distributed under the Apache License 2.0.
+Please review the upstream repository and license for full details.

package/extensions/docparser/constants.ts

@@ -0,0 +1,71 @@
+import { cpus } from "node:os";
+
+export const PREVIEW_MAX_LINES = 20;
+export const PREVIEW_MAX_BYTES = 2 * 1024;
+export const DEFAULT_MAX_PAGES = 10000;
+export const DEFAULT_DPI = 150;
+export const DEFAULT_NUM_WORKERS = Math.max(1, cpus().length - 1);
+export const INSTALL_COMMAND_TIMEOUT_MS = 30 * 60 * 1000;
+
+export const OFFICE_EXTENSIONS = new Set([
+  ".doc",
+  ".docx",
+  ".docm",
+  ".dot",
+  ".dotm",
+  ".dotx",
+  ".odt",
+  ".ott",
+  ".ppt",
+  ".pptx",
+  ".pptm",
+  ".pot",
+  ".potm",
+  ".potx",
+  ".odp",
+  ".otp",
+  ".rtf",
+  ".pages",
+  ".key",
+]);
+
+export const SPREADSHEET_EXTENSIONS = new Set([
+  ".xls",
+  ".xlsx",
+  ".xlsm",
+  ".xlsb",
+  ".ods",
+  ".ots",
+  ".csv",
+  ".tsv",
+  ".numbers",
+]);
+
+export const IMAGE_EXTENSIONS = new Set([
+  ".jpg",
+  ".jpeg",
+  ".png",
+  ".gif",
+  ".bmp",
+  ".tiff",
+  ".tif",
+  ".webp",
+  ".svg",
+  ".eps",
+  ".ps",
+  ".ai",
+]);
+
+export const GHOSTSCRIPT_REQUIRED_EXTENSIONS = new Set([".svg", ".eps", ".ps", ".ai"]);
+
+export const LIBREOFFICE_MISSING_MESSAGE =
+  "LibreOffice is not installed. Please install LibreOffice to convert office documents. On macOS: brew install --cask libreoffice, On Ubuntu: apt-get install libreoffice, On Windows: choco install libreoffice-fresh";
+
+export const IMAGEMAGICK_MISSING_MESSAGE =
+  "ImageMagick is not installed. Please install ImageMagick to convert images. On macOS: brew install imagemagick, On Ubuntu: apt-get install imagemagick, On Windows: choco install imagemagick.app";
+
+export const GHOSTSCRIPT_MISSING_MESSAGE =
+  "Ghostscript is required to convert %s files but is not installed. On macOS: brew install ghostscript, On Ubuntu: apt-get install ghostscript, On Windows: choco install ghostscript";
+
+export const DOCTOR_COMMAND_NAME = "docparser-doctor";
+export const DOCTOR_COMMAND = `/${DOCTOR_COMMAND_NAME}`;