literature-review-agent

文献レビューエージェント（ステップ 3）

PaperOrchestra の Hybrid Literature Agent を忠実に実装しています （Song et al., 2026, arXiv:2604.05018, §4 Step 3, App. D.3, App. F.1 p.46）。

コスト：約20～30回の LLM 呼び出し。 これは最も時間のかかる2つのステップのうちの1つです（もう1つはプロット作成です）。所要時間の下限は、Semantic Scholar の検証レート制限である1 QPSによって決まります。

入力

• workspace/outline.json — 特に intro_related_work_plan。Introduction の検索方針と、Related Work の2～4個の手法クラスターが含まれています
• workspace/inputs/conference_guidelines.md — cutoff_date の導出に使用します
• workspace/inputs/idea.md、workspace/inputs/experimental_log.md — Introduction の構成と、Related Work における位置づけの根拠に使用します

出力

• workspace/citation_pool.json — 検証を通過したすべての論文について、検証済みの Semantic Scholar メタデータを格納します
• workspace/refs.bib — 検証済みのプールから生成した BibTeX ファイルです
• workspace/drafts/intro_relwork.tex — テンプレートに書き込まれた、Introduction と Related Work の草稿です。テンプレートの残りの部分は一字一句そのまま保持されます

2段階のパイプライン（App. D.3）

PHASE 1 — Parallel Candidate Discovery
   For each search direction in introduction_strategy.search_directions:
   For each limitation_search_query in each related_work cluster:
     - Use the host's web search tool to discover up to ~10 candidate papers.
     - Run up to 10 discovery queries in parallel (host-permitting).
     - Collect (title, snippet, url) tuples — no verification yet.
   → PRE-DEDUP before Phase 2 (see Step 1.5 below)

PHASE 2 — Sequential Citation Verification (1 QPS, with cache)
   For each candidate (after pre-dedup), sequentially:
     0. Check s2_cache.json first (scripts/s2_cache.py --check).
        If HIT: use cached response, skip live S2 call. No throttle needed.
        If MISS: proceed with live request below.
     1. Query Semantic Scholar by title:
          GET https://api.semanticscholar.org/graph/v1/paper/search?query=<title>
              &fields=title,abstract,year,authors,venue,externalIds&limit=5
        (Public endpoint, no key. Throttle to 1 QPS for live requests only.)
     2. Store the S2 response in cache: s2_cache.py --store.
     3. Pick the top hit. Check Levenshtein title ratio against the original
        candidate title. If ratio < 70: discard.
     4. Bonus: if year and venue exactly align with hints, add a +5 point
        match-quality bonus.
     5. Require: abstract is non-empty.
     6. Require: paper.year (or month if known) strictly predates cutoff_date.
        Months default to day-1: e.g., "October 2024" → 2024-10-01.
     7. If all checks pass, add to verified pool.
   After all candidates are verified, dedup by Semantic Scholar paperId.

LLM とウェブ検索の処理はホストエージェントが行い、決定論的なヘルパーが scripts/ で計算を行います。

手順

0. cutoff_date の導出

conference_guidelines.md から投稿締切を解析します。論文の調査対象期間は、投稿先の締切に合わせます（App. D.1）。

会場	締切
CVPR 2025	2024年11月
ICLR 2025	2024年10月
その他	記載された投稿締切の1か月前

YYYY-MM-DD 形式で指定します。月だけが指定されている場合、日付は1日とします（例：2024-10-01）。

1. フェーズ1：候補の並列検索

outline.json から、次を取得します。

• すべての introduction_strategy.search_directions（3～5件のクエリ）
• related_work_strategy.subsections の各クラスターについて：
  • クラスターの sota_investigation_mission を検索クエリとして使用します
  • すべての limitation_search_queries（各1～3件）

各クエリに対して、ホストのウェブ検索ツール（Claude Code の WebSearch、Cursor の @web、Antigravity の検索ツールなど）を使用します。クエリごとに上位約10件の候補を収集します。候補には、タイトル、要旨の抜粋、ソース URL を含めます。

ホストが並列サブタスクに対応している場合は、最大10件の検索クエリを同時に実行します。対応していない場合は、順次実行します。時間はかかりますが、機能的には同等です。

オプション：フェーズ1のバックエンドとして Exa を使用

ホストに標準のウェブ検索機能がない場合、またはノイズに対するシグナルの比率がより高い、研究論文に特化したバックエンドを使いたい場合は、同梱の scripts/exa_search.py ヘルパーを使って Exa を利用できます。これはオプトイン方式で、環境変数から EXA_API_KEY を読み込みます。リポジトリにキーがコミットされることはありません。

export EXA_API_KEY="your-key-here"   # get one at https://dashboard.exa.ai/
python skills/literature-review-agent/scripts/exa_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 15 \
    --discovered-for "related_work[2.1]"

出力は、raw_candidates.json に統合できる正規化済み候補リストです。フェーズ2の検証（Semantic Scholar によるあいまい一致、締切日による絞り込み、重複排除）は変更ありません。レシピ全体、クエリのパターン、コストの見積もり、セキュリティに関する注意事項については、references/exa-search-cookbook.md を参照してください。

オプション：フェーズ1のバックエンドとして Tavily を使用

ホストに標準のウェブ検索機能がない場合、または関連度スコアの高い、LLM 向けに最適化された検索バックエンドを使いたい場合は、同梱の scripts/tavily_search.py ヘルパーを使って Tavily を利用できます。これはオプトイン方式で、環境変数から TAVILY_API_KEY を読み込みます。リポジトリにキーがコミットされることはありません。

export TAVILY_API_KEY="tvly-your-key-here"   # get one at https://app.tavily.com
python skills/literature-review-agent/scripts/tavily_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 15 \
    --academic \
    --discovered-for "related_work[2.1]"

出力は、raw_candidates.json に統合できる正規化済み候補リストです。フェーズ2の検証（Semantic Scholar によるあいまい一致、締切日による絞り込み、重複排除）は変更ありません。レシピ全体、クエリのパターン、コストの見積もり、セキュリティに関する注意事項については、references/tavily-search-cookbook.md を参照してください。

オプション：Phase 1 のバックエンドとして Serply を使用する

ホストにネイティブのウェブ検索機能がない場合、または site: フィルターを使って Google の検索結果をそのまま取得したい場合は、同梱の scripts/serply_search.py ヘルパーを介して Serply（ドキュメント）を使用できます。これはオプトイン方式で、環境変数から SERPLY_API_KEY を読み取ります。リポジトリにキーがコミットされることはありません。

export SERPLY_API_KEY="your-key-here"   # get one at https://serply.io
python skills/literature-review-agent/scripts/serply_search.py \
    --query "Sparse attention long context transformers" \
    --num-results 10 \
    --academic \
    --discovered-for "related_work[2.1]"

出力は、raw_candidates.json にマージできるよう正規化された候補リストです。Phase 2 の検証（Semantic Scholar のあいまい一致、カットオフ、重複排除）は変更ありません。手順全体、クエリのパターン、コストの見積もり、セキュリティに関する注意事項については、references/serply-search-cookbook.md を参照してください。

見つかった候補をすべて、1 つの作業用リストにまとめます。後から「intro」と「related_work[i]」のどちらに由来するか特定できるよう、それぞれに元のクエリ ID を付けます。

1.5. Phase 2 の前に重複を排除する

Phase 2 を開始する前に、必ずこれを実行してください。 複数の検索クエリで同じ論文が頻繁に返されます（例：「Attention is All You Need」はほとんどすべての NLP 論文検索クエリに登場します）。重複を検証すると、1 QPS の制限下で S2 の利用枠の 30～40% が無駄になります。

python skills/literature-review-agent/scripts/pre_dedup_candidates.py \
    --in workspace/raw_candidates.json \
    --out workspace/deduped_candidates.json
# Prints: "150 candidates → 97 unique (53 duplicates removed)"

Phase 2 の入力には workspace/deduped_candidates.json を使用してください。

2. Phase 2：Semantic Scholar による逐次検証（キャッシュ付き）

deduped_candidates.json 内の各候補について、順次処理します。

ステップ A — まずキャッシュを確認（S2 呼び出しなし、スロットリング不要）：

python skills/literature-review-agent/scripts/s2_cache.py \
    --cache workspace/cache/s2_cache.json \
    --check "<candidate title>"
# exit 0 + prints JSON → use cached response, skip Step B
# exit 1 → proceed to Step B

ステップ B — S2 にライブリクエストを送信（キャッシュミスの場合のみ、1 QPS に制限）：

推奨： 同梱の scripts/s2_search.py ヘルパーを使用してください。認証、再試行、429 のバックオフを自動で処理します。

python skills/literature-review-agent/scripts/s2_search.py \
    --query "<URL-decoded candidate title>" --limit 5
# If SEMANTIC_SCHOLAR_API_KEY is set the key is forwarded automatically.
# If not, the public unauthenticated endpoint is used (≤1 QPS, still works).

Phase 2 を開始する前に、キーが設定されているか確認してください。

python skills/literature-review-agent/scripts/s2_search.py --check-key

代替方法： ホストの URL 取得ツールを使用する場合は、次の URL に GET リクエストを送信してください。

https://api.semanticscholar.org/graph/v1/paper/search?query=<URL-encoded title>&limit=5&fields=title,abstract,year,authors,venue,externalIds

環境変数が設定されている場合は、ヘッダー x-api-key: <SEMANTIC_SCHOLAR_API_KEY> を追加します。適切に利用してください。ライブリクエストは 1 秒あたり 1 件以下にしてください。キャッシュヒットは無料です。

ステップ C — キャッシュに保存（ライブリクエストが成功するたびに実行）：

python skills/literature-review-agent/scripts/s2_cache.py \
    --cache workspace/cache/s2_cache.json \
    --store "<candidate title>" \
    --response '<full S2 JSON response>'

最上位の検索結果について：

python skills/literature-review-agent/scripts/levenshtein_match.py \
    --candidate "Original candidate title" \
    --found "S2 returned title"
# prints integer 0-100. Discard if < 70.

次に、時間的なカットオフを確認します。

python skills/literature-review-agent/scripts/check_cutoff.py \
    --paper-year 2024 \
    --paper-month 9 \
    --cutoff 2024-10-01
# exit 0 if strictly predates, exit 1 if not

両方の確認に合格し、かつアブストラクトが空でない場合は、その論文の S2 メタデータ全体を検証済みプールに追加します。

3. 重複を排除してプールを組み立てる

すべての候補の検証が終わったら：

python skills/literature-review-agent/scripts/dedupe_by_id.py \
    --in raw_pool.json \
    --out workspace/citation_pool.json

重複排除スクリプトは paperId（Semantic Scholar の内部一意 ID）をキーとして使用し、取得できない場合は externalIds.DOI、次に externalIds.ArXiv、最後に正規化したタイトルを使います。

また、このスクリプトは min_cite_paper_count = floor(0.9 * len(papers)) を計算して書き込みます。これは、執筆ステップで引用が必須となる論文の最小数です（論文の 90% 以上を組み込むルール、付録 D.3）。

dedupe_by_id.py の実行直後に、プールのスキーマを検証し、自動修正します。

python skills/literature-review-agent/scripts/validate_pool.py \
    --pool workspace/citation_pool.json --fix
# Catches and fixes authors-as-strings, reports missing required fields.
# Must pass before proceeding to Step 4.

3.5. クロスインデックス検証（Crossref + OpenAlex）

Semantic Scholar は1つのインデックスであり、実在しない論文のもっともらしいレコードを返したり、誤ったメタデータを紐付けたりすることがあります。参考文献リストを作成する前に、S2で検証済みのすべての論文を2つの独立したインデックスで再確認してください。これは、幻覚による引用が紛れ込むのを防ぐ実用的な対策です。

# Optional but recommended: a polite-pool email gives faster, more reliable
# service. The repo never commits an address.
export PAPER_ORCHESTRA_MAILTO="[email protected]"

python skills/literature-review-agent/scripts/cross_verify.py \
    --pool workspace/citation_pool.json --inplace
# Annotates each paper with a `cross_verification` field and writes
# workspace/cross_verification_report.json.
# exit 0 = all corroborated; exit 1 = WARN (something flagged or an index
# was unreachable); exit 2 = usage error.

これはハードゲートではなくWARNゲートです（validate_consistency.py のようなものではありません）。疑わしい引用にフラグを立てますが、パイプラインを停止したり、何かを削除したりはしません。レポートの low と conflict のティアを確認してください。

• high — 1つ以上の外部インデックスで裏付けあり → 維持します。
• medium — 裏付けはありますが、年が一致しません → 維持し、年をスポットチェックします。
• low — Crossref または OpenAlex で見つかりません → 手作業で確認してください。DOIのないarXivのみのプレプリントは、よくある無害な原因です。low は「裏付けを確認できなかった」という意味であり、「捏造された」という意味ではありません。S2ではすでに実在が確認されています。
• conflict — poolのDOIが外部のDOIと一致しません → レコードが誤っている可能性が高いです。

本当に裏付けを確認できないエントリだけを削除し、その後 dedupe_by_id.py 以降を再実行してください。両方のインデックスに到達できない場合（オフライン）、スクリプトは適切に縮退し、S2検証のみでパイプラインを続行します。

詳細な根拠、信頼度のティア、arXivの偽陽性に関する注記については、references/cross-index-verification.md を参照してください。

4. BibTeXファイルを作成する

python skills/literature-review-agent/scripts/bibtex_format.py \
    --pool workspace/citation_pool.json \
    --out workspace/refs.bib

このスクリプトは、`firstauthor + year

• first significant word of title から決定論的に引用キーを生成します（例：vaswani2017attention）。@article／@inproceedings／@miscエントリのみを書き出し、フィールドを捏造することはありません。また、各論文レコードの正規のbibtex_keyをcitation_pool.json` に書き戻します。

bibtex_format.py の直後に、intro_relwork.tex のキーを同期します。

python skills/literature-review-agent/scripts/sync_keys.py \
    --pool workspace/citation_pool.json \
    --tex  workspace/drafts/intro_relwork.tex \
    --inplace
# Replaces every \cite{agent_key} with \cite{canonical_bibtex_key}.
# Eliminates citation_coverage gate failures caused by key mismatch.

この2つの手順により、以前必要だった手動のPythonスニペットが不要になります。現在のパイプラインは次のとおりです。

dedupe_by_id → validate_pool --fix → cross_verify --inplace → bibtex_format → sync_keys

5. 序論と関連研究の草稿を作成する

ここで、ホストエージェントであるあなたが実際に文章を執筆します。references/prompt.md にあるLiterature Review Agentのプロンプト全文を読み込みます。テンプレートのプレースホルダーを置き換えます。

プレースホルダー	値
intro_related_work_plan	outline.json の完全なJSONオブジェクト
project_idea	idea.md の内容
project_experimental_log	experimental_log.md の内容
citation_checklist	refs.bib のBibTeXキー
collected_papers	citation_pool.json の {key, title, abstract} のリスト
paper_count	len(citation_pool.papers)
min_cite_paper_count	citation_pool.json の値
cutoff_date	ステップ0で導出した日付

さらに、 ../paper-orchestra/references/anti-leakage-prompt.md のAnti-Leakage Promptを先頭に追加します。

また、 skills/shared/section_rhetoric.md の序論と関連研究のテンプレートを末尾に追加します。このファイルにある次の2つの制約が、ここでの作業の大部分を担います。

• 序論のパート2では、技術的な課題を「制約とその原因」の形で述べる必要があります。「従来手法は遅い」は症状です。「従来手法は各ステップでコンテキスト全体を再エンコードするため、対話の長さに比例してレイテンシが増大する」は、その手法で対処できる課題です。原因のないパート2では、パート3を書けません。
• 関連研究の各段落は、対象範囲を示す文 → 代表的な手法 → そのグループの限界をこちらの課題に結び付ける → 次への移行、という流れにします。グループ分けは年ではなく、技術的なテーマに基づいて行います。min_cite_paper_count ゲートが測定するのは網羅性であり、位置付けではありません。草稿がこのゲートを通過しても、引用の羅列になっている場合があります。

統合したプロンプトを使って、LLMに template.tex を処理させます。エージェントの役割は、テンプレートの序論と関連研究の空のセクションを埋め、それ以外には一切手を加えないことです。出力は、2つのセクションを埋めた template.tex 全体です。workspace/drafts/intro_relwork.tex に保存します。

5b. research_brief.md に §2 を追記する

intro_relwork.tex の下書きが作成され、引用カバレッジのチェックを行う前に、 workspace/research_brief.md に §2 を追記します（skills/shared/research_brief_template.md を参照）。

テンプレート:

## §2 · Literature Landscape
_Written by: literature-review-agent, Step 3_

**What the literature says about the core claim:** <2-3 sentence synthesis>

**Strongest prior work (must address in the paper):**
- <bibtex_key>: <why this is the strongest comparator or predecessor>

**Gaps confirmed by the literature:** <list>

**Baseline comparisons — verification status:**
| Baseline | In citation_pool? | Confidence tier |
|---|---|---|

**Related Work cluster coverage:**
| Cluster | Papers found | Notes |
|---|---|---|

**Anything the section-writing agent should know:** <important context>

これは、アウトラインが想定した内容ではなく、実際に発見された内容を統合したものです。

6. 引用カバレッジが 90% 以上であることを検証する

python skills/literature-review-agent/scripts/citation_coverage.py \
    --tex workspace/drafts/intro_relwork.tex \
    --pool workspace/citation_pool.json
# exit 0 if ≥90% of pool is cited; exit 1 otherwise

ゲートが失敗した場合は、不足しているキーを明示的に列挙し、文脈上適切な箇所にそれらを統合するようエージェントに求めて、執筆ステップを再度プロンプトします。

プロンプトからの重要なルール

これらは references/prompt.md から抜粋したものです。ホストエージェントは執筆呼び出しにおいてこれらを遵守しなければなりません（MUST）:

• collected_papers からのみ引用すること。 BibTeX キーを捏造してはならず、プールにない論文を参照してもいけません。
• それらのうち少なくとも min_cite_paper_count 件を Introduction と Related Work を合わせて引用すること。
• TIMELINE RULE: cutoff_date より後に公開された論文を、打ち負かすべき先行ベースラインとして扱ってはいけません。それらは同時期の研究にすぎません。
• EVALUATION RULE: experimental_log.md において明示的に評価対象とされていない限り、特定の引用論文に対して私たちの手法が勝っている / SOTA を達成していると主張してはいけません。その他の最近の論文は、厳密に同時期の研究、直交する研究、または概念的な研究として位置づけてください。
• 出力形式: 更新された template.tex の完全なコードを返してください。2 つの空のセクション（Introduction と Related Work）は記入済みとし、その他すべてのコード（パッケージ、スタイル、その他のセクション）は元の template.tex と同一としてください。
• 出力を ```latex ... ``` フェンスで囲んでください。
• \usepackage[capitalize]{cleveref} を cleverref に変更しないでください（cleverref.sty は存在しません）。

縮退モード（web 検索なし）

ホストに web 検索ツールがない場合は、縮退モードに切り替えてください:

1. ユーザーが事前構築済みの workspace/inputs/refs.bib をワークスペースに配置している場合は、それを直接 workspace/refs.bib に読み込み、フェーズ 1 とフェーズ 2 をスキップします。
2. そうでない場合は、Intro セクションと Related Work セクションに 2 つの TODO マーカーを含むテンプレートを内容とする workspace/drafts/intro_relwork.tex を出力し、web 検索なしではパイプラインがステップ 3 を完了できないことをユーザーに伝えてください。

リソース

• references/prompt.md — App. F.1 の Literature Review Agent プロンプトをそのまま収録
• references/discovery-pipeline.md — Phase 1 と Phase 2 の詳細な説明
• references/verification-rules.md — レーベンシュタイン距離のしきい値、年の整合性、重複排除
• references/citation-density-rule.md — 90％以上の統合ルール
• references/s2-api-cookbook.md — Semantic Scholar の URL、フィールド、レート制限
• references/cross-index-verification.md — Crossref と OpenAlex による裏付け、信頼度レベル、arXiv の誤検出に関する注記
• references/exa-search-cookbook.md — Phase 1 用のオプションの Exa バックエンド（研究論文に特化したウェブ検索）
• references/tavily-search-cookbook.md — Phase 1 用のオプションの Tavily バックエンド（LLM に最適化されたウェブ検索）
• references/serply-search-cookbook.md — Phase 1 用のオプションの Serply バックエンド（Google SERP API）
• scripts/pre_dedup_candidates.py — Phase 2 の前に Phase 1 の候補を重複排除（S2 のクォータを 30～40％節約）
• scripts/s2_cache.py — 永続的な S2 応答キャッシュ（再実行時の再検証を不要に）
• scripts/validate_pool.py — citation_pool.json のスキーマ（authors 形式）を検証し、自動修正
• scripts/sync_keys.py — bibtex_format.py の実行後、.tex 内の cite キーを正規の bibtex_keys と同期
• scripts/levenshtein_match.py — あいまいなタイトル照合（一致率 > 70）
• scripts/check_cutoff.py — 日付比較。月のみの場合はデフォルトで 1 日を使用
• scripts/dedupe_by_id.py — 検証済みプールを S2 の paperId で重複排除
• scripts/bibtex_format.py — JSON プールから refs.bib を作成
• scripts/citation_coverage.py — 引用カバレッジ 90％以上のゲート
• scripts/s2_search.py — Semantic Scholar のタイトル検索ヘルパー。環境変数 SEMANTIC_SCHOLAR_API_KEY を読み込み（任意。未設定時は認証なしで実行）
• scripts/exa_search.py — Phase 1 用のオプションの Exa バックエンド（環境変数 EXA_API_KEY を読み込み）
• scripts/tavily_search.py — Phase 1 用のオプションの Tavily バックエンド（環境変数 TAVILY_API_KEY を読み込み）
• scripts/serply_search.py — Phase 1 用のオプションの Serply バックエンド（環境変数 SERPLY_API_KEY を読み込み）
• scripts/crossref_client.py — インデックス間の裏付け確認用の Crossref タイトル／DOI 検索（キー不要。CROSSREF_MAILTO／PAPER_ORCHESTRA_MAILTO を読み込み）
• scripts/openalex_client.py — インデックス間の裏付け確認用の OpenAlex タイトル／DOI 検索（キー不要。OPENALEX_MAILTO／PAPER_ORCHESTRA_MAILTO を読み込み）
• scripts/cross_verify.py — S2 で検証済みのプールを Crossref と OpenAlex に照合し、相互に裏付け。幻覚による引用にフラグを付与（WARN ゲート）
• skills/shared/research_brief_template.md — §2 のスキーマ。intro_relwork.tex の草稿作成後に追加
• skills/shared/section_rhetoric.md — Introduction の論理展開と Related Work の段落テンプレート