arxiv-search

arXiv 検索（メタデータ優先）

トリガーとルーティング

• トリガー: arXiv、arxiv、論文検索、メタデータ取得、文献検索、論文検索、メタデータの取り込み、オフラインインポート。
• 使用する場面: arXiv を情報源として、初期論文セット（survey/snapshot の Stage C1）が必要な場合（オンライン検索またはオフラインでの export インポート）。

後続のランキング、分類体系の構築、引用生成を支援できるだけのメタデータを含む初期論文セットを収集します。

オンラインの場合は、arXiv の豊富なメタデータ（categories、arxiv_id、pdf_url、published/updated など）を優先します。オフラインの場合は、export を受け取り、適切に変換します。

読み込み順序

必ず読み込むファイル：

• references/domain_pack_overview.md — ドメインパックがトピック固有の動作をどのように制御するか

ドメインパック（トピックが一致した場合に読み込み）：

• assets/domain_packs/llm_agents.json — LLM エージェントのトピック向けの固定 ID とクエリ書き換えルール

スクリプトの境界

scripts/run.py を使用するのは、次の処理に限ります。

• arXiv API からの取得と XML の解析
• オフライン export の変換（CSV/JSON/JSONL の正規化）
• id_list によるメタデータの補完

次の用途に run.py を使用しないでください。

• トピックの検出やクエリの書き換えのハードコーディング（ドメインパックを使用）
• ドメイン固有の固定論文リスト（assets/domain_packs/ に外部化）

コントラクトに基づく動作

• 幅広い検索を行うワークフローでは、ドメインパックによるクエリの書き換えがデフォルトです。
• 焦点を絞ったワークフローでは、 quality_contract.retrieval_policy.domain_pack_query_mode: explicit を設定できます。このモードでは、 queries.md のクエリリストが引き続き優先され、ドメイン パックによってトピックの焦点を置き換えてはなりません。
• quality_contract.retrieval_policy.minimum_records は、ワークフローの未処理候補プールの下限を、厳格な品質ゲートのチェック条件にします。

入力

• queries.md（キーワード、除外条件、期間）

出力

• papers/papers_raw.jsonl（JSONL。1 行につき 1 論文）
  • 各レコードには、少なくとも title、authors、year、url、abstract が含まれます。
  • オンラインの arXiv API モードでは、レコードに役立つメタデータも含まれます：arxiv_id、pdf_url、categories、primary_category、published、updated、doi、journal_ref、comment
• 利便性のためのインデックス（任意ですが、スクリプトで生成されます）：
  • papers/papers_raw.csv

判断：オンラインとオフライン

• ネットワークに接続できる場合：arXiv API から取得します。
• 接続できない場合：ユーザーが提供する export（CSV/JSON/JSONL）をインポートし、フィールドを正規化します。
• ハイブリッド：オフラインでインポートした後にネットワークを利用できるようになった場合は、--enrich-metadata または queries.md の enrich_metadata: true を使用して、arXiv の id_list 経由で不足フィールド（abstract/authors/categories）を補完できます。

ワークフロー（ヒューリスティック）

1. queries.md を読み、具体的なクエリ文字列に展開します。
2. オンラインで検索結果を取得するか、オフラインで export をインポートします。
3. すべてのレコードを正規化し、少なくとも次の項目を含めます。
   • title、authors（配列）、year、url、abstract
4. この段階では対象を幅広く保ちます。重複排除とランキングは次の段階で行います。
5. 指定されている場合は、期間と max_results を適用します。

品質チェックリスト

• papers/papers_raw.jsonl が存在する。
• 各行が有効な JSON であり、title、authors、year、url が含まれている。

副作用

• 許可：papers/papers_raw.jsonl の作成・上書き、STATUS.md へのメモの追記。
• 禁止：執筆が承認される前に、output/ に文章のセクションを書き込むこと。

スクリプト

クイックスタート

• uv run python .codex/skills/arxiv-search/scripts/run.py --help
• オンライン：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query "<query>" --max-results 200
• オフラインインポート：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --input <export.csv|json|jsonl>

すべてのオプション

• --query <q>：複数回指定可能。複数のクエリの結果を統合します。
• --exclude <term>：複数回指定可能。取得後に除外条件を適用します。
• --max-results <n>：取得件数の上限
• --input <export.*>：オフラインモード（CSV/JSON/JSONL）
• --enrich-metadata：arXiv の id_list 経由で可能な範囲でメタデータを補完します（ネットワーク接続が必要）。
• queries.md では、keywords、exclude、time window、max_results、enrich_metadata も指定できます。

使用例

• オンライン（複数クエリ＋除外語）：
  • uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query "LLM agent" --query "tool use" --exclude "survey" --max-results 300
• arXiv ID を指定して論文を取得（id_list による直接取得）：
  • uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace> --query 2509.02547 --max-results 1
• オフラインで自動検出（フラグなし）：
  • papers/import.csv（または .json/.jsonl）をワークスペース内に配置してから、次を実行します：uv run python .codex/skills/arxiv-search/scripts/run.py --workspace <workspace>
• オフラインでのインポート＋期間指定（queries.md 経由）：
  • - time window: { from: 2022, to: 2025 } を設定してから、通常どおりオフラインインポートを実行します

トラブルシューティング

よくある問題

問題：papers/papers_raw.jsonl が空です

症状：

• スクリプトが「No results returned …」と表示して終了するか、出力ファイルが空です。

原因：

• ネットワークがブロックされています（オンラインモード）。
• クエリの範囲が狭すぎるか、queries.md が空です。

解決策：

• オフラインインポートを使用します。papers/import.csv|json|jsonl をワークスペースに配置するか、--input を渡します。
• キーワードの範囲を広げ、queries.md の除外語を減らします。
• --query を明示して実行し、パーサーが正常に動作することを確認します。

問題：オフラインインポートのレコードにフィールドが不足しています

症状：

• レコードに authors/year/abstract/url がなく、後続のステップが失敗します。

原因：

• エクスポートの列が想定されるフィールドと一致していません。上流のエクスポートが不完全です。

解決策：

• エクスポートに少なくとも title、authors、year、url、abstract が含まれていることを確認します。
• 後からネットワークを利用できる場合は、--enrich-metadata を使って不足しているフィールドを補完します（可能な範囲で実施）。

復旧チェックリスト

• queries.md に空でない keywords があることを確認します（または --query を渡します）。
• オフラインの場合：ワークスペースに papers/import.* があることを確認して、再実行します。
• JSONL の行を 3～5 件抜き取り確認します。有効な JSON であり、必須フィールドが含まれていることを確認します。