グラフィカルアブストラクトビルダー は何をしますか?
研究資料(PDF、ノート、実験記録)を、すべての要素が出典にトレース可能な1ページのグラフィカルアブストラクトと、契約を完全に満たす result.json に変換します。
役割分担 — 科学的判断はエージェントが、描画はスクリプトが担当:
- エージェント(あなた):実際の資料を読み、エンティティ/関係/データを抽出し、視覚的エンコーディングを選択し、キャンバスに描く内容とキャプションに回す内容を決定し、図と資料を照合検証します。
- スクリプト(
scripts/、純粋なPython + matplotlib):レイアウト、レンダリング、チェック、結果のアセンブリを行います。決定論的:同じモデル入力 → 同じ図出力。
環境とパス
- スキルルート:
/skills/weekly-skill(スクリプトはscripts/、スキーマドキュメントはreferences/)。作業は/app/workで行い、最終成果物は/app/outputに配置。 - 入力:
/input/case.json(+ task.md; 資料ファイルはケースから参照)。 - Python + matplotlib が必要。matplotlibがない場合、PNGエクスポートは自動的にPillowにフォールバックし、PDFエクスポートはエラーを発生させて対処法を表示します(プレイブック参照)。
- 典型的なコスト:10〜20回のモデルリクエスト(64リクエスト/900秒の予算内)。各ビルド/検証スクリプトの実行は1ツールコールです。
ワークフロー
ステップ 0 — ケースを読み、result.json の雛形を作成する(最初に実行)
/input/case.json を完全に読みます。case_id と output_contract のすべてのフィールドに注意してください — これらがあなたの納品義務です。その後、すぐに次を実行します:
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
これにより、すべての契約フィールドが明示的な null と保留理由で書き込まれます。以降、クラッシュが発生しても契約を満たす成果物が残ります。--stage final(ステップ6)でこれを埋めます。
ステップ 1 — 実際の資料を読む
ケースが参照する実際のファイルを開きます(ラベルから内容を推測しないでください)。PDFには pdf-text-tool / scientific-python を使用します。OCRが必要な場合のみページをスキャンします。各資料ファイルを抽出テキストにマッピングする sources.json を保存します — 後のステップで引用を自動的に検証します:
{ "materials/paper.pdf": "<抽出された全文>" }
ステップ 2 — 科学的情報を抽出する(あなたの判断。スクリプトは関与しない)
テンプレート(templates/agent_worksheet.md)を資料から直接埋めます:
- 質問(Question) — 資料が提起する問題は何か? そのまま引用します。
- エンティティ(Entities) — 登場する必要があるもの(分子、細胞、デバイス、手法、コホート...)。それぞれについて:ラベル、一字一句の引用、位置情報(ファイル + ページ/セクション/文)。
- 関係(Relations) — 資料が述べる方向性のある接続(AがBを活性化する、投与量が質問の動機となる...)。方向とそれを述べている文を記録します。
- データ(Data) — 描画する可能性のあるすべての数値:値、単位、条件、およびその出典文。描画したい数値が資料にない場合、描画せず、代わりに
uncertainty/limitsにリストします。 - 結論(Conclusion) — 資料自体が述べる主張。
エビデンスのルール:引用は資料の一字一句の部分文字列。位置情報は人間が数秒で見つけられるほど正確。出典不明のものはキャプション/ノートに回し、データとしてキャンバスに描かない。
ステップ 3 — figure_model.json を作成する
/app/work/figure_model.json を、references/model_schema.md のスキーマに従って記述します(完全な実例:examples/transformer-1706.03762/)。あなたが行う主要な判断:
- パネル計画:通常、読み順に4〜6パネル(質問 → 方法 → 結果(1〜2)→ 結論)。1パネルあたり1つの発見。
- パネルごとのレイアウト:
flow(エンティティ/関係のボックス+矢印)、chart(データの棒/横棒/グループ化棒/折れ線)、stats(主要な値2〜4個の大きな数字の呼び出し)、text(箇条書きの結論)。 - 視覚チャネル:長さ → 共通単位とゼロベースラインを持つ大きさ。位置 → 時系列。色 → カテゴリ系列のみ(Okabe–Itoパレットが組み込み。純粋な赤vs緑は不可)。形状/強調 → 焦点エンティティ。1つの意味に1つのチャネル、1つのチャネルに1つの意味。
- キャンバス:デフォルト 1800×1000 px(≈ A4横、150 dpi)。すべてのフォントサイズは12 px以上(チェッカーが強制)。
- 各要素の
sourceに、ワークシートから引用と位置情報をコピーします。
ステップ 4 — ビルドと反復
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
graphical_abstract.svg(編集可能なソースオブトゥルース:名前付きID、layer-*グループ、各要素の provenance <desc> 付き)、.png(300 dpi)、.pdf、element_map.json、export_report.json を生成。終了コード2 = モデル無効(JSONを修正)、3 = SVG失敗(プレイブックに従って修正)。PNG/PDFのレンダリング失敗は実行を中断せず、export_report.json の failures に記録されます。
反復:レポートにエラーが表示された場合、SVGではなくモデルを編集して再ビルドします。すべてのエラーコードがクリアされるまで、図は不完全です。
ステップ 5 — 査読者のように検証する
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
これにより、すべてのチェックが再実行されます:SVGの整形式性、フォントサイズの下限、キャンバス境界、要素マップの完全性、引用と資料の一致(捏造された数値や誤引用を検出)、グレースケール/コントラスト、エクスポートの整合性。次に、PNGを自分で確認(レンダリングプレビューを読む)し、読み順が明らかか、エンティティ/矢印の方向が資料と一致するか、凡例がエンコーディングと一致するか、すべての軸に単位があるかを確認します。警告が排除できない場合は記録し、隠蔽しないでください。
ステップ 6 — 最終的な result.json を組み立てる
契約フィールドの値(scientific_summary、uncertainty、パスリスト、export_checks...)を記述した /app/work/values.json を書き込みます。element_source_map と export_checks はビルドから自動入力されます。その後:
python scripts/make_result.py --stage final \
--case /input/case.json --out /app/output/result.json \
--values /app/work/values.json \
--map /app/work/out/element_map.json \
--export /app/work/out/export_report.json \
--issues /app/work/out/issues.json \
--status complete --uncertainty "<正直な一文>"
マッチャーは、完全一致、包含、説明キーワードの順で契約フィールドを埋めます。一致しないフィールドは明示的な null と理由が残ります。エラーレベルの問題が残っている場合、ステータスは自動的に partial にダウングレードされます — チェックが失敗しているのに complete と宣言しないでください。成果物を /app/output にコピーします:
graphical_abstract.svg + figure_model.json(編集可能なソース)、
graphical_abstract.png(プレビュー)+ graphical_abstract.pdf(エクスポート)、
result.json。
ステップ 7 — 最終自己チェック
- result.json:
case_idが存在する。すべての契約フィールドが埋まっているか、明示的なnullと理由がある。ステータスが正直(自動ダウングレードが尊重されている)。 - SVG が開く(整形式XML)、テキストは実際の
<text>(編集可能)、すべての要素にIDがある、レイヤーに名前が付いている。 - PNG と PDF が存在し、空ではない。PNG は 300 dpi 以上。
- キャンバス上のすべての数値が
element_map.json内の引用に出現する。 - 凡例が色/系列のエンコーディングと正確に一致する。
-
uncertainty/limitsが、劣化または出典不明の項目をすべて言及している。
問題が発生した場合
すべての障害モード、その兆候、および対処法(資料に主要な数値がない、エンティティの曖昧さ、テキストオーバーフロー、フォント置換、キャンバスオーバーフロー、エクスポート失敗、matplotlibがないなど)は references/exception_playbook.md に記載されています — 赤色の出力が出たら参照してください。すべてに優先する唯一のルール:正直に記録し、決して捏造しない。 文書化された制限とともに partial の結果を出すことは、捏造された証拠を使ったきれいな図よりも高く評価されます。
参考文献
references/model_schema.md— figure_model.json のフィールドごとの説明、デフォルト値、制約。references/exception_playbook.md— 障害の兆候 → 対処法。references/design_notes.md— ビルダーが使用する視覚エンコーディングルール、色覚安全性、レイアウト規則。templates/agent_worksheet.md— ステップ2の抽出ワークシート。templates/figure_model.template.json— 最小限の開始モデル。examples/transformer-1706.03762/— 実際の論文を使った実例(arXiv:1706.03762、一字一句の引用 + sha256)。