make_textbook5.py 技術ドキュメント

プログラムの動作

make_textbook5.py は、AI（OpenAIのGPTシリーズまたはGoogleのGeminiシリーズ）を利用して、講義の文字起こしテキストとMarkdown形式のスライドから、教育用の教科書Markdownと、より洗練されたスライド用Markdownを自動生成するPythonスクリプトです。このプログラムは、AIプロンプトエンジニアリングを駆使し、ユーザーが指定する出力言語、専門分野、役割に基づいて最適なコンテンツを生成します。

主な機能:

  • 入力ファイルの処理: 講義の文字起こしテキストファイル (.txt) およびオプションとして既存の講義スライドMarkdownファイル (.md) を読み込みます。

  • AI APIの選択: OpenAI (GPT-4oなど) または Google Gemini (Gemini-2.5-flashなど) のいずれかのAI APIを選択して利用できます。

  • プロンプトの動的構築: 出力言語（日本語、英語など）、専門分野（半導体工学など）、およびAIの役割（大学教授など）に基づいて、AIへのプロンプトを自動で構築します。

  • AI応答の解析と保存: AIからの応答を解析し、教科書内容とスライド内容をそれぞれのMarkdownファイルに抽出して保存します。

  • デバッグログの生成: AIに送信されたメッセージ（プロンプト）は、デバッグ用にJSON形式のログファイル (.log) として保存されます。

  • INIファイルによる設定: プロンプトテンプレートなどの設定は、INIファイルから柔軟に読み込めます。

解決する課題:

講義内容から教科書や洗練されたスライドを手動で作成する労力を大幅に削減し、教育コンテンツ制作の効率化と品質向上に貢献します。

原理

本プログラムは、大規模言語モデル（LLM）の強力なテキスト生成能力を最大限に活用するために、以下の原理に基づいています。

  1. AIプロンプトエンジニアリング:

    • ユーザーが指定する出力言語 (--lang)、専門分野 (--field)、およびAIの役割 (--role) を用いて、AIへの具体的な指示（プロンプト）を動的に構築します。これにより、生成されるコンテンツが特定の文脈や目的に合致し、より高品質で専門性の高いものになります。

    • プロンプトテンプレートは、INIファイル (--inifile) から読み込まれる PROMPT_TEMPLATE_JA (日本語用) および PROMPT_TEMPLATE_EN (英語用) に基づいています。これらのテンプレート内のプレースホルダー（{field}, {role}, {language}) が、コマンドライン引数で提供された値に置き換えられます。

  2. 異なるAI APIへの対応:

    • AIのプラットフォームによって最適なメッセージ構築形式が異なるため、選択されたAPIに応じてメッセージ形式を切り替えます。

      • OpenAI API (例: gpt-4o): system ロールと複数の user ロールを組み合わせた会話形式でメッセージを構築します。system メッセージで全体の指示を与え、その後、文字起こしテキスト、スライドMarkdown、最終的な出力形式の指示をそれぞれ user メッセージとして送信します。

      • Google Gemini API (例: gemini-2.5-flash): すべての指示と入力コンテンツを1つの user メッセージにまとめて提供する形式を採用します。これにより、Geminiがシングルターンでの複雑な指示を処理できるようになります。

      • OpenAI Responses API (openai5): 仮のAPIとして想定されており、OpenAIの特定のモデル (openai_model5) に対してメッセージを送信します。

  3. 情報抽出の機構:

    • AIからの応答は、特定のマーカーで囲まれた形式であることを前提としています。具体的には、教科書内容は [TEXTBOOK_START] と [TEXTBOOK_END] で、スライド内容は [SLIDES_START] と [SLIDES_END] で囲まれます。

    • Pythonの正規表現モジュール re を使用して、これらのマーカーパターン $r"\[TEXTBOOK_START\](.*?)\[TEXTBOOK_END\]"$ および $r"\[SLIDES_START\](.*?)\[SLIDES_END\]"$ を適用し、それぞれのコンテンツを正確に抽出します。

  4. 設定ファイルの検索と解析:

    • INIファイル検索: プログラムは、search_file 関数を通じて、指定されたINIファイル（またはデフォルトの make_textbook5.ini）をカレントディレクトリまたはスクリプトが配置されているディレクトリから検索します。

    • INIファイル解析: read_ini 関数は、key=value 形式のINIファイルを読み込み、コメント行や空行をスキップします。また、変数展開（例: $VAR）と、3重引用符で囲まれた複数行の値をサポートします。これにより、長いプロンプトテンプレートなどをINIファイル内に記述できます。

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

このプログラムを実行するには、以下のPythonライブラリが必要です。

  • google-generativeai: Google Gemini APIにアクセスするために使用されます。

  • openai: OpenAI APIにアクセスするために使用されます。

  • python-dotenv: tkai_lib モジュール内で環境変数（APIキーなど）を読み込むために使用されます。

これらのライブラリは、以下の pip コマンドでインストールできます。

pip install google-generativeai openai python-dotenv

必要な入力ファイル

  1. 文字起こしテキストファイル

    • コマンドライン引数: --infile または -i

    • 形式: プレーンテキストファイル (.txt)

    • 内容: 講義の文字起こし内容を記述します。AIが教科書やスライドを作成するための主要な情報源となります。

    • 例: lecture.txt

  2. 講義スライドMarkdownファイル (任意)

    • コマンドライン引数: --in_slide または -im

    • 形式: Markdownファイル (.md)

    • 内容: 既存の講義スライドのMarkdown表現です。AIがこれを基にして、より洗練された新しいスライドMarkdownを生成します。このファイルはオプションです。

    • 例: original_slide.md

  3. INI設定ファイル

    • コマンドライン引数: --inifile (指定がない場合、デフォルトで make_textbook5.ini をカレントディレクトリまたはスクリプトディレクトリから検索します)

    • 形式: key=value 形式のテキストファイル (.ini)

    • 内容: AIへのプロンプトテンプレート (PROMPT_TEMPLATE_JA, PROMPT_TEMPLATE_EN) やその他の設定を定義します。複数行のテキストは、3重引用符（例: key="""複数行の\nテキスト"""）で囲んで記述できます。

    • 例: make_textbook5.ini の一部

    # make_textbook5.ini
PROMPT_TEMPLATE_JA="""
あなたは{field}の{role}です。
以下の情報を元に、{language}で教科書と講義スライドを作成してください。
"""
PROMPT_TEMPLATE_EN="""
You are a {role} of {field}.
Based on the following information, create a textbook and lecture slides in {language}.
"""

  4. AI環境設定ファイル

    • ファイル名: ai.env (このファイルはプログラム内で tkai_lib.read_ai_config によって読み込まれます)

    • 形式: 環境変数を定義するファイル

    • 内容: OpenAIおよびGoogle GeminiのAPIキーなど、AIサービスにアクセスするために必要な認証情報を含めます。

    • 例:

    OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
GOOGLE_API_KEY="AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
OPENAI_MODEL="gpt-4o"
GOOGLE_MODEL="gemini-2.5-flash"

生成される出力ファイル

  1. 教科書Markdownファイル

    • コマンドライン引数: --textbook または -t

    • デフォルト名: 入力ファイル名が [infile].txt の場合、[infile]_textbook.md (例: lecture_textbook.md)

    • 内容: AIによって生成された、講義内容に基づく詳細な教科書形式のMarkdownテキスト。

  2. スライドMarkdownファイル

    • コマンドライン引数: --slide または -s

    • デフォルト名: 入力ファイル名が [infile].txt の場合、[infile]_slide.md (例: lecture_slide.md)

    • 内容: AIによって洗練された、発表に適した形式のスライドMarkdownテキスト。

  3. AIメッセージログファイル

    • デフォルト名: 入力ファイル名が [infile].txt の場合、[infile].log (例: lecture.log)

    • 内容: AIに送信されたメッセージ（プロンプト）のJSON形式のログ。デバッグや検証、プロンプトチューニングのために利用されます。

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

python make_textbook5.py [-h] [--inifile INIFILE] [-i INFILE] [-im IN_SLIDE] [-t TEXTBOOK] [-s SLIDE]
                         [--api {gemini,openai5,openai,google}] [--model MODEL] [--openai_model OPENAI_MODEL]
                         [--openai_model5 OPENAI_MODEL5] [--google_model GOOGLE_MODEL] [--lang {ja,en,zh,ko}]
                         [--field FIELD] [--role ROLE] [--pause PAUSE]

引数の説明:

  • -h, --help: ヘルプメッセージを表示して終了します。

  • --inifile INIFILE: プロンプトなどを保存した設定ファイル (デフォルト: make_textbook5.ini)。

  • -i INFILE, --infile INFILE: 文字起こしテキストファイル (例: lecture.txt)。

  • -im IN_SLIDE, --in_slide IN_SLIDE: 入力講義スライドMarkdownファイル (任意, 例: slide.md)。

  • -t TEXTBOOK, --textbook TEXTBOOK: 出力する教科書Markdownファイルのパス (デフォルト: [infile]_textbook.md)。

  • -s SLIDE, --slide SLIDE: 出力するスライドMarkdownファイルのパス (デフォルト: [infile]_slide.md)。

  • --api {gemini,openai5,openai,google}: 使用するAI APIの選択 (デフォルト: gemini)。

    • gemini または google: Google Gemini APIを使用。

    • openai: OpenAI Chat Completions APIを使用。

    • openai5: 仮のOpenAI Responses APIを使用。

  • --model MODEL: 明示的にモデル名を指定します (APIごとに適用先が切り替わります)。

  • --openai_model OPENAI_MODEL: OpenAIのチャット補完モデル (デフォルト: gpt-4o または環境変数 OPENAI_MODEL)。

  • --openai_model5 OPENAI_MODEL5: OpenAIの仮のResponses APIモデル (デフォルト: gpt-5.2 または環境変数 OPENAI_MODEL5)。

  • --google_model GOOGLE_MODEL: Google Geminiモデル (デフォルト: gemini-2.5-flash または環境変数 GOOGLE_MODEL)。

  • --lang {ja,en,zh,ko}: 出力言語 (デフォルト: ja)。

  • --field FIELD: 専門分野 (デフォルト: 半導体工学)。

  • --role ROLE: AIの役割 (デフォルト: 大学教授)。

  • --pause PAUSE: 終了時にEnterキー入力を要求するか (0: 要求しない, 1: 要求する, デフォルト: 0)。

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

以下の例では、lecture.txt という文字起こしテキストと original_slide.md という既存のスライドMarkdownを入力として、Google Gemini API (gemini-2.5-flash) を使用し、日本語で「量子コンピューティング」の「研究者」の役割で、教科書とスライドを生成します。

前提:

  • カレントディレクトリに lecture.txt と original_slide.md が存在します。

  • ai.env ファイルに GOOGLE_API_KEY が適切に設定されています。

  • make_textbook5.ini ファイルに PROMPT_TEMPLATE_JA が定義されています。

実行コマンド:

python make_textbook5.py -i lecture.txt -im original_slide.md \
  -t textbook_output.md -s slide_output.md \
  --api gemini --google_model gemini-2.5-flash \
  --lang ja --field 量子コンピューティング --role 研究者 --pause 1

実行結果の説明:

  1. 標準出力:

    • make_textbook5.ini が読み込まれたことが表示されます。

    • 入力ファイル (lecture.txt, original_slide.md) が読み込まれたことが表示されます。

    • Gemini API [gemini-2.5-flash] を呼び出しています... のように、AI API呼び出しの進行状況が表示されます。

    • 📝 messagesログを 'lecture.log' に保存しました というメッセージが表示され、AIに送信されたプロンプトがJSON形式で保存されたことが示されます。

    • ✅ 教科書ファイル 'textbook_output.md' を生成

    • ✅ スライドファイル 'slide_output.md' を生成

    • 最後に --pause 1 が指定されているため、Press ENTER to terminate>> と表示され、ユーザーがEnterキーを押すまでプログラムが終了しません。

  2. 生成されるファイル:

    • textbook_output.md: lecture.txt と original_slide.md の内容に基づき、AIが「量子コンピューティングの研究者」という役割で生成した日本語の教科書Markdownファイル。

    • slide_output.md: 同様にAIが生成した、洗練された日本語のスライドMarkdownファイル。

    • lecture.log: AIに送信された、すべてのプロンプト（システム指示、文字起こしテキスト、スライドMarkdown、最終指示）を含むJSON形式のファイル。これはデバッグやAIの応答を理解するために役立ちます。