論文からノートブックへ は何をしますか?
1つの論文から、読者がその論文を理解するための実行可能なmarimoノートブックを生成します。このノートブックは、単なる要約ページではなく、レッスン形式です。平易な説明、理解を助ける対話型ウィジェット、そして随所に配置された簡単な確認問題が特徴です。文章は、一般的なAIによる散文ではなく、論文を忠実に表現し、理解しやすいものでなければなりません。
このファイルはスケルトンです。多くの詳細は後で追加されます。TODOとマークされた項目は、未決定またはスケッチのみの状態です。
契約
| 入力 | PDF、HTML、またはプレーンテキスト形式(LaTeX、Markdownなど)の論文。全文が取得可能であれば、パス、URL、識別子のいずれでも構いません。 |
| 出力 | 読者が uvx marimo edit --sandbox … で開くことができる、実行可能なmarimoノートブック(*.py)。 |
不足している場合に尋ねるべきオプションの入力(ユーザーが論文のみを指定した場合でも処理をブロックしないこと):
- 対象読者層、または「状況に応じて調整」。デフォルトの想定:学部生から大学院生、およびこの論文や分野に初めて触れる実務経験者で、ある程度の一般的な科学知識を持つ。TODO: デフォルトをより明確にする。
- 追加のコンテキスト:補足情報、引用論文、またはユーザーが根拠として扱いたいその他の情報源(一般的な知識ではありません)。
- 詳細度:完全なウォークスルー、手法・結果のみ、または特定の図のみ。
- 出力パスと実行時の制約。
このスキルを大規模な文献レビューのためのツールとして扱わないでください。それは別の役割です。
ワークフロー
1. 論文を取り込む(PDF / HTML / プレーンテキスト)
2. 構造、用語、数式、図、および不足部分を抽出する
3. 学習パスを計画する
4. marimoノートブックを生成する
5. `uv run` で実行できることを検証し、引き渡す
1. 論文を取り込む
要約のみではなく全文を取得します。入力タイプに応じて分岐し、フォーマット固有のメモは resources/ に、ヘルパーは scripts/ に配置します(常に uv run を使用し、グローバルな pip install は使用しない)。
- PDF: TODO: テキスト、数式、図、読み取り順序を取得および解析する方法。推測ではなく、失敗を報告すること。
- HTML: TODO: メインのテキストとナビゲーション/装飾、MathJax/MathML、図を取得および解析する方法。
- プレーンテキスト(LaTeX、Markdownなど): TODO: インクルード、参考文献、図ファイルを追跡する方法;数式と図のラベルを保持する方法。
論文のタイトル、著者、年、および安定したリンクまたは識別子を記録します。
2. 構造、数式、図を抽出する
ノートブックを作成する前に、論文の中間表現を構築します。TODO: このステップのデータ構造を確定する(適切な中間構造が残りの作業を容易にするという考えも参照)。
少なくとも以下を抽出します:
- 問題と貢献(自分の言葉で)。
- 前提条件プロファイル:各レベルの読者が何を知っていて、何を知らず、何を教えられる必要があるか(複数レベルでの説明を参照)。
- 主要な概念と、論文が使用しているが定義していない用語(コアメタデータまたは分野用語)。設計議論で挙げられた例:「心筋梗塞」を説明していない心臓発作に関する論文。
- 主要な数式(論文内の番号と変数付き)。
- 主要な図:各図が何を表しているか、どのようにラベル付けされているか、基礎となるデータが利用可能かの有無。
- 生成上のリスクポイント:複雑なLaTeXや数式、ギリシャ文字の図ラベル、その他の非ASCIIテキスト。
- 手法や報告における明らかな欠落。存在しない実験結果を invent してはいけません。
分野の成熟度(確立、新興、学際的、または混合)を、resources/field-maturity.md のルーブリックと軽量な文献サンプルを使用して分類します。クラス、その根拠、および必要な語彙オンボーディングノートブックコンポーネント(用語集、曖昧性解消、変動する用語)を記録します。
TODO: 論文をアルゴリズム的(コーディング演習、手法のリバースエンジニアリング)か、概念的(エージェント作成の説明ウィジェット)かに分類するかどうか。議論で使用された化学の例:質量バランス、反応速度論、新しい速度モデル。
3. 学習パスを計画する
人間が一度に読み通せるパスを設計します。TODO: 目標時間。
ノートブック全体を単一の読解レベルに固定しないでください。適応的な説明を計画します:読者は難しい箇所について、より簡単な説明またはより高度な説明を取得できるべきです。TODO: デフォルトの方向性 — シンプルから始めて複雑さを追加するか、高度から始めて読者が混乱したときに段階を下げるか。両方が提案されましたが、どちらも選択されませんでした。コアコンセプトには完全なラダーを用意します(複数レベルでの説明を参照)。
推奨される骨子(論文に応じて調整):
- この論文が重要な理由。
- 複雑な表記法の前の直感またはおもちゃの例。
- 準備:表記法、仮定、用語、および分野語彙のオンボーディング(用語集、必要に応じて曖昧性解消または変動する用語 —
resources/field-maturity.mdを参照)。 - 中心となるアイデア(数式または図に関連付けて)。
- 論文に沿ったステップスルー。
- セクションごとの簡単な確認問題(説明レベルに合わせて:説明する、予測する、適用する、批評する — 正式な評価は範囲外)。
- 大学院生以上向け:批評ポイント — 実験計画は提示された疑問に対応しているか、統計フレームワークは適切な選択か、何が欠けているか、読者はどのような仮定をしているか。
- まとめ:限界、次に読むべきもの、引用。
- 最終クイズ:論文に関する5択問題(常に最後のセクション、最終クイズを参照)。
TODO: 最初のバージョンでの批評、結果セクションの分析、図解釈プロンプトの範囲と、単純なガイド付きウォークスルーとの比較。
ユーザーが追加の情報源を提供した場合、それらがノートブックのどこで引用され、情報源のある証拠と一般的な知識がどのように区別されるかを計画します。TODO: その区別のメカニズム、および後で小さなコンセプトマップや「知識Wiki」がここに含まれるべきかどうか。
4. marimoノートブックを生成する
assets/ テンプレートが存在する場合はそれから始めます(TODO: assets/notebook_template.py を追加)。uvx marimo edit --sandbox で開くことができるmarimoノートブックを作成します。
.agents/skills/ にインストールされたmarimoスキルに従います(import marimo as mo セル1つ、一意のトップレベル名、探索を促進するためのウィジェット — 装飾ではない):
marimo-notebook-patterns:ノートブックのセルを作成または編集する前に読むこと(インポートとセルパラメータのルール、一意の変数、ウィジェットAPIシグネチャ、一般的なエラー)。marimo:より広範なオーサリングリファレンス(ライブペアリングやWebへのノートブック埋め込みを含む)。awesome-marimo-notebook:論文やデータセットの説明ノートブックを魅力的で洗練されたものにする方法。
ファイルの先頭に PEP 723 のインラインスクリプトメタデータブロック(# /// script … # ///)で依存関係を宣言し、marimo とノートブックがインポートするすべてのパッケージを下限バージョン付きでリストします(例:numpy>=2.0)。これにより、uv run と marimo edit --sandbox がそれらをインストールできるようになります。
ノートブックの最後に、最終クイズで説明されている5問のクイズを配置します。
文章に関する厳格な要件:
- 論文の核となるアイデアを理解可能かつ忠実に表現すること。
- 一般的な「AIの粗製乱造」ではないこと。もし文がどの論文についても書けるものなら、書き直すこと。
- 記号や分野用語は、最初に重要になったときに定義するか、用語集/ツールチップ/ハイライトして説明を表示する補助機能を参照すること。
resources/field-maturity.mdに従い、成熟度固有のオンボーディングセクションを設けてください。TODO: これらの読者補助機能のうち、最初に出荷するもの。ハイライトして説明する機能として「Marimo Lens」が可能な選択肢として言及されました。実際の機能名とホストのサポートを確認してください。
その他の生成ルール:
- 数式:
mo.md内でLaTeXを使用。直感を養う場合はパラメータに対するウィジェットを使用。 - 図:データが許せば再現または簡略化し、論文の図番号にリンクすること。データが利用できない場合はその旨を明記し、プロットを invent してはいけません。TODO: v1でどの程度、視覚ベースの推定や読者作成の図解釈まで進めるか。
- 図のウォークスルー:主要な図にガイド付きの段階的なツアーが必要な場合は、
resources/dynamic_figure_annotation.mdを読むこと(FigureAnnotatorWidgetとscripts/内の座標監査ヘルパー)。 - コアコンセプト(ノートブックあたり1〜3つ)には説明ラダーを設けます(複数レベルでの説明)。
- 簡単な確認問題:短い質問、採点ではない。
resources/explanation-levels.md§9のshow_checkパターンを使用(ラジオボタン、許容差付きの数値回答、または模範解答付きの自由記述)。 - ステップ2からのドメインモード:アルゴリズム的な論文にはコーディング演習と手法の再構築を、概念的な論文にはエージェント作成の可視化/ウィジェット説明を(例:セル内のメカニズム)。
- 論文の範囲を超えるものにはラベルを付ける(「デモ」、「簡略化した仮定」)。
- 論文のメタデータと引用を含めること。
5. 検証と引き渡し
最小要件(v1スケルトン):ノートブックが実行できること。
uv run scripts/validate_notebook.py path/to/notebook.py --run
これにより、Python構文のチェック、marimo check --strict の実行、および --run オプションでノートブックを最初から最後まで実行します。報告されたすべての問題を修正してから引き渡します。
ユーザーに次の情報を伝えます:
- ノートブックのパスと、それを開くためのコマンド(
uvx marimo edit --sandbox …)。 - 想定した読者層と簡略化した内容。
- TODOと既知のギャップ(欠落データや未定義の用語を含む)。
- 論文の参照情報(タイトル、著者、年、リンク)。
計画されている「実行できる」以上の検証(最初のスケッチではすべて必須ではない):
- 文章が理解可能かつ忠実であり、粗製乱造ではないこと。
- コアコンセプトとメタデータ用語が実際に説明されていること。
- 捏造された数値や主張がないこと。
- ノートブックが5問のクイズで終了し、その質問が論文の主張、発見、限界に関するものであり、実装の詳細に関するものではないこと。
- すべてのラダーが、すべてのレベルで同じメカニズムの骨子を説明していること。すべてのレベルの簡略化が後のレベルで修正されていること。アナロジーの限界が述べられていること。
- 語彙オンボーディング: 確立、新興、学際的なケーススタディについて、用語集のカバレッジを検証し、必要に応じて
resources/field-maturity.md§8に従って曖昧性解消または変動する用語のセクションを確認すること。 - TODO: アサーションまたはゴールドクエスチョンによる評価。マルチモデル実行(中国のオープンウェイトモデルとClaudeモデルが提案されました)。LLM-as-judgeは、「良い」よりも「悪い」について信頼性が高い最初のフィルターとしてのみ使用すること。見慣れない論文での人間によるテスト。自身の分野でのスモークテスト後のドメインエキスパートによるレビュー。
- TODO: 確立、新興、学際的な研究、およびサブドメインをカバーする共有テスト論文セット(単一の分野だけでないこと)。2016年のインフルエンザ論文が1つの可能なケースとして提案されましたが、リストはまだ選択されていません。
複数レベルでの説明
コアとなるアイデアには説明ラダーを設けます。1つのメカニズムを5つのレベルで説明し、各レベルは特定の前提知識を持つ読者向けに書かれています。これはWIREDの5 Levelsシリーズに着想を得ています。レベル名は簡略表記です。各レベルを定義するのは、読者が持っている主題知識と数学、およびそのレベルが追加する精度です。
| レベル(簡略表記) | 想定される主題知識 | 想定される数学 | メカニズムに追加するもの |
|---|---|---|---|
| 1 · 子ども | 日常の経験 | カウントと比較 | 因果関係(日常的な用語で) |
| 2 · 10代 | 一般的な科学リテラシー | 算術、パーセンテージ、簡単なグラフ | 実際の小さな数を使ったおもちゃの例 |
| 3 · 学部生 | その分野の入門コース | その分野の入門ツール | 正確な数式またはアルゴリズム、すべての記号を定義 |
| 4 · 大学院生 | 関連分野の標準的な手法 | 論文の導出を追える | 仮定、成立する条件、破綻する条件、標準的なアプローチとの比較 |
| 5 · 専門家 | このサブフィールドの文献 | 完全な形式主義 | 新しい点、トレードオフ、限界、未解決の問題 |
ルール:
-
論文ごとに前提条件をプロファイルする(フェーズ1): 各レベルについて、読者が知っていること、知らないこと、ノートブックが教えなければならないことを定義します。ユーザーが指定した背景(「契約」のオプション入力から)をレベルにマッピングします。
-
すべてのレベルで1つのメカニズム。 最初に1文のメカニズムの骨子を書き、各レベルはそれに精度を追加します。どのレベルも、より曖昧または異なるメカニズムで置き換えてはいけません。
-
すべてのレベルで正確であること。 省略によって簡略化し、誤ったことを言って簡略化してはいけません。各簡略化を台帳に記録し、後のレベルで修正します。
-
アナロジーをマッピングし、その限界を述べること。 1つのアンカーをレベル3まで引き上げ、その部分を手法の部分にマッピングし、レベル3までにそれが破綻する箇所を述べます。
-
レベルに合わせた確認問題:
- 子ども:説明する。
- 10代:予測する。
- 学部生:適用する。
- 大学院生:適用し、仮定を批評する。
- 専門家:批評する。
各確認問題には、期待される回答、その理由、および論文内の該当箇所が含まれている必要があります。
-
ラダーはコアコンセプト用: ノートブックあたり1〜3の概念。
-
根拠に基づくこと: 読んだテキストから箇所を引用し、推測しないこと。ドラフト中はギャップを
[引用: …]でマークし、出荷前に解決すること。 -
数値はその条件と共に記載すること: 表、コホート、特徴セット、または範囲は同じ文に含めます。実際の論文でのテストでは、ラダーによって引き起こされた誤解は両方とも、条件を剥ぎ取られた数値から生じました。
ノートブック内で: 上部近くに1つのレベルピッカーを追加します。各ラダーは mo.ui.tabs を取得し、読者のレベルで開き、そのレベルの確認問題が下に表示されます。
書く前に読むこと: resources/explanation-levels.md には、プロファイルと台帳のテンプレート、動作例、テスト済みのmarimoセル、および落とし穴が含まれています。resources/examples/ には、さらに2つの完全なラダーがあります。