make_textbook5.py 技術ドキュメント

プログラムの動作

make_textbook5.py は、AI処理を活用して、講義の文字起こしテキストとスライドのMarkdownファイルから、教科書用の詳細なMarkdownと、講義スライド用の簡潔なMarkdownを自動生成するPythonプログラムです。

主な機能:

  • AI統合インターフェース: LiteLLMライブラリを介して、OpenAI (GPTシリーズ)、Google (Gemini)、LM Studioなどの複数の大規模言語モデル (LLM) プロバイダーを統一的なインターフェースで利用できます。

  • 柔軟なプロンプト構築: INIファイルからプロンプトテンプレートを読み込み、専門分野、役割、出力言語などのパラメータを動的に埋め込むことで、AIへの指示を柔軟にカスタマイズできます。

  • 多言語対応: 日本語、英語、標準中国語、韓国語でのテキスト生成をサポートします。

  • 明確な出力形式: AIからの応答は、教科書内容とスライド内容が明確に分離された形式([TEXTBOOK_START]...[TEXTBOOK_END], [SLIDES_START]...[SLIDES_END]) で抽出され、それぞれ別のファイルに保存されます。

  • ログ記録: AIへの入力メッセージ(プロンプト)は、デバッグや履歴管理のためにJSON形式で .log ファイルに保存されます。

解決する課題:

  • 手作業での講義内容のテキスト化や、既存のスライドからの教科書・補足資料作成にかかる時間と労力を大幅に削減します。

  • 多様な形式の講義資料(文字起こし、既存スライド)を一貫した品質と形式のMarkdownコンテンツに変換するプロセスを自動化します。

  • 異なるAIモデルの特性を活かしつつ、開発者が単一のスクリプトで複数のLLMを試せる柔軟性を提供します。

原理

このプログラムは、大規模言語モデル (LLM) の高度なテキスト生成能力を利用して、入力された講義情報から構造化されたMarkdownドキュメントを生成します。その中心的なアルゴリズムは以下のステップで構成されます。

  1. 入力と設定の読み込み:

    • コマンドライン引数から、文字起こしテキストファイル (--infile)、既存のスライドMarkdownファイル (--in_slide、任意)、AI APIの選択、モデル名、出力言語、専門分野、役割などの各種設定を解析します。

    • プロンプトテンプレートは、make_textbook5.ini のようなINIファイルから読み込まれます。このファイルには、AIに与える指示の骨格が、プレースホルダ ({field}, {role}, {language}) を含んだ形で定義されています。

    • AIのAPIキーなどの認証情報は、ai.env ファイルから環境変数として読み込まれます。

  2. プロンプトの動的構築:

    • 読み込んだプロンプトテンプレートのプレースホルダに、コマンドライン引数で指定された値(例: --field "半導体工学", --role "大学教授", --lang "ja" から「日本語」)を埋め込み、AIに対するシステム命令文を生成します。

    • 入力された文字起こしテキストとスライドMarkdownは、AIが解釈しやすいように整形され、ユーザーからの指示メッセージとしてシステム命令文に追加されます。

    • AIからの応答が特定の形式であることを保証するため、出力形式の指示 (例: [TEXTBOOK_START]...[TEXTBOOK_END], [SLIDES_START]...[SLIDES_END]) が最終的なユーザーメッセージに含められます。

  3. AIへのクエリ実行:

    • 構築されたシステム命令とユーザーメッセージは、tkai_lib_litellm モジュールを介してLiteLLMライブラリに渡されます。

    • LiteLLMは、選択されたAI API (OpenAI, Gemini, LM Studio) に応じて、メッセージの形式を自動的に調整します。例えば、OpenAI系のAPIでは会話履歴形式を、Gemini系のAPIでは単一のユーザーメッセージに全てをまとめる形式を採用します。

    • LM StudioでQwen3.8などの特定のモデルを使用する場合、--reasoning-effort のようなモデル固有のパラメータを extra_body としてLiteLLM経由でAIに渡すことができます。

  4. 応答の解析とファイル出力:

    • AIからの応答テキストが返された後、正規表現を用いて[TEXTBOOK_START] と [TEXTBOOK_END] の間の内容が教科書用Markdownとして、[SLIDES_START] と [SLIDES_END] の間の内容がスライド用Markdownとしてそれぞれ抽出されます。

    • 抽出された内容は、指定された出力ファイル名でそれぞれディスクに保存されます。

    • AIに送信された完全なメッセージリストは、デバッグ目的でJSON形式の .log ファイルに保存されます。

このプロセスにより、人間が手作業で行うには時間と専門知識が必要な、講義内容の再構築と形式化が自動化され、効率的なコンテンツ生成が可能になります。

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

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

  • litellm: 複数の大規模言語モデル (LLM) プロバイダー(OpenAI, Google Gemini, LM Studioなど)を統一的なインターフェースで利用するためのライブラリです。

  • python-dotenv: .env ファイルから環境変数を読み込み、APIキーなどの機密情報を安全に管理するために使用されます。

また、本プログラムは、カスタムライブラリである tkai_lib_litellm.py に依存しています。このファイルは、本プログラムと同じディレクトリか、Pythonの検索パスが通っている場所に配置されている必要があります。

インストール方法:

以下のコマンドを実行して、必要なライブラリをインストールしてください。

pip install litellm python-dotenv

必要な入力ファイル

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

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

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

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

  2. 講義スライドMarkdownファイル (--in_slide, 例: slide.md):

    • 形式: Markdownファイル

    • 内容: 任意。既存の講義スライドの内容をMarkdown形式で記述したものです。このファイルが提供されると、AIはこれを参考に、より内容が豊富な教科書やスライドを生成できます。省略した場合、文字起こしテキストのみを基に生成されます。

  3. INI設定ファイル (--inifile, デフォルト: make_textbook5.ini):

    • 形式: key=val 形式のテキストファイル

    • 内容: AIへのプロンプトテンプレートやその他の設定を定義します。最低限、PROMPT_TEMPLATE_JA (日本語プロンプト) と、英語出力を使用する場合は PROMPT_TEMPLATE_EN (英語プロンプト) が必要です。

    INIファイルの例:

    PROMPT_TEMPLATE_JA = """
    あなたは{field}の{role}です。
    以下の文字起こしテキストとスライドを基に、{language}の教科書とスライドを作成してください。
    教科書は詳細に、スライドは箇条書きと簡潔な説明にしてください。
    """
    PROMPT_TEMPLATE_EN = """
    You are a {role} of {field}.
    Based on the following transcription and slides, create a textbook and slides in {language}.
    Make the textbook detailed and the slides concise with bullet points.
    """
    

    複数行の値を指定する際には、Pythonの3重引用符に似た """ または ''' を使用できます。これは、値の開始と終了を示すためのものです。 例:

    LONG_TEXT = """
    これは
    複数行にわたる
    長いテキストです。
    """
    
  4. AI設定ファイル (ai.env):

    • 形式: .env 形式のテキストファイル

    • 内容: 各AIプロバイダーのAPIキーやエンドポイントなどの認証情報を環境変数として定義します。このファイルはプログラム実行ディレクトリに置くか、LiteLLMがサポートする方法で読み込まれる必要があります。

    ai.env の例:

    OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    GOOGLE_API_KEY="AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    # LM Studio を使用する場合、通常はAPIキーは不要ですが、エンドポイントを指定できます
    # LMSTUDIO_BASE_URL="http://localhost:1234/v1"
    

生成される出力ファイル

プログラムは、実行結果として以下のファイルを生成します。

  1. 教科書Markdownファイル (--textbook, デフォルト: [infile]_textbook.md):

    • 形式: Markdownファイル

    • 内容: AIが文字起こしテキストやスライドを基に生成した、詳細な教科書の内容が含まれます。ファイル名は、入力ファイル名 (例: lecture.txt なら lecture_textbook.md) を基に自動決定されるか、--textbook オプションで明示的に指定されます。

  2. スライドMarkdownファイル (--slide, デフォルト: [infile]_slide.md):

    • 形式: Markdownファイル

    • 内容: AIが文字起こしテキストやスライドを基に生成した、簡潔なスライドの内容が含まれます。ファイル名は、教科書ファイルと同様に自動決定されるか、--slide オプションで明示的に指定されます。

  3. AIメッセージログファイル ([infile].log):

    • 形式: JSONファイル

    • 内容: AIに送信された完全なメッセージのやり取り(システムプロンプト、ユーザープロンプト)がJSON形式で記録されます。これは、AIの応答が期待と異なる場合のデバッグや、過去のAIとの対話履歴を確認する際に有用です。ファイル名は、入力ファイル名 (例: lecture.txt なら lecture.log) を基に自動決定されます。

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

make_textbook5.py は、以下のコマンドライン引数を受け付けます。

python make_textbook5.py [-h] [--inifile INIFILE] [-i INFILE] [-im IN_SLIDE] [-t TEXTBOOK] [-s SLIDE]
                         [--api {gemini,openai5,openai,google,lmstudio}] [--model MODEL] [--openai_model OPENAI_MODEL]
                         [--openai_model5 OPENAI_MODEL5] [--google_model GOOGLE_MODEL] [--lmstudio_model LMSTUDIO_MODEL]
                         [--reasoning-effort {low,medium,xhigh}] [--lang {ja,en,zh,ko}] [--field FIELD] [--role ROLE]
                         [--pause PAUSE]
  • -h, --help: ヘルプメッセージを表示して終了します。

  • --inifile INIFILE: プロンプトテンプレートなどを保存したINIファイルのパス。

  • -i INFILE, --infile INFILE: 文字起こしテキストファイルへのパス (例: lecture.txt)。必須(-im とどちらか一つ)。

  • -im IN_SLIDE, --in_slide IN_SLIDE: 入力する既存の講義スライドMarkdownファイルへのパス (任意, 例: slide.md)。必須(-i とどちらか一つ)。

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

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

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

    • gemini / google: Google Gemini APIを使用します。

    • openai / openai5: OpenAI APIを使用します。openai5 は gpt-5.4 モデルをデフォルトとします。

    • lmstudio: LM Studioを介してローカルモデルを使用します。

  • --model MODEL: AIモデル名を明示的に指定します。このオプションを使用すると、--openai_model などのAPI固有のモデル設定が上書きされます。

  • --openai_model OPENAI_MODEL: OpenAI APIで使用するモデル名 (デフォルト: gpt-4o)。

  • --openai_model5 OPENAI_MODEL5: OpenAI APIで使用する新しいモデル名 (デフォルト: gpt-5.4)。

  • --google_model GOOGLE_MODEL: Google Gemini APIで使用するモデル名 (デフォルト: gemini-3.1-pro-preview)。

  • --lmstudio_model LMSTUDIO_MODEL: LM Studioで使用するモデル名 (省略時: qwen/qwen3.8-27b)。

  • --reasoning-effort {low,medium,xhigh}: LM StudioのQwen3.8モデルなどで利用可能な推論量設定 (省略時はモデル既定値)。--api lmstudio と組み合わせて使用する必要があります。

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

    • ja, jp: 日本語

    • en: 米国英語

    • zh, cn: 標準中国語

    • ko, kr: 韓国語

  • --field FIELD: AIに設定する専門分野 (デフォルト: 半導体工学)。

  • --role ROLE: AIに設定する役割 (デフォルト: 大学教授)。

  • --pause PAUSE: プログラム終了時にENTERキー入力を要求するかどうか (デフォルト: 0 (しない))。

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

例1: 日本語で教科書とスライドを生成(Gemini使用)

lecture.txt の文字起こしと slide.md の既存スライドを基に、日本語の教科書とスライドを生成します。AIには「半導体物理」の「研究者」としての役割を与えます。出力ファイル名を明示的に指定します。

入力ファイル (lecture.txt):

今日の講義では、半導体の基本について説明します。半導体は、電気を通す導体と電気を通さない絶縁体の中間の性質を持つ物質です。その代表例がシリコンです。

入力ファイル (slide.md):

# 半導体の基礎

## 半導体とは
* 導体と絶縁体の中間の性質
* 例: シリコン (Si)

INIファイル (make_textbook5.ini):

PROMPT_TEMPLATE_JA = """
あなたは{field}の{role}です。
以下の文字起こしテキストとスライドを基に、{language}の教科書とスライドを作成してください。
教科書は詳細に、スライドは箇条書きと簡潔な説明にしてください。
"""
PROMPT_TEMPLATE_EN = """
You are a {role} of {field}.
Based on the following transcription and slides, create a textbook and slides in {language}.
Make the textbook detailed and the slides concise with bullet points.
"""

コマンド:

python make_textbook5.py -i lecture.txt -im slide.md --api gemini --field "半導体物理" --role "研究者" -t my_textbook.md -s my_slide.md

実行結果:

  • my_textbook.md: lecture.txtとslide.mdの内容を元にした、より詳細な教科書Markdownが生成されます。

  • my_slide.md: lecture.txtとslide.mdの内容を元にした、簡潔なスライドMarkdownが生成されます。

  • lecture.log: AIに送信されたメッセージがJSON形式で記録されます。

例2: 英語で教科書を生成(OpenAI GPT-4o使用、スライド入力なし)

introduction.txt の文字起こし内容を基に、英語の教科書のみを生成します。スライド入力はないため、AIは文字起こしテキストのみを参考にします。出力ファイル名はデフォルトの命名規則に従います。

入力ファイル (introduction.txt):

Today's topic is an introduction to artificial intelligence. AI is a broad field of computer science concerned with building smart machines capable of performing tasks that typically require human intelligence.

コマンド:

python make_textbook5.py -i introduction.txt --lang en --api openai --openai_model gpt-4o --field "情報科学" --role "講師"

実行結果:

  • introduction_textbook.md: introduction.txtの内容を元にした、英語の教科書Markdownが生成されます。

  • introduction.log: AIに送信されたメッセージがJSON形式で記録されます。

  • スライド出力ファイル (introduction_slide.md) は指定されていないため、生成されません。

例3: LM Studio (Qwen3.8) を使用し、推論量を指定して教科書とスライドを生成

ローカルで動作するLM StudioのQwen3.8モデルを利用し、推論量を xhigh に設定して、日本語の教科書とスライドを生成します。

コマンド:

python make_textbook5.py -i lecture.txt -im slide.md --api lmstudio --lmstudio_model qwen/qwen3.8-27b --reasoning-effort xhigh --field "機械学習" --role "技術者"

実行結果:

  • lecture_textbook.md: AIによって生成された教科書Markdown。

  • lecture_slide.md: AIによって生成されたスライドMarkdown。

  • lecture.log: AIに送信されたメッセージがJSON形式で記録されます。