メインコンテンツへ移動
AIチュートリアル

BookLemeチュートリアル：本をインストール可能で検証可能なAgent Skillにコンパイルする

本チュートリアルでは、BookLemeのインストールと使用方法を解説します。書籍のフレームワーク、プロセス、作業手法を構造化されたナレッジパッケージまたは実行可能な行動Skillにコンパイルし、ジャンルルーティング、成果物の検証、中断地点からの再開、著作権チェックまで行います。

約17分で読了
BookLemeチュートリアル：本をインストール可能で検証可能なAgent Skillにコンパイルする

BookLemeとは

BookLeme（中国語名「读了么」）は、書籍をAgent Skillにコンパイルするツールチェーンです。一般的な要約の生成ではなく、書籍に含まれる実践方法、たとえば質問の順序、判断条件、証拠のルール、プロセスの状態、不適用となる境界などを抽出し、インストール、呼び出し、検証が可能な成果物として構成することに重点を置いています。

このプロジェクトでは、書籍の処理をコンパイル時と実行時に分けています。コンパイル時に原書を読み込んで処理し、実行時には生成済みの知識分片を必要に応じて読み込みます。これにより、Skillを呼び出すたびに本全体を再読み込みする必要がなくなります。

注意：「要約ではなく構造を抽出する」という方針は、プロジェクトが採用している工学的な設計上の選択です。ただし、READMEでは、これはプロジェクトによってまだ検証されていない仮説であり、確認済みの結論ではないと明記されています。

BookLemeが生成するもの

BookLemeには2つの生成エンジンがあります。両者は抽出段階と検証段階の中間表現を共有し、レンダリング段階でのみ分岐します。そのため、2種類の成果物を同時に生成する場合でも、1冊の本を2回処理する必要はありません。

知識パッケージ knowledge_pack

知識パッケージは、参照用の構造化知識ベースです。主にTopic Indexルーティング表、必要に応じて読み込むフレームワーク分片、意思決定用クイックリファレンス、出典一覧で構成されます。「本にあるフレームワークをどのように使うか」といった質問への回答に適しています。

行動Skill behavior_skill

行動Skillは、完全なプロセスを実行するために使用します。役割定義、厳格な制約、状態機械、名前付き出力契約、アンチパターン、感情面のガードレールなどを含めることができます。知識の検索だけでなく、コーチング対話のような複数ステップのタスクの実行に適しています。

主な特長

  • 2エンジンの自動ルーティング：12個の決定論的なジャンル特徴に基づいて、知識パッケージまたは行動Skillを選択します。エンジンを手動で指定することもできます。
  • プラグイン可能なジャンル拡張：新しいジャンルを追加する際は、コアパイプラインを変更せず、ユーザープラグインディレクトリにPythonファイルを1つ追加できます。
  • 逐語的忠実性の再検証：引用は原文に含まれる完全一致の部分文字列でなければならず、複数の測定可能な指標で検査されます。
  • 著作権ハードゲート：インストールおよび公開前に決定論的な著作権チェックを実行します。第三者の書籍から生成したSkillは、デフォルトで非公開のまま保持されます。
  • 実行時の第三者依存ゼロ：コア実装ではPython標準ライブラリのみを使用します。
  • ステージ単位の冪等性：パイプラインはSHA-256を使って再実行をサポートします。あるステージの成果物を削除した場合は、そのステージだけを再実行できます。

インストールと環境準備

BookLemeにはPython 3.9以降が必要です。リポジトリをクローンした後は、第三者の実行時依存関係を先にインストールしなくても、Pythonモジュールのエントリーポイントから直接実行できます。

git clone https://github.com/bookleme/bookleme.git
cd bookleme
python3 -m bookleme --version

コマンドでバージョン情報が出力されれば、基本環境は利用可能です。リポジトリはPDF、EPUB、DOCX、Markdown、HTML、RTF、MOBIなどの入力形式に対応しています。以下では、プロジェクトに付属するMarkdownの合成原稿を使って、完全な処理フローを説明します。

初回コンパイル：原稿からSkillを生成する

runサブコマンドを実行し、--inputで原稿を指定し、--titleでタイトルを設定します。

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "私の最初の本"

デフォルトでは、BookLemeが原稿のジャンル特徴を分析し、適切な生成エンジンを自動選択します。コンパイルは、入力登録、テキスト抽出、中国語分割、ジャンルルーティング、原子能力抽出、忠実度検証、レンダリング、総合検証、インストール、スモーク評価などのステージを経て実行されます。

推奨：初めて試すときは、リポジトリに用意された合成テスト原稿を使用してください。第三者の書籍を処理する前に、適切な利用権を保有していることを確認し、生成物の配布制限を理解してください。

生成エンジンを選択する

--engineを使って出力タイプを制御できます。

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "コーチング対話の例" \
  --engine behavior_skill

指定できる値は次のとおりです。

  • auto：ルーターに自動選択させます。
  • knowledge_pack：構造化知識パッケージのみを生成します。
  • behavior_skill：実行可能な行動Skillのみを生成します。
  • both：2種類の成果物を同時に生成します。

ルーティングを無効にして、2つのエンジンからすべて出力したい場合は、--no-routerを使用します。

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "2エンジンの例" \
  --no-router

ジャンルプラグインを指定する

ジャンルプラグインは、成果物の状態機械、出力契約、厳格な制約、表現方法を決定します。現在実装されているプラグインは次のとおりです。

  • coach_dialogue：コーチングまたは自己対話向け。一問一答の状態機械、感情面のガードレール、中断、対話の再開に対応します。
  • knowledge_reference：フレームワークのクイックリファレンス向け。Topic Indexで内容をルーティングし、本にない情報については必ず回答を拒否します。

professional_analysisとdecision_checklistは、後続のM4ロードマップに含まれる項目であり、現時点で完成済みの機能とみなしてはいけません。

--genreで実装済みのプラグインを強制的に選択できます。

python3 -m bookleme run \
  --input evals/cases/synthetic/coach_book.md \
  --title "人生設計対話" \
  --engine behavior_skill \
  --genre coach_dialogue

生成物を検証する

生成が完了したら、プロジェクトが提供する検証コマンドで成果物を確認します。READMEではexamples/coachを例にしています。

python3 -m bookleme validate examples/coach

このステップでは、公式バリデーター、独自lint、著作権ハードゲートを実行します。BookLemeは忠実性を検証可能な指標に分解しており、引用解析率、逐語違反率、ネガティブ例の回答拒否率、トリガーワード一致率、成果物適合率、shingle重複上限、カバレッジなどを含みます。

プロジェクトにはgroundednessヒューリスティック指標も残されていますが、READMEにはLLM judgeがまだ接続されていないため、現時点ではこの値は報告のみで、ハードゲートには使用しないと明記されています。

回帰テストを実行する

コアコード、プラグイン、テンプレートを変更した後は、完全なテストを実行します。

python3 -m unittest discover -s tests -v

プラグインを開発中の場合は、状態スキーマを確認し、プラグインファイルを個別に検証することもできます。

python3 -m bookleme schema --state
python3 -m bookleme plugin validate bookleme/plugins/builtin/coach_dialogue.py

成果物のインストールと利用権の宣言

デフォルトでは、生成コマンドは成果物をSkillのソースオブトゥルースに書き込みません。インストールする場合は、明示的に--installを追加する必要があります。同時に、--user-rightsで入力内容の権利状態を宣言できます。

python3 -m bookleme run \
  --input path/to/book.md \
  --title "社内知識Skill" \
  --engine both \
  --install \
  --user-rights owned

--user-rightsで指定できる値は次のとおりです。

  • owned：ユーザーがコンテンツの権利を保有しています。
  • licensed：適切な許諾を取得しています。
  • public_domain：コンテンツがパブリックドメインに属しています。
  • unknown：権利状態が不明です。

権利の宣言は法的判断に代わるものではありません。MITライセンスが対象とするのはBookLeme変換ツールのコードとSkill定義であり、入力された書籍は対象外です。また、派生成果物を配布する権利が自動的にユーザーへ付与されるわけでもありません。

著作権ハードゲートを理解する

BookLemeの出力は、原文の再現ではなく、構造化された派生ノートとして位置づけられています。プロジェクトには6つの著作権ハードゲートが設定されており、いずれか1つでも失敗すると、インストールまたは公開が阻止されます。

  1. 1件の引用は150字以内で、入力原文に逐語的にさかのぼれること。
  2. 引用の総割合が0.03以下であること。
  3. 連続してコピーされた内容が150字以内であること。
  4. 13字shingleの重複が0.10以下であること。
  5. 成果物に全文または原文の分片を含めないこと。
  6. contains_original_textがfalseであること。

第三者の書籍から生成したSkillは、デフォルトで非公開かつ配布禁止です。実際に公開配布権を保有している場合でも、明示的に二重確認パラメーターを指定する必要があります。

--public --confirm-public PUBLISH

公開パラメーターは工学的な確認ゲートであり、著作権許諾そのものではありません。利用者は引き続き、許諾範囲、適用法、入力資料の権利状態を自ら確認する必要があります。

高度なテクニック：ステージ単位の冪等性を利用して再実行する

BookLemeのS0からS9までのパイプラインは、ステージ単位の冪等性を採用しており、SHA-256で既存の結果を識別します。長い文書の処理が予期せず中断した場合でも、完了済みのステージ成果物を保持できます。特定のステージの出力だけを削除すれば、書籍全体を再処理することなく、そのステージから再実行されます。

この設計は、プラグインやレンダリングロジックのデバッグにも適しています。2種類のエンジンは、前段の抽出、分割、能力抽出、忠実度検証の結果を共有するため、レンダリング層を変更しても原稿を再読み込みする必要がありません。

高度なテクニック：カスタムジャンルプラグインを開発する

カスタムプラグインはbookleme/plugins/user/<genre_id>.pyに配置します。プロジェクトでは、プラグインが主要フィールドを宣言することを要求しており、必須フィールドが不足している場合は読み込みを拒否します。

  • state_machine：プロセスの状態と遷移を定義します。
  • output_contract：成果物が提供すべき出力を定義します。
  • hard_constraints：違反してはならないルールを定義します。
  • anti_patterns：避けるべき誤った行動を列挙します。
  • voice_calibration：語調、呼称、禁止語、結論の帰属を定義します。
  • copyright_profile：著作権管理に関連する設定を宣言します。
  • trigger_words：3～5個の中国語トリガーワードを提供します。
  • eval_prompts：評価プロンプトを提供し、そのうち少なくとも1つはネガティブ例を含めます。

プラグインを作成する前に、プラグイン仕様を読むことを推奨します。完成後はplugin validateで検証してください。プラグインによって忠実度チェック、著作権ハードゲート、ネガティブ例への回答拒否要件を回避してはいけません。

S0–S9パイプラインの仕組み

  1. S0–S2：入力を登録し、決定論的に抽出・正規化したうえで中国語のセクション分割を行います。固定された英語の Chapter マーカーには依存しません。
  2. S3：12 個の特徴に基づいてジャンルを振り分けます。曖昧な場合は、2 つのエンジンを自動的に選択できます。
  3. S4：原子能力を抽出します。決定論的抽出器と、オプションの OpenAI 互換 LLM 抽出器を使用できます。設定がない場合は自動的にフォールバックします。
  4. S5：引用を逐語的に検証し、claim ledger を維持して、忠実度の指標を計算します。
  5. S6：プラグインに応じてナレッジパッケージまたは行動 Skill をレンダリングします。ここが 2 つのエンジンが実際に分岐する箇所です。
  6. S7–S9：総合検証、冪等インストール、スモーク評価を実行します。

S3 と S4 はいずれも S2 の結果を入力として受け取り、並行して動作できます。2 つのエンジンは S1、S2、S4、S5 の中間表現を共有するため、読み取りと抽出の重複を避けられます。

実践のヒント

  • まずはプロジェクト付属の合成書稿でコマンドに慣れてから、実際の書籍を扱ってください。
  • 成果物の種類が不確かな場合は --engine auto を使用します。2 種類の結果を同時に比較する場合は both または --no-router を使用します。
  • プラグインまたはテンプレートを変更するたびに、成果物の検証と単体テストを実行してください。
  • 書籍に記載されていない情報については拒否する能力を維持し、モデルの一般知識で出典の不足を補わないでください。
  • 書籍の原文、表紙、スキャン画像をリポジトリにコミットしないでください。また、デフォルトで非公開となっている第三者の書籍成果物をそのまま公開しないでください。
  • 忠実度ドキュメントと著作権ドキュメントを読み、指標と公開範囲を確認してください。

現在の範囲

BookLeme は現在、M0–M3 の段階にあります。coach_dialogue と knowledge_reference は実装済みですが、専門分析と意思決定チェックリストのプラグインは今後のロードマップに含まれています。LLM judge はまだ統合されておらず、関連する一部の指標は依然として null です。使用時には、実装済み、実測済み、検証待ちの機能を区別してください。

まとめ

BookLeme は「読書」をテスト可能なエンジニアリングパイプラインへと変換します。まず抽出とセクション分割を行い、次に能力を抽出して忠実度を検証し、最後にナレッジパッケージまたは行動 Skill としてレンダリングします。初回のコンパイルが完了したら、検証、テスト、権利表示、著作権チェックを定常的なプロセスに組み込むことを推奨します。これにより、書籍の手法を再利用しながら、出典の境界と検証可能性を維持できます。