[design] Citation graph 機能を Phase 1 必須にするか後ろ倒しか

[sotashimozono]

Question

1 paper から引用文献を辿る citation graph 機能をいつ実装するか。

Background

BiblioFetch.jl の citation graph: Crossref + Semantic Scholar の references を統合、max_depth / max_refs_per_paper で fan-out 制御、mermaid / DOT 出力。agent 視点では「論文 1 本から関連文献も全部欲しい」シナリオが頻出。

Options

• A. Phase 4 — MVP は単発 + batch + MCP に focus、後で追加 (4 日)
• B. Phase 1 必須 — agent killer use case として最初から (+1 週)
• C. scope 外 — doiget は単発 fetch only、連鎖は user / agent 責任

Recommendation

A。citation graph は Semantic Scholar の rate limit にぶつかりやすい (Phase 1 で取り組むには厄介)、MVP の basic flow を確立してからの追加が綺麗。Phase 4 で MCP tool expand_citation_graph(ref, depth) として公開。

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth). Reads with #3 (MVP source) / #5 (TDM) / #16 (Legal posture).

立場

Recommendation A (Phase 4 倒し) を 支持 しますが、 citation graph 機能には agent UX 観点で見落としがある expansion control の安全弁 が必要です。 また機能を Phase 4 で MCP tool として exposing する際の設計も spec lock が要ります。

1. Citation graph の expansion 制御は agent loop の燃料源

LLM agent は citation graph を fan-out するとき、 「max_depth=3, max_refs_per_paper=20」のような parameter を、 user の意図を超えて拡大解釈する failure mode があります:

Agent failure mode	結果
"be thorough" → max_depth を増やす	100 + 件 fetch、 rate limit hit、 cost blow up
"follow up on interesting refs" → max_refs を増やす	同上
Hallucinated DOI を expansion に混入	invalid fetch 連発
Cycle detection 失敗	infinite recursion

→ 本文 BiblioFetch.jl の "max_depth / max_refs_per_paper" の安全弁を MCP tool 側でも hard-cap すべき:

const CITATION_GRAPH_MAX_DEPTH: u32 = 3;       // user が parameter で 5 指定しても 3 で切る
const CITATION_GRAPH_MAX_REFS_TOTAL: u32 = 100; // 全 expansion 合計
const CITATION_GRAPH_MAX_REFS_PER_PAPER: u32 = 20;

「parameter は受け付けるが内部で hard-cap で切る」設計。 cap に当たったら truncated: true を結果に含めて agent に明示。

2. Citation graph と CapabilityProfile の関係

#16 §7 で提案した CapabilityProfile が citation graph に与える影響を Phase 4 spec で明記:

• citation graph の expansion で fetch するのは metadata のみ (PDF は fetch しない、 user が明示的に各 ref に対して fetch_paper を呼ぶ)
• metadata source は Crossref / Semantic Scholar / OpenAlex (Phase 4 で追加される Tier 2)
• 各 source の rate limit を尊重: S2 の rate limit は厳しい (1 req/sec without API key)
• TDM source は citation graph expansion に 使わない (TDM API は 個別 ref fetch 用、 graph traversal は ToS が grey)

これは Phase 4 着手時に実装で守らせる: expand_citation_graph 内部で TDM source を呼べないように capability check を必須化。

3. MCP tool spec (Phase 4 で公開予定)

#8 review で提案した命名 / error 規約に従って:

doiget_expand_citation_graph(
  ref: string,
  depth?: number,           // default 1, max 3
  max_refs_per_paper?: number, // default 10, max 20
  format?: "edgelist"|"mermaid"|"dot",  // default "edgelist"
): {
  ok: true,
  root: string,
  nodes: Array<{ ref: string, title?: string, year?: number }>,
  edges: Array<{ from: string, to: string }>,
  truncated: boolean,
  truncation_reason?: "max_depth"|"max_total"|"rate_limited",
} | { ok: false, error: ... }

注意点:

• output に PDF path は含めない (citation graph は metadata-only)
• truncated flag を必須に (LLM agent が「全部取れた」と誤認するのを防ぐ)
• mermaid / DOT format は LLM が visualization tool に渡しやすい

4. Cycle detection は明示的に必要

paper A が paper B を引用、 B が C を引用、 C が A を引用 (= cycle) は実在する (議論論文 / response paper 等)。 expansion で BFS 中に visited set で skip する spec を明記:

fn expand(root: &Ref, depth: u32) -> Graph {
    let mut visited = HashSet::new();
    let mut queue = VecDeque::from([(root.clone(), 0)]);
    while let Some((node, d)) = queue.pop_front() {
        if d >= depth { break; }
        if !visited.insert(node.clone()) { continue; }   // skip cycle
        for child in fetch_refs(&node) {
            if !visited.contains(&child) {
                queue.push_back((child, d + 1));
            }
        }
    }
    ...
}

5. Citation graph の incremental persistence

BiblioFetch.jl の citation graph 結果が ephemeral (実行ごと再 fetch) かどうか本文では不明。 Phase 4 で reviewer 推奨:

• expansion 中に取得した metadata を ~/.cache/doiget/citations/<safekey>.toml に 永続化
• 同じ root で再 expand したら cache hit で network 呼ばない (ttl = 30 日)
• これは provenance log とは別物 (audit log とは独立した cache)
• cache disable: --no-cache flag

これで agent loop で何度も同じ graph を走らせても rate limit を消費しない。

6. Phase 4 スコープ確定 (本文 "1 週" の中身)

reviewer 提案で Phase 4 を以下に分解:

1. Tier 2 source 追加 (S2 + OpenAlex) — 2 日
2. metadata-only fetch path 実装 (PDF fetch とは別 code path) — 1 日
3. citation graph expansion + cycle detection + hard-cap — 2 日
4. expand_citation_graph MCP tool exposing — 1 日
5. mermaid / DOT format generator — 1 日
6. cache layer + integration test — 1 日

合計 8 日 (本文の "4 日" より大きい)。 単純な expand ではなく safety / cache / format / test を含めると現実的に 1 週半。

Reviewer Decision proposal

• Decision: A (Phase 4 で追加)
• expansion hard-cap (depth=3, total=100, per-paper=20) を library const として lock
• TDM source は citation graph で 使わない (capability check 必須)
• MCP tool spec: doiget_expand_citation_graph を [design] MCP server が公開する tool の名前と signature #8 命名規約で実装
• cycle detection を visited set で実装
• cache layer (~/.cache/doiget/citations/) で 30 日 ttl
• Phase 4 工数を 4 日 → 1 週半に再見積もり ([plan] Phase 計画と timeline #7 で更新)

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.