literature-search-openalex

OpenAlex Skill

前提条件

1. uv：uv スキルを読み、セットアップ手順に従って uv がインストールされ、PATH に設定されていることを確認してください。
2. ユーザーへの通知：.licenses/literature_search_openalex_LICENSE.txt がワークスペースのルートディレクトリに存在しない場合は、（1）https://help.openalex.org/ の利用規約を確認し、このスキルで取得した論文に制限がないか、必ずライセンスを確認するようユーザーに目立つ形で通知し、（2）通知文とタイムスタンプを記録したファイルを作成してください。
3. .env ファイル：ホームディレクトリに .env ファイルがあることを確認してください。存在しない場合は作成してください。
4. OPENALEX_API_KEY（任意ですが推奨）：このスキルはキーなしでも動作しますが、キーなしのリクエストでは IP アドレスごとに 1 日あたり $0.10 の予算を共有します。無料キーには 1 日あたり $1 の独自の予算と、より高いレート制限があります。また、content.openalex.org から全文をダウンロードするにはキーが必要です（download-pdf）。mailto（以前の「polite pool」）を追加しても、レート制限は緩和されなくなりました。無料キーは OpenAlex.org → アカウント設定から取得できます。このキーの有無を確認するとき、またはキーを求めるときは、設定されていない場合でもキーなしでの実行を妨げることなく、credentials スキルの安全な認証情報プロトコルを必ず使用してください。

基本ルール

1. 情報源を列挙する。 このスキルを使用した場合は、出力にその旨を記載し、出力の作成に使用したすべての論文の URL を列挙してください。
2. 絞り込む前に解決する。 名前で絞り込むことは絶対に避けてください。まず必ず名前を resolve で ID に解決し、その ID を --filter で使用してください。
3. CLI のみを使用する。 curl／urllib を使って API を呼び出さないでください。CLI が再試行とレート制限を処理します。
4. 捏造しない。 OpenAlex ID や DOI を作り出さないでください。resolve／get を使用して検索してください。結果が空の場合は、そのとおり正確に報告してください。
5. API キー。 コマンドが 401 を返す場合、レート制限または 1 日あたりの予算超過により 429 を返す場合、あるいは大量のクエリが必要な場合は、ユーザーが .env ファイルに追加できるよう、credentials スキルの安全な認証情報プロトコルを使用して OPENALEX_API_KEY の有無を確認し、キーの使用を求めることが必須です。無料キーでは、429 の Plan upgrade required エラーは解消されません。
6. 出力を小さく保つ。 概要クエリでは常に --select と --per-page 5–10 を使用してください。filter の出力はファイルにパイプ（> results.json）し、読み込む前に jq で必要な項目に絞り込んでください。

レート制限

• キーなし： 10 req/s。IP アドレスごとに 1 日あたり $0.10 の予算で、同じ IP からのキーなしのリクエストすべてで共有されます。
• 無料キーあり： 30 req/s。1 日あたり $1 の予算です。
• 年間プラン： 50 req/s。

操作	コスト
単一の get	無料
filter	$0.0001
--search／resolve	$0.001
download-pdf	$0.01

CLI リファレンス

uv run scripts/openalex_cli.py [--api-key KEY] <command> [flags]

コマンド間で共通のエンティティタイプ：works、authors、sources、 institutions、topics、domains、fields、subfields、sdgs、countries、 continents、languages、keywords、publishers、funders、work-types、 source-types、institution-types、licenses

コマンド

resolve <entity> <query> — 名前から ID 候補を検索します。id、 display_name、hint を返します。候補を増やすには --per-page N を使用します。

get <entity> <id> — 1 つのエンティティの完全なメタデータを取得します。短縮 ID （W2741809807）、完全な URL、または DOI URL を指定できます。返すフィールドを制限するには --select を使用します。

filter <entity> — エンティティを検索／フィルタリングします。主なフラグは次のとおりです。

• --search <query>：全文検索（--filter の 10 倍のコスト）
• --filter <expr>：フィルタ式。AND には ,、OR には | を使用します。
• --sort <field:dir>：結果を並べ替えます（例：cited_by_count:desc）
• --select <fields>：出力で返すフィールドを制限します。
• --group-by <field>：指定したフィールドで結果を集計します。
• --per-page <N>：1 ページあたりの結果数（デフォルトは 25、最大 100）。
• --page <N>：取得するページ番号を指定します。
• --sample <N>：最大 10,000 件の結果からランダムなサンプルを取得します。
• --seed <N>：再現可能なサンプリングのためのシード値。

download-pdf <work-id> <output-path> — PDF をダウンロードします （content.openalex.org には OPENALEX_API_KEY が必要です。認証されていない場合、またはプライマリサーバーに障害が発生した場合は、work のメタデータにある代替の pdf_url の場所にフォールバックします）。必ず download-pdf を実行し、ダウンロードした PDF が空でなく、破損していないことを確認してください。OPENALEX_API_KEY がない場合は、ユーザーが追加できるよう credentials スキルも参照してください。

rate-limit — 現在のレート制限と 1 日あたりのクレジット状況を確認します（キーがない場合は IP ごとの共有制限を、OPENALEX_API_KEY が設定されている場合はキーごとの制限を報告します。OPENALEX_API_KEY が設定されていない場合は、ユーザーが追加できるよう credentials スキルも参照してください）。

検索のヒント

• resolve で一致する結果がない場合は、別の綴りや略語を試してください。
• --search で結果が 0 件の場合は、より広い検索語を試してください（再試行は最大 3 回）。
• resolve で複数の候補が返された場合は、手動で選択できるよう display_name と hint を添えてユーザーに提示してください。

エンティティの参照情報

各エンティティで有効なフィルタ、並べ替え、グループ化のフィールドについては、references/ を参照してください。

• 著作物 — 著者 — 情報源
• 機関 — トピック — 分類体系
• 地域と言語 — 出版社と資金提供者
• タイプ値

ここに記載されていない内容や、API の動作がこのスキルの説明と異なる場合は、公式ドキュメントのインデックス https://help.openalex.org/llms.txt を確認してください。

一般的なワークフロー

# Author's works (resolve → filter)
uv run scripts/openalex_cli.py resolve authors "Geoffrey Hinton"
uv run scripts/openalex_cli.py filter works \
  --filter "authorships.author.id:A5108093963" \
  --sort "cited_by_count:desc" --per-page 10 > papers.json
cat papers.json | jq '[.results[] | {id, title: .display_name, year: .publication_year, citations: .cited_by_count}]'

# DOI lookup
uv run scripts/openalex_cli.py get works "https://doi.org/10.1038/s41586-021-03819-2"

# Bulk DOI lookup (up to 100)
uv run scripts/openalex_cli.py filter works \
  --filter "doi:10.1234/a|10.1234/b|10.1234/c" --per-page 100 > results.json

# Institutional impact by year
uv run scripts/openalex_cli.py resolve institutions "MIT"
uv run scripts/openalex_cli.py filter works \
  --filter "authorships.institutions.id:I63966007" \
  --group-by "publication_year" > mit_by_year.json

# Random sample
uv run scripts/openalex_cli.py filter works \
  --filter "publication_year:2023,is_oa:true" \
  --sample 100 --seed 42 > results.json

エラー処理

CLI は、Plan upgrade required の場合を除き、429 エラーをバックオフしながら再試行します。この場合は説明を表示して直ちに失敗します。どちらの種類もむやみに再試行しないでください。エラー出力の Server body で区別できます。

コード	意味	対処
401	認証されていません	ユーザーが .env に API キーを追加できるよう、credentials スキルの安全な認証情報プロトコルを必ず使用してください
404	見つかりません	ID を確認してください。まず resolve を試してください
429	Body に Plan upgrade required と記載	有料プランの機能です（プランで制限されたフィルタなど）。再試行しないでください。無料のキーでは解決しません。フィルタを削除するか、ユーザーに伝えてください。https://openalex.org/pricing を参照してください
429	Body にレート制限または予算超過と記載	キーがない場合：ユーザーが .env に API キーを追加できるよう、credentials スキルの安全な認証情報プロトコルを必ず使用してください。キーがある場合：待ってから再試行するか（レート制限）、1 日の予算を使い切ったことをユーザーに伝えてください

プランで制限されたフィルタとして判明しているもの：from_created_date、 from_updated_date、 to_updated_date。

結果が空の場合は、決して結果を捏造せず、正確に報告して別の検索語を提案してください。