oma-pdf

PDF スキル - PDF から Markdown への変換

スケジューリング

目標

LLM のコンテキスト、RAG、または後続のレビューに使えるよう、読みやすい文書構造を維持しながら、PDF ファイルを構造化された Markdown または指定された別の抽出形式に変換します。

意図のシグネチャ

• ユーザーが PDF の変換、解析、読み取り、抽出、または形式変換を依頼している。
• ユーザーが AI で利用できるよう、PDF のテキスト、見出し、リスト、表、または画像を準備する必要がある。
• ユーザーが「PDF to markdown」、「parse PDF」、「read this PDF」、または同等の表現を使っている。

使用する場合

• LLM のコンテキストまたは RAG 用に PDF 文書を Markdown に変換する場合
• 表、見出し、リスト、画像、脚注、ハイパーリンクなどの構造化されたコンテンツを抽出する場合
• AI で利用できるように PDF データを準備する場合
• OCR を選択する前に、PDF にテキストレイヤーがあるか確認する場合

使用しない場合

• PDF の生成または作成 → 文書生成ツールを使用してください
• 既存の PDF の編集 → 対象外です
• すでにテキストファイルになっているものの読み取り → ファイルを直接読み取ってください
• HWP、HWPX、DOCX、XLSX、またはスライド資料の処理 → 該当する文書スキルを使用してください

想定される入力

• input_path：PDF ファイルまたはフォルダーのパス
• output_dir：任意の出力先ディレクトリ
• format：任意の出力形式。既定値は markdown
• ocr_languages：スキャンされた PDF または画像ベースの PDF に使用する、任意の OCR 言語リスト
• extraction_options：タグ付き構造、画像抽出、またはハイブリッド変換の任意のフラグ

想定される出力

• Markdown、テキスト、JSON、HTML、またはこれらを組み合わせた抽出結果
• Markdown を出力する場合は、正規化された Markdown
• 出力パス、ページ数、変換時の問題を記載した簡潔なレポート

依存関係

• 標準変換には uvx opendataloader-pdf
• OCR またはハイブリッド変換には uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid（ハイブリッドサーバーは [hybrid] エクストラのコンソールスクリプトであり、単独のパッケージではありません）
• Markdown の正規化には uvx mdformat
• 入力パスと出力パスへのローカルファイルシステムアクセス
• ハイブリッドサーバー経由の任意の OCR ランタイム

制御フローの機能

• テキストレイヤーの品質、タグ付き PDF の有無、スキャン／OCR の必要性、ユーザー指定の出力形式に応じて分岐します
• uvx を通じて外部 CLI ツールを呼び出します
• ローカルファイルを読み取り、抽出結果をローカルに書き込みます
• OCR または複雑な抽出が必要な場合に限り、ハイブリッドサーバーを使用します

構造フロー

開始

1. 入力パスが存在し、PDF ファイル、PDF フォルダー、またはサポート対象の一括入力であることを確認します。
2. ファイルサイズを確認し、変換に時間がかかったり、メモリに負荷がかかったりするおそれがある場合は警告します。
3. output_dir と想定される出力ファイル名を決定します。

シーン

1. 準備：入力パス、出力先、指定された抽出オプションを検証します。
2. 取得：テキストのプレビューを抽出し、PDF に読み取り可能なテキストレイヤーがあるか評価します。
3. 実行：標準モード、タグ付き構造モード、またはハイブリッド OCR モードで変換します。
4. 検証：Markdown 出力には mdformat を実行し、読みやすい構造になっているか確認します。
5. 完了：出力パス、ページ数、形式、抽出品質に関する問題を報告します。

遷移

• プレビューのテキストが読み取り可能な場合は、標準変換を使用します。
• PDF にタグが付いていて標準出力が文字化けする場合は、--use-struct-tree を指定して再試行します。
• 表が欠落または崩れている場合は、ハイブリッドモードに切り替える前に、--table-method cluster または --markdown-with-html を指定して再試行します。
• PDF がスキャン済みまたは画像ベースの場合は、ハイブリッド OCR サーバーを起動または再利用し、ハイブリッドモードで変換します。
• PDF が暗号化されているため変換に失敗した場合は、処理を停止し、パスワードまたはロック解除済みのコピーを求めます。
• メモリまたはサイズの制限に達した場合は、より小さなページ範囲に分けて、それぞれ別の出力ディレクトリに処理します（または --to-stdout を追加します）。これにより、繰り返し実行しても同じベース名のファイルが上書きされません。

失敗と復旧

失敗	復旧方法
uvx が利用できない	変換前に uv をインストールするようユーザーに依頼します
opendataloader-pdf-hybrid が見つからない	uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid で呼び出します。PyPI にパッケージ名だけのものは存在しません
パスワードで保護された PDF	パスワード、またはロック解除済みの PDF を依頼します
出力が文字化けしている	タグ付き構造またはハイブリッドモードで再試行します
表が欠落している	まず --table-method cluster または --markdown-with-html を指定して再試行します。スキャンされた表にはハイブリッドモードを使用します
OCR の言語が一致しない	たとえば ko,en のように、OCR 言語を明示して再試行します
ファイルが大きい、またはメモリに負荷がかかっている	個別の出力ディレクトリまたは --to-stdout を使ってページ範囲ごとに分割します。同じベース名に対して同じ出力ディレクトリを再利用しないでください

終了

• 成功：出力ファイルが存在し、該当する場合は Markdown が整形され、抽出された構造を読み取れます。
• 部分的な成功：出力は存在しますが、品質上の問題が明示的に報告されています。
• 失敗：信頼できる出力が生成されず、処理を妨げた原因が報告されています。

論理操作

アクション

アクション	SSL プリミティブ	根拠
パスとオプションを検証する	VALIDATE	実行プロトコルでの入力の事前確認
テキストレイヤーを調べる	READ	テキストのプレビュー抽出
変換方法を選択する	SELECT	標準、タグ付き、またはハイブリッドモードの決定
コンバーターを実行する	CALL_TOOL	uvx opendataloader-pdf
OCR サーバーを起動する	CALL_TOOL	uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid
出力アーティファクトを書き込む	WRITE	Markdown、テキスト、JSON、または HTML の出力
Markdown を正規化する	CALL_TOOL	uvx mdformat
抽出品質を確認する	VALIDATE	構造と読みやすさの検証
結果を報告する	NOTIFY	ユーザー向けの最終サマリー

ツールと機器

• opendataloader-pdf：PDF 抽出の主要 CLI
• opendataloader-pdf-hybrid：ハイブリッド OCR と複雑な抽出のための処理経路
• mdformat：Markdown の正規化
• file、wc、pdfinfo などのファイルシステムコマンドは、利用可能な場合、事前確認に使用できます

標準的なコマンドの流れ

uvx opendataloader-pdf "{input_path}" -f text --pages 1-3 --to-stdout -q   # text-layer probe (no temp files)
uvx opendataloader-pdf "{input_path}" --format markdown --output-dir "{output_dir}"
uvx mdformat "{output_path}"

スキャン画像ベースの PDF では、まず OCR を起動し、その後ハイブリッドモードで変換します：

uvx --from "opendataloader-pdf[hybrid]" opendataloader-pdf-hybrid --port 5002 --force-ocr --ocr-lang "{languages}"
uvx opendataloader-pdf --hybrid docling-fast --hybrid-mode full "{input_path}" --format markdown --output-dir "{output_dir}"

リクエストに応じたフラグ — --sanitize（PII のマスキング）、--pages（範囲を指定した抽出）、--threads（ページの並列処理）、--detect-strikethrough、ハイブリッドの --enrich-formula／--enrich-picture-description — の詳細は resources/execution-protocol.md に記載されています。2 つの拡張フラグには、クライアント側での --hybrid-mode full の指定が必要です。

リソースの範囲

範囲	リソースの対象
LOCAL_FS	入力 PDF と生成された出力ファイル
PROCESS	uvx サブプロセスとオプションのハイブリッドサーバー
MEMORY	抽出されたプレビューと検証メモ
OTHER	ハイブリッドモード内の OCR モデル／ランタイムの動作

前提条件

• 入力 PDF のパスが存在し、読み取り可能であること。
• 出力先に書き込み可能であるか、作成可能であること。
• 必要な CLI を uvx 経由で利用できること。
• OCR は、ハイブリッドモードが利用可能な場合、または起動可能な場合にのみ実行されます。
• デフォルト値は .agents/oma-config.yaml の pdf: セクションから取得し、未設定のキーには config/pdf-config.yaml の値を使用します。明示的なユーザー指定オプションは両方より優先されます。また、output.overwrite: false の場合、既存の出力ファイルを置き換える前に確認が必要です。

影響と副作用

• 設定とユーザーの意図に応じて、抽出出力を作成または上書きします。
• 設定されたポートで、ローカルのハイブリッド OCR サーバーを起動する場合があります。
• 大容量またはスキャンされた PDF では、CPU、メモリ、または時間を大幅に消費する場合があります。
• ソース PDF を意図的に変更することはありません。

ガードレール

1. 抽出が不完全な場合、不足している内容を創作しないでください。
2. 文字化け、表の欠落、OCR の不確実性、抽出の一部欠落は必ず報告してください。
3. テキストレイヤーが読み取り可能な場合は、まず標準的な変換を優先してください。
4. PDF がスキャン画像または画像ベースの場合、あるいは標準的な抽出品質が不十分な場合にのみ、OCR を使用してください。
5. 詳細なコマンド手順は、すべてのバリエーションをここに重複して記載せず、resources/execution-protocol.md に記載してください。

参考資料

• 実行プロトコル：resources/execution-protocol.md
• 設定：まず .agents/oma-config.yaml の pdf: セクションを読み、そのセクションで設定されていないキーについては config/pdf-config.yaml を参照してください。oma update によってスキル設定が上書きされるため、ユーザーによる上書き設定は .agents/oma-config.yaml に記載してください。
• コンテキストの読み込み：../_shared/core/context-loading.md
• 品質原則：../_shared/core/quality-principles.md