API PubMed

Prérequis

uv: Lisez la skill uv et suivez ses instructions de configuration pour vérifier que uv est installé et accessible depuis PATH.
Notification utilisateur: Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans ce répertoire de skill, alors (1) avertissez l'utilisateur de consulter les conditions à https://pubmed.ncbi.nlm.nih.gov/disclaimer/ et https://www.ncbi.nlm.nih.gov/home/about/policies/, et de toujours vérifier la licence des articles récupérés par la skill pour identifier les restrictions, puis (2) créez le fichier enregistrant le texte de notification et l'horodatage.
Fichier .env: Assurez-vous que le fichier .env existe dans votre répertoire home. Créez-en un s'il n'existe pas.
NCBI_API_KEY (optionnel): Augmente la limite de débit NCBI E-utilities de 3 à 10 requêtes/seconde. La skill fonctionne sans elle, mais une clé est recommandée si l'utilisateur prévoit de nombreuses requêtes ou rencontre une erreur 429. L'utilisateur peut en obtenir une gratuitement en s'inscrivant à https://www.ncbi.nlm.nih.gov/account/settings/
USER_EMAIL (optionnel mais recommandé): Identifie l'appelant auprès de NCBI (recommandé par leurs Conditions d'utilisation).

Si les variables sont manquantes dans .env, ne demandez PAS à l'utilisateur de les coller dans le chat (ce qui fuirait les clés dans le contexte de l'agent). À la place, fournissez à l'utilisateur ces commandes — en remplaçant ENV_FILE par le chemin littéral résolu vers le fichier .env:

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

printf "Enter contact email: " && read email && echo "USER_EMAIL=$email" >> "ENV_FILE" && echo "Saved."

Les scripts chargent automatiquement les credentials via dotenv. Ne JAMAIS lire, afficher, ou inspecter le fichier .env ou ses variables (par exemple pas de cat, grep, echo, printenv, ou os.environ.get sur les clés). Les credentials doivent rester en dehors du contexte de l'agent.

Cette skill fournit un accès CLI aux APIs NCBI PubMed et PubMed Central via scripts/pubmed_api.py — un CLI unique avec 10 fonctions couvrant la recherche, la récupération, la liaison, le texte intégral, la vérification d'orthographe, la découverte, la correspondance de citations et la mise en cache.

Règles principales

Utilisation de l'API: Utilisez toujours le wrapper fourni scripts/pubmed_api.py qui gère automatiquement les limites de débit et prévient les abus d'API. Configurer la variable d'environnement NCBI_API_KEY augmente la limite de débit de 3 à 10 requêtes/seconde. Interroger l'API d'une autre manière (par exemple via curl, wget ou code écrit à la main) est strictement interdit.
Traitement JSON: Utilisez jq pour filtrer et transformer la sortie JSON (ou les équivalents Python si jq n'est pas disponible) afin de prévenir les hallucinations et le débordement de contexte.
Fichiers temporaires: Pour éviter de polluer le répertoire de travail avec des fichiers JSON, utilisez un répertoire temporaire dans le répertoire courant. Lors de l'exécution de plusieurs agents ou tâches en parallèle, assurez-vous que chacun utilise un nom de sous-répertoire unique (par exemple, tmp_$TASK_ID/) pour éviter les collisions de fichiers.
Notification: Si cette skill est utilisée, assurez-vous que cela est mentionné dans la sortie ET listez les URLs de tous les articles qui ont été utilisés pour produire la sortie.

Structure du répertoire de la skill

SKILL.md - Ce fichier
scripts/pubmed_api.py - Le CLI de la skill
references/ - Répertoire avec les spécifications détaillées des fonctions
- advanced-linking.md
- advanced-search.md
- bulk-workflows.md
- citation-matching.md
- cross-database-linking.md
- fetch-and-resolve.md
- search-and-discovery.md
- utilities.md

Utilisation du CLI

uv run scripts/pubmed_api.py <output_file> <function_name> <required_args> [--flag value ...]

Arguments positionnels: Les arguments sont positionnels; les arguments de liste sont passés sous forme de chaînes séparées par des virgules sans espaces (par exemple "35113657,31234568").
Options avec drapeau: Les arguments optionnels peuvent être passés sous la forme --flag value au lieu d'arguments positionnels.
Gestion de la sortie: En cas de succès, JSON est écrit dans output_file. En cas d'erreur, le processus se termine avec un code non nul et aucun fichier de sortie n'est créé.

Exemple d'utilisation

uv run scripts/pubmed_api.py ./search_results.json search_pubmed "BRCA1" --max_results 5
cat ./search_results.json | jq '.[]' -r
uv run scripts/pubmed_api.py ./abstracts.json fetch_article_abstracts "35113657"
cat ./abstracts.json | jq '.[0].title' -r

Recettes essentielles

Joindre les PMIDs pour l'appel suivant (motif de chaînage le plus courant):

cat ./search_results.json | jq -r 'join(",")'

Simplifier les abstracts aux champs essentiels et tronquer les longs abstracts:

cat ./abstracts.json | jq '[.[] | {pmid, title, snippet: (.abstract // "")[:500]}]'

Filtrer par mot-clé (null-safe):

cat ./abstracts.json | jq '[.[] | select((.title // "") | contains("Review"))]'

Gestion du contexte et précision

Lors du traitement de plus grands ensembles de résultats (>10 abstracts):

Filtrer en premier: Utilisez jq pour vérifier les mots-clés dans les abstracts avant de lire l'intégralité du JSON dans le contexte.
Simplification: Extrayez uniquement les champs title et abstract sauf instruction explicite contraire. Les listes d'auteurs et les métadonnées contribuent au bruit.
Opérations en masse (N > 10): Évitez de récupérer ou traiter les IDs un par un. L'API et le serveur d'historique sont conçus pour la récupération en masse. Récupérez toutes les données en un seul tour et utilisez les pipelines shell pour simplifier les résultats avant de les lire dans le contexte. Cela prévient l'épuisement des tours et le débordement de contexte.
Ancrage: Ne jamais utiliser les connaissances internes pour fournir des identifiants spécifiques (PMIDs, CIDs, Gene IDs) si aucun résultat n'est trouvé. Rapportez la sortie de l'outil avec précision pour assurer que les résultats sont ancrés dans l'état actuel de la base de données.
Arrêt de la recherche: Lorsqu'on vous demande de trouver des articles qui pourraient ne pas exister, limitez l'exploration à 3–5 requêtes de recherche variées et de haute qualité. Si aucun résultat ne correspond après ces tentatives, concluez qu'aucun article ne répond aux critères plutôt que de continuer à itérer — sauf instruction explicite d'être approfondi.

Fonctions

⚠️ OBLIGATOIRE: Vous DEVEZ lire le fichier de référence lié pour un groupe de fonctions avant d'appeler une fonction de ce groupe. Les tableaux ci-dessous décrivent uniquement ce que chaque fonction fait — pas comment l'appeler. Les noms d'arguments, l'ordre des arguments, les drapeaux et les schémas de sortie sont uniquement documentés dans les fichiers de référence. Ne DEVIREZ PAS ou n'inférez PAS les arguments à partir des noms de fonctions. Si vous appelez une fonction sans d'abord lire sa référence, vous produirez des invocations incorrectes.

Recherche

search_pubmed: Trouver les PMIDs correspondant à une requête NCBI en texte libre ou structurée.
global_database_discovery: Compter combien d'enregistrements correspondent à une requête dans chaque base de données NCBI.

Récupération et résolution

fetch_article_abstracts: Récupérer les métadonnées et abstracts pour un lot de PMIDs.
get_full_text_pmc: Récupérer le texte intégral en libre accès depuis PMC.
fetch_database_summary: Résoudre les UIDs opaques de n'importe quelle base de données NCBI en métadonnées lisibles.

Liaison inter-bases de données

find_linked_biological_data: Trouver les enregistrements dans d'autres bases de données NCBI liés à un enregistrement source.
discover_available_links: Lister tous les noms ELink disponibles pour un enregistrement donné.

Flux de travail en masse

Lors du travail avec plus d'environ 10 PMIDs, évitez de traiter les IDs un par un. Téléchargez-les sur le serveur d'historique NCBI via cache_results_history pour obtenir un handle de session (webenv + query_key), puis passez ce handle à fetch_article_abstracts ou find_linked_biological_data pour un appel en masse unique. Chaînez avec les pipelines shell jq pour simplifier les résultats avant de les lire dans le contexte. Cela prévient l'épuisement des tours et le débordement de contexte. Consultez la référence pour les recettes complètes du flux de travail (recherche→récupération, exploration inter-bases, résolution de citations et récupération en masse avec simplification des données).

cache_results_history: Télécharger les PMIDs sur le serveur d'historique NCBI pour la récupération en masse.

Utilitaires

verify_medical_spelling: Vérifier l'orthographe des termes biomédicaux avant la recherche.
match_raw_citations: Résoudre les citations bibliographiques incomplètes en PMIDs.

pubmed-database