技術ドキュメント: make_textbook5.py
プログラムの動作
make_textbook5.py は、講義の文字起こしテキストと、オプションで提供されるスライドのMarkdownファイルを統合し、AI（大規模言語モデル）の力を借りて教科書形式のMarkdownファイルと、より整理されたスライド形式のMarkdownファイルを生成するPythonスクリプトです。このプログラムは、教育資料の作成プロセスを効率化し、手動での編集作業を大幅に削減することを目的としています。
主な機能:
入力処理: 講義の文字起こしテキストと、既存の講義スライド（Markdown形式）をAIへの入力として利用します。
AI APIの選択: OpenAI (GPTシリーズ) と Google Gemini API の両方に対応しており、コマンドライン引数でどちらを使用するか選択できます。
メッセージ構築の自動分岐: 選択されたAI APIに応じて、
system+userの会話形式（OpenAI）または単一のuserメッセージ形式（Google Gemini）でAIに渡すプロンプトメッセージを自動的に構築します。多言語対応: 生成する出力ファイルの言語（日本語、英語、標準中国語、韓国語）を指定できます。
プロンプトの詳細設定: 専門分野やAIに与える役割（例: 大学教授）を設定することで、より高品質で専門性の高い出力を引き出します。
ログ保存: AIに送信される全メッセージ内容をJSON形式でログファイルに保存し、デバッグや検証に役立てます。
出力形式の統一: AIからの応答から教科書とスライドの内容を抽出し、指定されたファイル名で保存します。
解決する課題:
文字起こしデータとスライド情報を元に、手動で教科書やスライドを再構成する手間を省きます。
専門分野や対象読者に合わせた質の高い教材を効率的に生成します。
複数言語での教材作成ニーズに対応します。
原理
make_textbook5.py は、大規模言語モデル (LLM) を活用したプロンプトエンジニアリングに基づいています。
設定とプロンプトの読み込み:
プログラムは、
make_textbook5.iniのようなINIファイルからプロンプトテンプレート（日本語用PROMPT_TEMPLATE_JAと英語用PROMPT_TEMPLATE_EN）を読み込みます。このINIファイルは、AIに与えるsystem_instructionsの基盤となります。INIファイルは
$VARNAME形式の変数展開もサポートしています。
AIへの指示の構築:
ユーザーが指定した専門分野 (
--field)、役割 (--role)、出力言語 (--lang) の情報をINIファイルから読み込んだテンプレートに埋め込み、AIに対する具体的なsystem_instructionsを生成します。 $\( \text{system\_instructions} = \text{PROMPT\_TEMPLATE}\_\text{LANG} \\ \quad \cdot \text{replace}(\text{"\{field\}", args.field}) \\ \quad \cdot \text{replace}(\text{"\{role\}", args.role}) \\ \quad \cdot \text{replace}(\text{"\{language\}", language}) \)$さらに、AIが教科書とスライドの内容を明確に区別して出力できるように、以下の最終指示を組み込みます。
[TEXTBOOK_START] （教科書の内容） [TEXTBOOK_END] [SLIDES_START] （スライドの内容） [SLIDES_END]
APIに応じたメッセージ形式の構築:
OpenAI API (gpt-4o, gpt-5.2など):
build_messages関数は、systemロールとuserロールを使い分けた会話形式のリストを作成します。最初のメッセージ:
{"role": "system", "content": system_instructions}文字起こしテキストがある場合:
{"role": "user", "content": "# 文字起こしテキスト\n\n{lecture_text}"}スライドMarkdownがある場合:
{"role": "user", "content": "# 講義スライド\n\n{slide_markdown}"}最後のメッセージ:
{"role": "user", "content": final_instruction}
Google Gemini API (gemini-2.5-flashなど):
build_messages関数は、すべての指示内容を1つのuserメッセージにまとめて渡します。{"role": "user", "content": "\n\n".join([system_instructions, lecture_text_part, slide_markdown_part, final_instruction])}
AIへのリクエストと応答の処理:
構築されたメッセージリストは、選択されたAI API（OpenAIまたはGoogle Gemini）に送信されます。
AIからの応答は単一の文字列として受け取られます。
この応答文字列から、正規表現
re.searchを使用して[TEXTBOOK_START]と[TEXTBOOK_END]の間、および[SLIDES_START]と[SLIDES_END]の間のテキストを抽出し、それぞれ教科書とスライドのMarkdownファイルとして保存します。
このプロセスにより、入力された講義内容とスライド情報がAIによって解釈され、指定された形式とスタイルで新しい教材として再構築されます。
必要な非標準ライブラリとインストール方法
このプログラムの実行には、以下のPythonライブラリが必要です。
google-generativeai: Google Gemini API を利用するために必要です。openai: OpenAI API を利用するために必要です。python-dotenv: 環境変数（APIキーなど）を読み込むためにtkai_lib内で使用されている可能性があります。
これらのライブラリは pip コマンドでインストールできます。
pip install google-generativeai openai python-dotenv
必要な入力ファイル
プログラムの実行には、以下のファイルが期待されます。
文字起こしテキストファイル (
--infileまたは-i):形式: プレーンテキストファイル（例:
.txt）。内容: 講義の文字起こし内容を記述します。AIがこのテキストを解析し、教科書やスライドの内容を生成する際の主要な情報源となります。
例:
lecture.txt
講義スライドMarkdownファイル (
--in_slideまたは-im):形式: Markdownファイル（例:
.md）。内容: 既存の講義スライドの内容をMarkdown形式で記述します。このファイルはオプションですが、提供することでAIがより構造化された情報を参照し、高品質な出力を生成する助けとなります。
例:
slide.md
INI設定ファイル (
--inifile):形式:
key=val形式のテキストファイル（例:.ini）。内容: AIへのプロンプトテンプレート（
PROMPT_TEMPLATE_JA,PROMPT_TEMPLATE_EN）、デフォルトの専門分野、役割などの設定が含まれます。配置:
--inifileオプションで明示的に指定しない場合、プログラムはスクリプトと同じディレクトリまたは現在の作業ディレクトリでmake_textbook5.iniという名前のファイルを検索します。例 (
make_textbook5.ini):# 日本語プロンプトテンプレート PROMPT_TEMPLATE_JA = """あなたは、{field} の{role}です。 以下の指示に従い、講義の文字起こしテキストとスライド情報から、{language}の教科書とスライドを作成してください。 制約条件: - 専門用語の正確な使用。 - 自然で理解しやすい文章。 - 教科書は詳細に、スライドは簡潔にまとめる。 - 教科書とスライドの両方で、Markdown形式を使用してください。 """ # 英語プロンプトテンプレート PROMPT_TEMPLATE_EN = """You are a {role} of {field}. Based on the transcribed lecture text and slide information, create a textbook and slides in {language} according to the following instructions. Constraints: - Use technical terms accurately. - Write in natural and easy-to-understand language. - The textbook should be detailed, and the slides should be concise. - Use Markdown format for both the textbook and slides. """
環境変数ファイル (
.envファイル):tkai_lib.read_ai_config('ai.env')関数がai.envファイルまたは.envファイルを読み込み、APIキーを設定することが想定されます。内容: AI APIの認証情報（例:
OPENAI_API_KEY,GOOGLE_API_KEY）を格納します。例 (
ai.env):OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" GOOGLE_API_KEY="AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
生成される出力ファイル
プログラムは、AIの処理結果として以下のファイルを生成します。
教科書Markdownファイル:
ファイル名:
--textbook <ファイル名>オプションで指定された場合、そのファイル名。指定がない場合、
--infileで指定された入力ファイルのベース名に_textbook.mdを付加したもの（例:lecture.txtの場合lecture_textbook.md）。--infileも指定されていない場合はoutput_textbook.md。
内容: AIによって生成された、詳細な教科書形式のMarkdownテキスト。
スライドMarkdownファイル:
ファイル名:
--slide <ファイル名>オプションで指定された場合、そのファイル名。指定がない場合、
--infileで指定された入力ファイルのベース名に_slide.mdを付加したもの（例:lecture.txtの場合lecture_slide.md）。--infileも指定されていない場合はoutput_slide.md。
内容: AIによって生成された、簡潔なスライド形式のMarkdownテキスト。
AIメッセージログファイル:
ファイル名:
--infileで指定された入力ファイルのベース名に.logを付加したもの（例:lecture.txtの場合lecture.log）。--infileが指定されていない場合はoutput.log。
内容: プログラムがAI APIに送信した
messagesの内容をJSON形式で保存したもの。AIへの指示がどのように構築されたかを確認するためのデバッグやトレースに役立ちます。
コマンドラインでの使用例 (Usage)
make_textbook5.py スクリプトは、以下のコマンドライン引数をサポートしています。
usage: make_textbook5.py [-h] [--inifile INIFILE] [-i INFILE] [-im IN_SLIDE] [-t TEXTBOOK] [-s SLIDE]
[-a {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]
講義の文字起こしとスライドをAIで教科書/スライドMarkdownに変換（Pandoc不要）。
options:
-h, --help show this help message and exit
--inifile INIFILE プロンプトなどを保存したkey=valファイル
-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)
AI設定:
-a {gemini,openai5,openai,google}, --api {gemini,openai5,openai,google}
使用API
--model MODEL 明示モデル名の指定（apiごとに適用先を切替）
--openai_model OPENAI_MODEL
--openai_model5 OPENAI_MODEL5
--google_model GOOGLE_MODEL
--lang {ja,en,zh,ko} 出力言語 (デフォルト ja)
--field FIELD 専門分野
--role ROLE 役割
--pause PAUSE 終了時にENTERキー入力を要求するか (デフォルト: 0)
コマンドラインでの具体的な使用例
ここでは、make_textbook5.py の具体的な使用例をいくつか紹介します。
事前準備
ai.env と make_textbook5.ini ファイルをスクリプトと同じディレクトリに配置してください。
ai.env の内容例:
OPENAI_API_KEY="sk-..."
GOOGLE_API_KEY="AIzaSy..."
make_textbook5.ini の内容例:
# 日本語プロンプトテンプレート
PROMPT_TEMPLATE_JA = """あなたは、{field} の{role}です。
以下の指示に従い、講義の文字起こしテキストとスライド情報から、{language}の教科書とスライドを作成してください。
制約条件:
- 専門用語の正確な使用。
- 自然で理解しやすい文章。
- 教科書は詳細に、スライドは簡潔にまとめる。
- 教科書とスライドの両方で、Markdown形式を使用してください。
"""
# 英語プロンプトテンプレート (英語出力の場合のみ使用)
PROMPT_TEMPLATE_EN = """You are a {role} of {field}.
Based on the transcribed lecture text and slide information, create a textbook and slides in {language} according to the following instructions.
Constraints:
- Use technical terms accurately.
- Write in natural and easy-to-understand language.
- The textbook should be detailed, and the slides should be concise.
- Use Markdown format for both the textbook and slides.
"""
例1: 日本語で教科書とスライドを生成（Google Gemini APIを使用）
lecture.txt (文字起こしテキスト) と slide.md (スライドMarkdown) を入力とし、日本語で教科書とスライドを生成します。専門分野を「情報科学」、役割を「高校教師」と指定します。
入力ファイル例:
lecture.txt:今日の講義では、AIの基本的な概念について学びます。AIはArtificial Intelligenceの略で、人間のような知能を持つ機械やソフトウェアを指します。主な種類としては、機械学習や深層学習があります。機械学習はデータからパターンを学習し予測を行う技術で、深層学習はニューラルネットワークを多層にしたものです。
slide.md:# AIの基本概念 ## 1. AIとは？ - Artificial Intelligenceの略 - 人間のような知能を持つ機械やソフトウェア ## 2. AIの種類 - 機械学習 (Machine Learning) - データからパターンを学習 - 予測や分類 - 深層学習 (Deep Learning) - 機械学習の一分野 - 多層ニューラルネットワーク
実行コマンド:
python make_textbook5.py -i lecture.txt -im slide.md -a gemini --lang ja --field "情報科学" --role "高校教師"
実行結果の説明:
lecture_textbook.mdというファイルが生成され、AIによって再構成された詳細な教科書内容（Markdown形式）が記述されます。lecture_slide.mdというファイルが生成され、AIによって整理されたスライド内容（Markdown形式）が記述されます。lecture.logというファイルが生成され、AIに送信されたプロンプトメッセージがJSON形式で保存されます。
例2: 英語で教科書とスライドを生成し、出力ファイル名を指定（OpenAI APIを使用）
speech.txt と presentation.md を入力とし、英語で教科書とスライドを生成します。出力ファイル名を quantum_textbook.md と quantum_slides.md に指定し、OpenAI APIを使用します。
実行コマンド:
python make_textbook5.py -i speech.txt -im presentation.md -t quantum_textbook.md -s quantum_slides.md -a openai --lang en --field "Quantum Physics" --role "University Professor"
実行結果の説明:
quantum_textbook.mdというファイルが生成され、英語の教科書内容が出力されます。quantum_slides.mdというファイルが生成され、英語のスライド内容が出力されます。speech.logというファイルが生成され、OpenAI APIに送信されたプロンプトメッセージがJSON形式で保存されます。
例3: 特定のINIファイルを使用し、終了時に一時停止
custom_prompts.ini という独自のINIファイルを使用し、AIモデルとしてGoogle Geminiの gemini-pro を明示的に指定します。処理終了時にEnterキー入力を要求するように --pause 1 を設定します。
実行コマンド:
python make_textbook5.py -i lesson.txt --inifile custom_prompts.ini -a gemini --model gemini-pro --lang ja --field "宇宙工学" --pause 1
実行結果の説明:
lesson.txtを入力として、custom_prompts.iniに定義されたプロンプトテンプレートが適用されます。lesson_textbook.mdとlesson_slide.mdが生成されます。AIモデルには
gemini-proが使用されます。プログラム終了時に「Press ENTER to terminate>>」というメッセージが表示され、ユーザーの入力を待ってから終了します。