ncbi-sequence-fetch

Par mkurman · zorai

Récupère des séquences protéiques et nucléotidiques depuis les bases de données NCBI via les E-utilities. Prend en charge la recherche directe par numéro d'accession, la traduction CDS, la recherche par gène et organisme, la recherche par locus, les séquences liées à PubMed, l'extraction de protéines issues de brevets, et la recherche de repli par organisme et longueur. À utiliser lorsque vous devez récupérer des séquences biologiques par numéro d'accession, nom de gène, tag de locus, identifiant PubMed ou numéro de brevet.

npx skills add https://github.com/mkurman/zorai --skill ncbi-sequence-fetch

Récupération de séquences NCBI

Prérequis

  1. uv : Consultez la skill uv et suivez ses instructions de configuration pour vérifier que uv est installé et accessible dans PATH.

  2. Notification utilisateur : Si le fichier LICENSE_NOTIFICATION.txt n'existe pas déjà dans le répertoire de cette skill, alors (1) notifiez l'utilisateur de manière visible pour qu'il consulte les conditions à https://www.ncbi.nlm.nih.gov/ et https://www.ncbi.nlm.nih.gov/home/about/policies/, 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. NCBI_API_KEY (optionnel) : Augmente la limite de débit NCBI de 3 à 10 requêtes/seconde. La skill fonctionne sans elle, mais une clé est recommandée si l'utilisateur prévoit plusieurs 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/. Si la variable manque dans .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 "Entrez la clé API NCBI (saisie masquée) : " && read -s key && echo && echo "NCBI_API_KEY=$key" >> "ENV_FILE" && echo "Enregistré."

    Les scripts chargent les identifiants automatiquement via dotenv. Ne LISEZ, N'AFFICHEZ ou N'INSPECTEZ JAMAIS le fichier .env ou ses variables (p. ex., 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.

Règles fondamentales

  • Utilisez le wrapper : EXÉCUTEZ TOUJOURS les scripts d'aide fournis pour interroger la base de données plutôt que d'y accéder directement. Les scripts appliquent automatiquement la limite de débit requise de manière graduelle.
  • Support des clés API : Si l'utilisateur fournit une NCBI_API_KEY dans son environnement, les limites de vitesse d'interrogation augmentent automatiquement de manière significative.
  • Notification : Si cette skill est utilisée, assurez-vous que cela est mentionné dans la sortie.

Aperçu

Encapsule les E-utilities Entrez de NCBI (efetch, esearch, elink, esummary) pour récupérer les séquences de protéines et de nucléotides. Fournit 10 sous-commandes couvrant l'ensemble des workflows de récupération de séquences :

  • fetch-protein — Recherche directe d'accession protéique (GenPept, RefSeq)
  • fetch-nucleotide — Recherche directe d'accession nucléotidique
  • cds-translate — Récupérer CDS et traduire en protéine (3 méthodes)
  • search — Recherche en texte libre dans n'importe quelle base de données NCBI
  • elink — Suivre les liens inter-bases de données (PubMed→Protéine, etc.)
  • gene-protein — Rechercher une protéine par nom de gène + organisme
  • locus-protein — Rechercher une protéine par locus tag + organisme
  • pubmed-proteins — Trouver les protéines liées à un article PubMed
  • patent-search — Extraire les séquences protéiques des brevets
  • organism-length — Recherche de dernier recours par organisme + longueur AA exacte

Scripts utilitaires

scripts/ncbi_fetch.py — Script unique avec sous-commandes.

Tous les sous-commandes produisent une sortie JSON structurée. Utilisez --output FILE pour enregistrer dans un fichier, ou omettez-le pour afficher sur stdout. Un résumé lisible par l'homme est toujours affiché sur stdout.

1. Récupérer une protéine par accession

Récupère la FASTA protéique de NCBI par accession (XP, NP, GenPept, etc.)

uv run scripts/ncbi_fetch.py fetch-protein XP_022033624 -o /tmp/result.json
uv run scripts/ncbi_fetch.py fetch-protein NP_001234567 ABC12345.1

2. Récupérer un nucléotide par accession

Récupère la FASTA nucléotidique de NCBI par accession.

uv run scripts/ncbi_fetch.py fetch-nucleotide MK034466 -o /tmp/result.json

3. Traduction CDS

Récupère une accession CDS/nucléotide et la traduit en séquence protéique. Essaie trois approches dans l'ordre : 1. La protéine CDS pré-traduite de NCBI (fasta_cds_aa) 2. Les traductions d'annotations CDS du XML GenBank 3. Recherche d'ORF sur 6 cadres du nucléotide brut

uv run scripts/ncbi_fetch.py cds-translate MK034466 -o /tmp/result.json
uv run scripts/ncbi_fetch.py cds-translate HQ662330 --target-length 1043

Si l'accession est un enregistrement génomique (pas d'ARNm/CDS), l'outil signalera is_genomic: true pour que vous puissiez revenir à une approche basée sur l'homologie.

4. Rechercher dans n'importe quelle base de données

Recherche en texte libre en utilisant la syntaxe de requête Entrez. Prend en charge toutes les bases de données NCBI.

# Rechercher dans la base de données des protéines
uv run scripts/ncbi_fetch.py search "WRR4B[Gene Name] AND Arabidopsis[Organism]" \
  --database protein --retmax 5 --fetch-sequences

# Rechercher dans la base de données nuccore
uv run scripts/ncbi_fetch.py search "Rz2[Gene Name] AND Beta vulgaris[Organism]" \
  --database nuccore --retmax 10

# Rechercher avec filtre de brevet
uv run scripts/ncbi_fetch.py search "disease resistance AND Solanum[Organism] AND patent[Properties]" \
  --database protein --fetch-sequences

# Rechercher par longueur de séquence
uv run scripts/ncbi_fetch.py search '"Oryza sativa"[Organism] AND 1043[SLEN]' \
  --database protein --fetch-sequences --retmax 50

5. Liens inter-bases de données (elink)

Suivre les liens inter-bases de données de NCBI (p. ex., article PubMed → protéines liées).

uv run scripts/ncbi_fetch.py elink 24896089 --dbfrom pubmed --db protein \
  --fetch-sequences -o /tmp/linked.json

6. Recherche par gène + organisme

Recherche les séquences protéiques par nom de gène et organisme. Recherche dans NCBI Protein avec les qualificateurs [Gene Name] et [Organism].

uv run scripts/ncbi_fetch.py gene-protein WRR4B --organism "Arabidopsis thaliana"
uv run scripts/ncbi_fetch.py gene-protein Pikh-2 --organism "Oryza sativa" \
  --target-length 1043 -o /tmp/result.json

7. Recherche par locus tag

Recherche par locus tag dans les bases de données NCBI Protein et Nuccore. Extrait les traductions CDS du XML GenBank quand les résultats directs sur les protéines ne sont pas disponibles.

uv run scripts/ncbi_fetch.py locus-protein At1g56540 --organism "Arabidopsis thaliana"
uv run scripts/ncbi_fetch.py locus-protein Niben101Scf02422g02015.1 \
  --organism "Nicotiana benthamiana" -o /tmp/result.json

8. Protéines liées à PubMed

Trouve les séquences protéiques liées à un article PubMed. Recherche dans NCBI Protein par PMID, suit elink PubMed→Protéine, et extrait les traductions CDS des enregistrements Nuccore liés.

uv run scripts/ncbi_fetch.py pubmed-proteins 30692254 --identifier WRR4B
uv run scripts/ncbi_fetch.py pubmed-proteins 24896089 --identifier "K2" \
  -o /tmp/result.json

9. Recherche de séquences dans les brevets

Deux modes :

Par numéro de brevet — récupère toutes les séquences protéiques d'un brevet spécifique :

uv run scripts/ncbi_fetch.py patent-search --patent-number US10123456 -o /tmp/patent.json

Par mots clés — recherche dans NCBI Protein avec le filtre patent[Properties] :

uv run scripts/ncbi_fetch.py patent-search --keywords WRR4B Albugo --organism "Arabidopsis thaliana" -o /tmp/patent.json

[!IMPORTANT] Convention des brevets : Dans les brevets en biologie moléculaire, SEQ ID NO: 1 est généralement la séquence d'ADN et SEQ ID NO: 2 est la protéine primaire. Les SEQ ID NOs plus élevés sont des variantes ou des séquences associées. Privilégiez la séquence 2 lors du choix de la protéine primaire d'intérêt.

10. Recherche par organisme + longueur

Recherche de dernier recours quand seuls l'organisme et la longueur protéique attendue sont connus. Utilise le filtre [SLEN] de NCBI pour une correspondance exacte de longueur.

uv run scripts/ncbi_fetch.py organism-length \
  --organism "Arabidopsis thaliana" --length 1048 --retmax 50 \
  -o /tmp/result.json

[!NOTE] Cela retourne souvent plusieurs candidats. Utilisez les en-têtes de sortie JSON pour identifier la protéine correcte.

Workflow

Cascade standard de récupération de séquences

Lors de la recherche d'une séquence protéique, suivez cet ordre de priorité :

  1. Accession directe — fetch-protein avec accession GenPept/RefSeq
  2. Traduction CDS — cds-translate avec accession nucléotide/CDS
  3. Liée à PubMed — pubmed-proteins avec PMID + nom de gène
  4. Recherche par locus — locus-protein avec locus tag + organisme
  5. Gène + organisme — gene-protein avec nom de gène + organisme
  6. Recherche de brevet — patent-search avec numéro de brevet ou mots clés
  7. Organisme + longueur — organism-length comme dernier recours

Interprétation des résultats

  • Tous les sous-commandes retournent du JSON avec un tableau results
  • Chaque résultat a sequence (chaîne AA), length, et header/métadonnées
  • Quand plusieurs résultats sont retournés, sélectionnez selon :
    • Correspondance la plus proche de la longueur attendue (target_length)
    • Pertinence de l'en-tête (correspondance du nom de gène, mots clés « disease resistance »)
    • Priorité de source (RefSeq > GenPept > brevet)

Référence

  • Documentation E-utilities NCBI : https://www.ncbi.nlm.nih.gov/books/NBK25499/
  • Syntaxe de recherche Entrez : https://www.ncbi.nlm.nih.gov/books/NBK49540/
  • Liste des bases de données : protein, nuccore, gene, pubmed, pmc, biosample, etc.
  • Formats d'accession courants :
    • XP_ / NP_ — Protéine RefSeq NCBI
    • AAA à AZZ + chiffres — GenPept (GenBank traduit)
    • MK, MN, HQ, etc. + chiffres — Nucléotide GenBank
    • ENSG, ENST, ENSP — Ensembl (utilisez la skill ensembl-database à la place)
    • Q, P, O + chiffres — UniProt (utilisez la skill uniprot-database à la place)

Skills similaires

eval-bootstrap
datadog-labs / agent-skills

Générer du code d'évaluation Python à partir de traces de production LLM Datadog.

126
pinecone-full-text-search
pinecone-io / skills

Créer et interroger un index full-text-search Pinecone avec l'API preview.

14
ad-model-onboard
nvidia / skills

Automatiser l'intégration de modèles HuggingFace dans AutoDeploy avec tests et rapport.

1 033
claude-api
anthropics / skills

Construire des applications LLM avec Claude via le SDK officiel adapté au langage.

146 960
clinvar-database
mkurman / zorai

Interroger la base ClinVar pour obtenir classifications cliniques et données de variants génomiques.

309