pdf-inspector

pdf-inspector

firecrawl/pdf-inspector を基盤とする、ローカル PDF → Markdown 変換ツールです。 純粋な Rust 製で、依存関係は lopdf のみです。読み取り順序と表の解析において opendataloader-bench のローカルパーサー比較で最高評価を獲得しており、完全にオフラインで動作します。

すぐに使う

同梱のラッパーを実行します（パスはこのスキルのフォルダーからの相対パスです）。初回実行時に ~/.venvs/pdf-inspector に venv をセットアップし（$PDF_INSPECTOR_VENV で変更できます）、 pdf-inspector ホイールをインストールします。それ以降はすべてオフラインで動作します。

python3 scripts/pdfmd.py document.pdf                  # Markdown on stdout, status on stderr
python3 scripts/pdfmd.py document.pdf --detect         # classification only (fast), JSON output
python3 scripts/pdfmd.py document.pdf --json           # full result (markdown + metadata) as JSON
python3 scripts/pdfmd.py document.pdf --text           # plain text, no Markdown structure
python3 scripts/pdfmd.py document.pdf --pages 1,3,5-10 # only these pages (1-indexed; not with --text)

終了コード：0 = 抽出完了、2 = 抽出可能なテキストなし（スキャン画像 PDF — OCR が必要）、1 = エラー。

結果の読み方

• pdf_type：text_based | scanned | image_based | mixed。confidence は 0.0～1.0 です。
• pages_needing_ocr：抽出可能なテキストがないページ（ページ番号は 1 始まり）。これらのページの内容は出力に含まれません。
• has_encoding_issues：true は、抽出したテキストが文字化けしている可能性があることを示します（フォントのエンコーディング破損）。スキャン文書と同様に扱ってください。
• pages_with_tables / pages_with_columns：ページ番号は 1 始まりです。レイアウトが複雑なページのスポットチェックに便利です。

ルール

1. OCR が必要なページの内容を絶対に捏造しないでください。 pdf_type が scanned / image_based の場合、または pages_needing_ocr が空でない場合は、読み取れなかったページを正確に示し、OCR ツールに回す（またはユーザーに確認する）ようにしてください。終了コード 2 は、文書全体に OCR が必要であることを意味します。
2. mixed PDF の場合は、テキストページには抽出した Markdown を使用し、OCR が必要なページを明示してください。欠落箇所を明記していれば、部分的な出力でもかまいません。
3. 大きな PDF（100 ページ以上）の場合は、まず --detect を実行し（約 10～50 ミリ秒）、次に --pages を指定して必要なページだけを抽出してください。
4. has_encoding_issues が true の場合は、テキストが一見もっともらしく見えても信用しないでください。

Python API を直接使う（上級者向け）

領域単位または位置単位の処理には、venv の Python を直接使用してください （~/.venvs/pdf-inspector/bin/python）：

import pdf_inspector
r = pdf_inspector.process_pdf("doc.pdf", pages=[1, 3])      # full result; pages= is 1-indexed
c = pdf_inspector.classify_pdf("doc.pdf")                   # lightweight; pages_needing_ocr is 0-indexed here
items = pdf_inspector.extract_text_with_positions("doc.pdf")  # TextItem: text, x, y, font, page, bold/italic
per_page = pdf_inspector.extract_pages_markdown("doc.pdf", pages=[0, 2])  # 0-indexed pages arg
regions = pdf_inspector.extract_text_in_regions("doc.pdf", [(0, [[50, 50, 400, 200]])])

インデックスに注意してください。関数によって異なります。process_pdf(pages=) は 1 始まり、 extract_pages_markdown(pages=) と classify_pdf の結果は 0 始まり、全結果に含まれる pages_needing_ocr / pages_with_tables は 1 始まりです。ラッパースクリプトがこの違いを処理しますが、ほかの関数を使う場合は実際に確認してください。

ホイールのインストールに失敗した場合

PyPI では macOS（x64/arm64）、Linux（x64/aarch64）、Windows x64 向けのホイールが提供されています。それ以外の環境では、代わりにソースからビルドしてください。cargo install pdf-inspector を実行すると、同等の pdf2md および detect-pdf バイナリを利用できます（純粋な Rust 製で、システムライブラリは不要です）。 npm パッケージ @firecrawl/pdf-inspector のプリビルド版は linux-x64/darwin-arm64/win-x64 のみです。Linux arm64 マシンでは Python ホイールを優先してください。

クレジット

高度な処理はすべて、Firecrawl チームによる pdf-inspector が担っています（MIT、© 2026 Firecrawl）。このスキルは、コーディングエージェント向けにパッケージ化したものです。