pdf-text-extractor

PDF テキスト抽出ツール

トリガーとルーティング

• トリガー：PDF のダウンロード、全文、テキストの抽出、論文/PDF、全文抽出、PDF のダウンロード。
• 使用する場合：queries.md で evidence_mode: fulltext を設定している場合（または全文のエビデンスが明確に必要な場合）で、論文ノートや主張により強いエビデンスを提供したいとき。

アブストラクトを超えてエビデンスを深めるため、全文の抜粋を任意で収集できます。

このスキルは意図的に保守的な設計です。多くのサーベイ実行では、アブストラクト/スニペットモードで十分であり、負荷の高いダウンロードを避けられます。

入力

• papers/core_set.csv（paper_id、title、および可能であれば pdf_url/arxiv_id/url が必要です）
• 任意：outline/mapping.tsv（マッピングされた論文を優先するために使用します）

出力

• papers/fulltext_index.jsonl（試行した論文ごとに1レコード）
• 付随するファイル：
  • papers/pdfs/<paper_id>.pdf（ダウンロードしたファイルのキャッシュ）
  • papers/fulltext/<paper_id>.txt（抽出したテキスト）

判断：エビデンスモード

• queries.md では evidence_mode: "abstract" | "fulltext" を設定できます。
  • abstract（デフォルトのテンプレート）：ダウンロードしません。スキップしたことが明確に記録されたインデックスを作成します。
  • fulltext：可能な場合は PDF をダウンロードし、papers/fulltext/ にテキストを抽出します。

ローカル PDF モード

PDF をダウンロードできない、またはダウンロードすべきでない場合（ネットワークの制限、レート制限、権限がない場合）は、PDF を手動で用意し、「ローカル PDF のみ」モードで実行します。

• PDF の命名規則：papers/pdfs/<paper_id>.pdf。<paper_id> は papers/core_set.csv と一致させます。
• queries.md で - evidence_mode: "fulltext" を設定します。
• 実行：uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --local-pdfs-only

PDF が不足している場合、スクリプトは対応が必要なファイルの一覧を書き出します。

• output/MISSING_PDFS.md（人間が読みやすい概要）
• papers/missing_pdfs.csv（機械可読な一覧）

ワークフロー（ヒューリスティック）

1. papers/core_set.csv を読み込みます。
2. outline/mapping.tsv がある場合は、マッピングされた論文を先に処理します。
3. 全文モードでは、選択した各論文について次の処理を行います。
   • pdf_url を特定します（pdf_url を使用し、なければ可能な場合は arxiv_id/url から導出します）。
   • PDF がない場合は papers/pdfs/<paper_id>.pdf にダウンロードします。
   • 適切な範囲の先頭部分のテキストを papers/fulltext/<paper_id>.txt に抽出します。
   • ステータスと統計情報を含む JSONL レコードを papers/fulltext_index.jsonl に追加または更新します。
4. 明示的に要求されない限り、抽出済みのテキストを上書きしません（再抽出するには .txt を削除してください）。

品質チェックリスト

• papers/fulltext_index.jsonl が存在し、空ではない。
• evidence_mode: "fulltext" の場合：少なくとも一部の論文から、少量でも無視できない量のテキストが抽出されている（抽出範囲がほぼゼロの場合、厳格モードでは処理を中止します）。
• evidence_mode: "abstract" の場合：インデックスに papers/core_set.csv 内の全論文が含まれ、すべてのレコードで skip_mode_abstract が明確に示されている（ダウンロードは試行されません）。fulltext_max_papers によって、ダウンロードを行わないこのインデックスが途中で切り詰められることはありません。

スクリプト

クイックスタート

• uv run python .codex/skills/pdf-text-extractor/scripts/run.py --help
• uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace>

すべてのオプション

• --max-papers <n>：処理する論文数の上限（queries.md で上書きできます）
• --max-pages <n>：PDF ごとに抽出するページ数の上限
• --min-chars <n>：正常と判定するために必要な抽出文字数の最小値
• --sleep <sec>：ダウンロード間の待機時間
• --local-pdfs-only：ダウンロードせず、存在する場合に限り papers/pdfs/<paper_id>.pdf を使用します
• queries.md で指定できる項目：evidence_mode、fulltext_max_papers、fulltext_max_pages、fulltext_min_chars

例

• アブストラクトモード（ダウンロードなし）：
  • queries.md で - evidence_mode: "abstract" に設定してから、スクリプトを実行します（スキップ状態を含む papers/fulltext_index.jsonl が出力されます）。
• ローカル PDF のみを使う全文モード：
  • queries.md で - evidence_mode: "fulltext" に設定し、PDF を papers/pdfs/ の下に置いてから、次を実行します：uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --local-pdfs-only
• 上限を小さくした全文モード：
  • uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --max-papers 20 --max-pages 4 --min-chars 1200

注意事項

• ダウンロードしたファイルは papers/pdfs/ にキャッシュされます。抽出したテキストは papers/fulltext/ にキャッシュされます。
• .txt ファイルを削除しない限り、スクリプトは既存の抽出済みテキストを上書きしません。

トラブルシューティング

問題：ダウンロード可能な PDF がありません

解決方法：

• evidence_mode: abstract（デフォルト）を使うか、ローカル PDF を papers/pdfs/ の下に置いて、--local-pdfs-only を指定して再実行します。

問題：抽出したテキストが空、または文字化けしています

解決方法：

• 対応している場合は、別の抽出バックエンドを試してください。それ以外の場合は、その論文のエビデンスレベルを abstract に設定し、全文に基づく強い主張を避けてください。