Compétence OpenAlex

Prérequis

1. uv : Lisez la compétence uv et suivez ses instructions de configuration pour vous assurer que uv est installé et accessible dans PATH.

2. Notification à l'utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette compétence, alors (1) notifiez bien visiblement l'utilisateur de consulter les conditions à https://developers.openalex.org/ et de toujours vérifier la licence des articles récupérés par la compétence pour détecter toute restriction, puis (2) créez le fichier enregistrant le texte et l'horodatage de la notification.

3. Fichier .env : Assurez-vous que le fichier .env existe dans votre répertoire personnel. Créez-en un s'il n'existe pas.

4. OPENALEX_API_KEY (optionnel mais recommandé) : Active l'API Premium OpenAlex avec des limites de taux plus élevées. La compétence fonctionne sans elle (en utilisant le « polite pool » gratuit). Si la variable est absente de .env, ne DEMANDEZ PAS à l'utilisateur de la coller dans le chat (cela fuirait la clé dans le contexte de l'agent). À la place, donnez à l'utilisateur cette commande — en remplaçant ENV_FILE par le chemin littéral résolu du fichier .env :

   printf "Enter OpenAlex API key (typing hidden): " && read -s key && echo && echo "OPENALEX_API_KEY=$key" >> "ENV_FILE" && echo "Saved."

   Les scripts chargent automatiquement les identifiants via dotenv. NE JAMAIS lire, afficher ou inspecter le fichier .env ou ses variables (pas de cat, grep, echo, printenv, ou os.environ.get sur les clés). Les identifiants doivent rester en dehors du contexte de l'agent. Voir la section Limites de taux pour plus de détails.

Règles de base

1. Lister les sources. Si cette compétence est utilisée, assurez-vous que cela est mentionné dans la sortie ET listez les URL de tous les articles utilisés pour produire la sortie.
2. Résoudre avant filtrer. NE JAMAIS filtrer par nom. Toujours resolve un nom vers un ID d'abord, puis utiliser cet ID dans --filter.
3. Utiliser uniquement la CLI. Ne jamais appeler l'API via curl/urllib. La CLI gère les tentatives et la limitation de taux.
4. Pas de fabrication. Ne jamais inventer d'IDs OpenAlex ou de DOIs. Utilisez resolve/get pour les chercher. Signalez les résultats vides avec précision.
5. Clé API. Si une commande retourne 401/429 ou si vous avez besoin de requêtes à gros volume, suivez les instructions préalables ci-dessus pour aider l'utilisateur à ajouter OPENALEX_API_KEY au fichier .env. Les clés se trouvent sur OpenAlex.org → paramètres du compte.
6. Garder la sortie petite. Toujours utiliser --select et --per-page 5–10 pour les requêtes d'aperçu. Diriger la sortie de filter vers un fichier (> results.json), puis réduire avec jq avant de lire dans le contexte.

Limites de taux

• Avec clé : ~10 req/s, budget gratuit de 1 $/jour.
• Sans clé : Très limité, budget de 0,01 $/jour.

Référence CLI

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

Types d'entité (partagés entre les commandes) : works, authors, sources, institutions, topics, domains, fields, subfields, sdgs, countries, continents, languages, keywords, publishers, funders, work-types, source-types, institution-types, licenses

Commandes

resolve <entity> <query> — Nom → Candidats ID. Retourne id, display_name, hint. Utilisez --per-page N pour plus de candidats.

get <entity> <id> — Métadonnées complètes pour une entité. Accepte l'ID court (W2741809807), l'URL complète, ou l'URL DOI. Utilisez --select pour limiter les champs.

filter <entity> — Rechercher/filtrer les entités. Les drapeaux clés sont :

• --search <query> : Recherche en texte intégral (coût 10× supérieur à --filter)
• --filter <expr> : Expressions de filtre. Utilisez , pour ET et | pour OU.
• --sort <field:dir> : Trier les résultats (par ex. cited_by_count:desc)
• --select <fields> : Limiter les champs retournés dans la sortie.
• --group-by <field> : Agréger les résultats par un champ spécifique.
• --per-page <N> : Nombre de résultats par page (défaut 25, max 100).
• --page <N> : Spécifier le numéro de page à récupérer.
• --sample <N> : Obtenir un échantillon aléatoire de jusqu'à 10 000 résultats.
• --seed <N> : Graine pour l'échantillonnage reproductible.

download-pdf <work-id> <output-path> — Télécharger le PDF (nécessite une clé API). Bascule vers les emplacements pdf_url alternatifs en cas d'échec du primaire. Chaque fois que vous téléchargez un PDF, vérifiez qu'il n'est pas vide ou corrompu.

rate-limit — Vérifier le statut actuel de la limite de taux (nécessite une clé API).

Conseils de recherche

• Si resolve ne retourne aucune correspondance, essayez d'autres orthographes ou abréviations.
• Si --search retourne 0 résultats, essayez des termes plus larges (max 3 tentatives).
• Si resolve retourne plusieurs candidats, présentez-les à l'utilisateur avec display_name et hint pour une sélection manuelle.

Références d'entités

Consultez references/ pour les champs de filtre, tri et groupement valides par entité :

• Works — Authors — Sources
• Institutions — Topics — Taxonomy
• Geo & Language — Publishers & Funders
• Type Values

Flux de travail courants

# Travaux d'un auteur (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}]'

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

# Recherche DOI en masse (jusqu'à 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

# Impact institutionnel par année
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

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

Gestion des erreurs

Filtres réservés premium connus : from_updated_date, to_updated_date.

Ne jamais fabriquer de résultats sur des réponses vides — signalez avec précision et suggérez des termes de recherche alternatifs.