get_paper_inf5.py 技術ドキュメント

プログラムの動作

get_paper_inf5.py は、学術論文のPDFファイルからメタデータ（著者名、論文タイトル、ジャーナル名、発行年、DOIなど）を抽出し、その情報をExcelファイルに集約することを目的としたPythonプログラムです。抽出されたメタデータに基づいて、PDFファイルを命名規則に従ってリネームする機能も提供します。

主な機能は以下の通りです。

  1. PDFからのテキスト抽出: 指定されたPDFファイルからテキストコンテンツを抽出します。抽出されるテキストの最大バイト数を制限できます。

  2. 生成AIによるメタデータ抽出: 抽出されたテキストをOpenAIまたはGoogleの生成AI APIに送信し、定義されたプロンプトテンプレートに基づいてJSON形式で論文のメタデータを抽出します。

  3. Excelファイルへの記録: 抽出されたメタデータをExcelファイル (summary.xlsx など) に追記します。各行は1つの論文に対応し、カラムには各種メタデータが含まれます。

  4. ファイルのリネーム: 生成AIが推奨するファイル名（filename_rename）に基づいて、元のPDFファイルをリネームまたはコピーします。元のファイルの削除オプションも提供されます。

  5. 複数ファイルの処理: コマンドラインで指定されたPDFファイル、または指定ディレクトリ内の複数のPDFファイルを再帰的に処理する機能も備えています。

原理

get_paper_inf5.py は以下の原理に基づいて動作します。

  1. PDFテキスト抽出: PyPDF2 ライブラリを使用してPDFファイルを開き、各ページからテキストコンテンツを抽出します。これにより、論文の本文、タイトル、著者情報などが文字列として取得されます。抽出されるテキストの量は、--max_bytes 引数で指定された最大バイト数に制限されます。これは、APIへの送信量を抑え、処理速度とコストを最適化するために重要です。

  2. 生成AIによるメタデータ抽出: 抽出されたPDFテキストは、プログラム内に定義されたプロンプトテンプレートに埋め込まれます。このプロンプトは、AIに対して、特定のメタデータ項目（著者、タイトル、ジャーナル、年、DOIなど）をJSON形式で抽出するように指示します。 プロンプトテンプレートの例：

    以下の学術論文のテキストから、指定された情報をJSON形式で抽出してください。
また、first author、last author、短縮したtitle (short_title)、shortest_name、発行年から
推奨ファイル名 {{template}} を作ってください。
short_titleの単語はCaptalFirstにして、空白、.、,などの文字は削除してください。
...
--- 論文テキスト ---
{{text}}

    {{text}} にはPDFから抽出されたテキストが、{{template}} にはファイル名テンプレートが挿入されます。 プログラムは以下のいずれかのAI APIを使用してこのプロンプトを送信し、JSON形式の応答を受け取ります。

    • OpenAI API: gpt-4o (デフォルトで query_openai4 を使用) または gpt-5-nano (デフォルトで query_openai5 を使用) モデルが利用されます。APIキー、モデル名、トークン数、温度（gpt-4oの場合）、推論努力（gpt-5-nanoの場合）は環境変数から設定されます。

    • Google Gemini API: gemini-2.5-flash (デフォルトで query_google を使用) モデルが利用されます。APIキーとモデル名は環境変数から設定されます。 各APIからのJSON応答は、プログラム内のヘルパー関数 (openai_response_to_json, openai5_response_to_json, google_response_to_json) によって解析され、Pythonの辞書オブジェクトに変換されます。

  3. ファイル名生成ロジック: プロンプトには、{{template}} の形式で推奨ファイル名のパターンが渡されます。デフォルトのテンプレートは (author_first)_(author_last)_(short_title)_(shortest_name)_(year).pdf です。AIは、抽出したメタデータからこのテンプレートに従って filename_rename を生成します。short_title は単語の頭文字を大文字にし、空白や句読点を除去するよう指示されています。

  4. Excelファイルへの記録: openpyxl ライブラリを使用して、抽出されたメタデータをExcelファイルに保存します。ファイルが存在しない場合はヘッダー行と共に新規作成され、存在する場合は新しいデータ行が追記されます。これにより、複数の論文のメタデータを一元的に管理できます。

  5. ファイル操作: os および shutil モジュールを使用して、PDFファイルのリネームまたはコピーを行います。--rename オプションが有効で、AIが filename_rename を生成した場合にこの処理が実行されます。--delete_original オプションにより、元のファイルを削除するか、残すかを選択できます。

必要な非標準ライブラリとインストール方法

このプログラムの動作には、以下の非標準Pythonライブラリが必要です。pip コマンドを使用してインストールしてください。

  • openpyxl: Excelファイル (.xlsx) の読み書きに使用されます。

    pip install openpyxl

  • PyPDF2: PDFファイルからテキストを抽出するために使用されます。

    pip install pypdf2

  • PyCryptodome: PDFファイルが暗号化されている場合、PyPDF2 が内部的に必要とすることがあります。エラーメッセージが表示された場合はインストールしてください。

    pip install pycryptodome

  • tkai_lib: このプログラムはカスタムライブラリ tkai_lib に依存しており、AIとの連携機能を提供します。このライブラリは、本プログラムの実行環境からアクセス可能なPythonのモジュール検索パスに配置されている必要があります。具体的なインストール手順は提供元の指示に従ってください。

必要な入力ファイル

プログラムの実行には、以下のファイルが必要です。

  1. PDFファイル:

    • メタデータ抽出の対象となる学術論文のPDFファイルです。

    • コマンドライン引数 input_file で1つまたは複数のパス（ワイルドカードを含む）を指定します。

    • 例: paper.pdf, articles/*.pdf

  2. ai.env ファイル:

    • APIキーやAIモデルの設定を記述する環境設定ファイルです。

    • プログラムは tkai_lib.read_ai_config(config_path) を介してこのファイルを読み込み、環境変数を設定します。

    • このファイルは、get_paper_inf5.py と同じディレクトリに配置されるか、プログラムがアクセスできるパスに存在する必要があります。

    • 以下に ai.env ファイルの内容例を示します。

      OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
openai_model="gpt-4o"
openai_model5="gpt-5-nano"
max_tokens="2000"
temperature="0.3"
reasoning_effort="low"
GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
gemini_model="gemini-2.5-flash"

      • YOUR_OPENAI_API_KEY: OpenAI APIの秘密鍵に置き換えてください。

      • YOUR_GOOGLE_API_KEY: Google Gemini APIの秘密鍵に置き換えてください。

      • 使用するAPIに応じて、関連するAPIキーとモデルを設定してください。

生成される出力ファイル

プログラムの実行により、以下のファイルが生成または更新されます。

  1. summary.xlsx (または指定されたパス):

    • 抽出された論文のメタデータが記録されるExcelスプレッドシートです。

    • デフォルトのファイル名は summary.xlsx ですが、--summary_path 引数で変更可能です。

    • ファイルが存在しない場合は新規作成され、ヘッダー行として以下のラベルが書き込まれます。 directory, filename_original, filename_rename, authors, author_first, author_last, title, short_title, journal, short_name, shortest_name, date_received, date_accepted, date_published_online, date_published, year, volume, issue, pages, doi

    • ファイルが既に存在する場合は、新しいメタデータ行が既存のデータの下に追記されます。

  2. リネームされたPDFファイル:

    • --rename 1 オプションが指定され、生成AIが推奨ファイル名 (filename_rename) を正常に生成した場合に、PDFファイルが操作されます。

    • リネームの場合: --delete_original 1 (デフォルト) が設定されている場合、元のPDFファイルは filename_rename で指定された名前に変更されます。

    • コピーの場合: --delete_original 0 が設定されている場合、元のPDFファイルはそのまま残り、filename_rename で指定された名前で新しいPDFファイルが作成されます。

    • filename_rename の形式は --template 引数で指定されたパターンに従います。デフォルトは (author_first)_(author_last)_(short_title)_(shortest_name)_(year).pdf です。

コマンドラインでの使用例 (Usage)

get_paper_inf5.py の基本的なコマンドライン構文は以下の通りです。

usage: get_paper_inf5.py [--api {openai,openai5,google}] [--summary_path SUMMARY_PATH] [--recursive RECURSIVE] [--rename RENAME] [--delete_original DELETE_ORIGINAL] [--max_bytes MAX_BYTES] [--template TEMPLATE] input_file

引数の説明:

  • input_file: 処理するPDFファイルのパス。ワイルドカード（例: *.pdf）やディレクトリ指定（例: data/*.pdf）も可能です。

  • --api {openai,openai5,google}: 使用するAI APIを指定します。

    • openai5: OpenAIの gpt-5-nano モデルを使用します (デフォルト)。

    • openai: OpenAIの gpt-4o モデルを使用します。

    • google: Googleの gemini-2.5-flash モデルを使用します。

  • --summary_path SUMMARY_PATH: 生成されるExcelファイルのパスを指定します (デフォルト: summary.xlsx)。

  • --recursive RECURSIVE: サブディレクトリを含めてPDFファイルを検索するかどうかを指定します。

    • 1: 再帰的に検索します。

    • 0: 現在のディレクトリのみを検索します (デフォルト)。

  • --rename RENAME: 生成AIで推薦ファイル名を取得できた場合に、ファイルをリネームするかどうかを指定します。

    • 1: リネームまたはコピーを実行します。

    • 0: リネームまたはコピーを行いません (デフォルト)。

  • --delete_original DELETE_ORIGINAL: --rename 1 が指定された場合に、元のファイルを削除するかどうかを指定します。

    • 1: 元のファイルを削除します (デフォルト)。

    • 0: 元のファイルを削除せず、コピーとして新しいファイルを作成します。

  • --max_bytes MAX_BYTES: APIに送信するテキストの最大バイト数を指定します。論文全体を送る必要がない場合に指定し、コスト削減に役立ちます (デフォルト: 10000バイト)。

  • --template TEMPLATE: ファイル名を変更する際のテンプレート文字列を指定します (デフォルト: (author_first)_(author_last)_(short_title)_(shortest_name)_(year).pdf)。{{author_first}}, {{title}} などのプレースホルダーを使用できます。

コマンドラインでの具体的な使用例

以下の例では、ai.env ファイルがプログラムと同じディレクトリに存在し、必要なAPIキーが設定されていることを前提とします。

  1. 単一のPDFファイルからメタデータを抽出し、Excelに記録する（デフォルト設定）: my_paper.pdf から情報を抽出し、summary.xlsx に追記します。ファイルのリネームは行いません。

    python get_paper_inf5.py my_paper.pdf

    実行結果の説明: my_paper.pdf のテキストが抽出され、openai5 API (gpt-5-nano) を使用してメタデータが取得されます。抽出されたメタデータはコンソールに出力され、summary.xlsx ファイルに追記されます。summary.xlsx が存在しない場合は新規作成されます。

  2. 特定のAPI (OpenAI gpt-4o) を使用してメタデータを抽出し、リネームする: another_paper.pdf を処理し、openai API (gpt-4o) を使用してメタデータを取得します。抽出した情報に基づいてファイルをリネームし、元のファイルは削除します。

    python get_paper_inf5.py --api openai --rename 1 --delete_original 1 another_paper.pdf

    実行結果の説明: another_paper.pdf からテキストが抽出され、openai API (gpt-4o) を使用してメタデータが取得されます。コンソールにメタデータが出力され、summary.xlsx に追記されます。AIが推奨するファイル名（例: Smith_Jones_MyResearchPaper_JRNL_2023.pdf）に another_paper.pdf がリネームされ、元のファイルは削除されます。

  3. 指定したディレクトリ内のすべてのPDFファイルを再帰的に処理し、元のファイルを残してコピーをリネームする: papers ディレクトリとそのサブディレクトリにあるすべてのPDFファイル (.pdf 拡張子) を処理します。Google Gemini APIを使用し、リネームされたファイルを元の場所にコピーとして残します。

    python get_paper_inf5.py --api google --recursive 1 --rename 1 --delete_original 0 papers/**/*.pdf

    実行結果の説明: papers ディレクトリ以下の全てのPDFファイルが検索され、個別に処理されます。各PDFファイルからテキストが抽出され、google API (gemini-2.5-flash) を使用してメタデータが取得されます。各ファイルのメタデータは summary.xlsx に追記されます。各PDFファイルは、AIが推奨するファイル名（例: Brown_Green_AmazingStudy_PROC_2022.pdf）で同じディレクトリにコピーされ、元のファイルは削除されずに残ります。

  4. カスタムファイル名テンプレートを指定する: report.pdf を処理し、ファイル名テンプレートを {{year}}-{{author_last}}-{{title}}.pdf に変更してリネームします。

    python get_paper_inf5.py --rename 1 --template "{{year}}-{{author_last}}-{{title}}.pdf" report.pdf

    実行結果の説明: report.pdf からメタデータが抽出され、AIが 2024-AuthorLastName-FullPaperTitle.pdf のような形式でファイル名を生成します。report.pdf はこの新しいファイル名にリネームされます。