benchling-integration

Par mkurman · zorai

Intégration de la plateforme R&D Benchling. Accédez au registre (ADN, protéines), à l'inventaire, aux entrées ELN, aux workflows via l'API, créez des Benchling Apps, interrogez le Data Warehouse, pour l'automatisation de la gestion des données de laboratoire.

npx skills add https://github.com/mkurman/zorai --skill benchling-integration

Intégration Benchling

Aperçu

Benchling est une plateforme cloud pour la R&D en sciences de la vie. Accédez aux entités de registre (ADN, protéines), à l'inventaire, aux carnets de laboratoire électroniques et aux workflows de manière programmatique via le SDK Python et l'API REST.

Quand utiliser cette compétence

Cette compétence doit être utilisée quand :

  • Vous travaillez avec le SDK Python ou l'API REST de Benchling
  • Vous gérez les séquences biologiques (ADN, ARN, protéines) et les entités de registre
  • Vous automatisez les opérations d'inventaire (échantillons, conteneurs, emplacements, transferts)
  • Vous créez ou interrogez des entrées de carnets de laboratoire électroniques
  • Vous construisez des automations de workflows ou des applications Benchling
  • Vous synchronisez les données entre Benchling et des systèmes externes
  • Vous interrogez l'entrepôt de données Benchling pour l'analytique
  • Vous mettez en place des intégrations événementielles avec AWS EventBridge

Capacités principales

1. Authentification et configuration

Installation du SDK Python :

# Version stable
uv pip install benchling-sdk
# ou avec Poetry
poetry add benchling-sdk

Méthodes d'authentification :

Authentification par clé API (recommandée pour les scripts) :

from benchling_sdk.benchling import Benchling
from benchling_sdk.auth.api_key_auth import ApiKeyAuth

benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=ApiKeyAuth("your_api_key")
)

Authentification par identifiants client OAuth (pour les applications) :

from benchling_sdk.auth.client_credentials_oauth2 import ClientCredentialsOAuth2

auth_method = ClientCredentialsOAuth2(
    client_id="your_client_id",
    client_secret="your_client_secret"
)
benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=auth_method
)

Points clés :

  • Les clés API s'obtiennent dans les paramètres de profil de Benchling
  • Stockez les identifiants de manière sécurisée (utilisez des variables d'environnement ou des gestionnaires de mots de passe)
  • Toutes les demandes API nécessitent HTTPS
  • Les permissions d'authentification reflètent les permissions utilisateur dans l'interface

Pour des informations détaillées sur l'authentification, notamment OIDC et les bonnes pratiques de sécurité, consultez references/authentication.md.

2. Gestion des entités et du registre

Les entités de registre incluent les séquences ADN, les séquences ARN, les séquences AA, les entités personnalisées et les mélanges. Le SDK fournit des classes typées pour créer et gérer ces entités.

Création de séquences ADN :

from benchling_sdk.models import DnaSequenceCreate

sequence = benchling.dna_sequences.create(
    DnaSequenceCreate(
        name="My Plasmid",
        bases="ATCGATCG",
        is_circular=True,
        folder_id="fld_abc123",
        schema_id="ts_abc123",  # optional
        fields=benchling.models.fields({"gene_name": "GFP"})
    )
)

Enregistrement dans le registre :

Pour enregistrer une entité directement lors de sa création :

sequence = benchling.dna_sequences.create(
    DnaSequenceCreate(
        name="My Plasmid",
        bases="ATCGATCG",
        is_circular=True,
        folder_id="fld_abc123",
        entity_registry_id="src_abc123",  # Registre dans lequel enregistrer
        naming_strategy="NEW_IDS"  # ou "IDS_FROM_NAMES"
    )
)

Important : Utilisez soit entity_registry_id soit naming_strategy, jamais les deux.

Mise à jour des entités :

from benchling_sdk.models import DnaSequenceUpdate

updated = benchling.dna_sequences.update(
    sequence_id="seq_abc123",
    dna_sequence=DnaSequenceUpdate(
        name="Updated Plasmid Name",
        fields=benchling.models.fields({"gene_name": "mCherry"})
    )
)

Les champs non spécifiés restent inchangés, ce qui permet les mises à jour partielles.

Énumération et pagination :

# Énumérer toutes les séquences ADN (retourne un générateur)
sequences = benchling.dna_sequences.list()
for page in sequences:
    for seq in page:
        print(f"{seq.name} ({seq.id})")

# Vérifier le nombre total
total = sequences.estimated_count()

Opérations clés :

  • Créer : benchling.<entity_type>.create()
  • Lire : benchling.<entity_type>.get(id) ou .list()
  • Mettre à jour : benchling.<entity_type>.update(id, update_object)
  • Archiver : benchling.<entity_type>.archive(id)

Types d'entités : dna_sequences, rna_sequences, aa_sequences, custom_entities, mixtures

Pour une référence SDK complète et des modèles avancés, consultez references/sdk_reference.md.

3. Gestion de l'inventaire

Gérez les échantillons physiques, les conteneurs, les boîtes et les emplacements dans le système d'inventaire Benchling.

Création de conteneurs :

from benchling_sdk.models import ContainerCreate

container = benchling.containers.create(
    ContainerCreate(
        name="Sample Tube 001",
        schema_id="cont_schema_abc123",
        parent_storage_id="box_abc123",  # optional
        fields=benchling.models.fields({"concentration": "100 ng/μL"})
    )
)

Gestion des boîtes :

from benchling_sdk.models import BoxCreate

box = benchling.boxes.create(
    BoxCreate(
        name="Freezer Box A1",
        schema_id="box_schema_abc123",
        parent_storage_id="loc_abc123"
    )
)

Transfert d'articles :

# Transférer un conteneur vers un nouvel emplacement
transfer = benchling.containers.transfer(
    container_id="cont_abc123",
    destination_id="box_xyz789"
)

Opérations d'inventaire clés :

  • Créer des conteneurs, des boîtes, des emplacements, des plaques
  • Mettre à jour les propriétés des articles d'inventaire
  • Transférer les articles entre emplacements
  • Vérifier l'entrée/sortie des articles
  • Opérations batch pour les transferts en masse

4. Carnet et documentation

Interagissez avec les entrées des carnets de laboratoire électroniques (ELN), les protocoles et les modèles.

Création d'entrées de carnet :

from benchling_sdk.models import EntryCreate

entry = benchling.entries.create(
    EntryCreate(
        name="Experiment 2025-10-20",
        folder_id="fld_abc123",
        schema_id="entry_schema_abc123",
        fields=benchling.models.fields({"objective": "Test gene expression"})
    )
)

Liaison des entités aux entrées :

# Ajouter des références aux entités dans une entrée
entry_link = benchling.entry_links.create(
    entry_id="entry_abc123",
    entity_id="seq_xyz789"
)

Opérations clés du carnet :

  • Créer et mettre à jour les entrées de carnets de laboratoire
  • Gérer les modèles d'entrée
  • Lier les entités et les résultats aux entrées
  • Exporter les entrées pour la documentation

5. Workflows et automatisation

Automatisez les processus de laboratoire en utilisant le système de workflows de Benchling.

Création de tâches de workflow :

from benchling_sdk.models import WorkflowTaskCreate

task = benchling.workflow_tasks.create(
    WorkflowTaskCreate(
        name="PCR Amplification",
        workflow_id="wf_abc123",
        assignee_id="user_abc123",
        fields=benchling.models.fields({"template": "seq_abc123"})
    )
)

Mise à jour du statut de la tâche :

from benchling_sdk.models import WorkflowTaskUpdate

updated_task = benchling.workflow_tasks.update(
    task_id="task_abc123",
    workflow_task=WorkflowTaskUpdate(
        status_id="status_complete_abc123"
    )
)

Opérations asynchrones :

Certaines opérations sont asynchrones et retournent des tâches :

# Attendre la fin de la tâche
from benchling_sdk.helpers.tasks import wait_for_task

result = wait_for_task(
    benchling,
    task_id="task_abc123",
    interval_wait_seconds=2,
    max_wait_seconds=300
)

Opérations clés de workflow :

  • Créer et gérer les tâches de workflow
  • Mettre à jour les statuts et les affectations des tâches
  • Exécuter les opérations en masse de manière asynchrone
  • Surveiller la progression des tâches

6. Événements et intégration

Abonnez-vous aux événements Benchling pour les intégrations en temps réel en utilisant AWS EventBridge.

Types d'événements :

  • Création, mise à jour, archivage d'entités
  • Transferts d'inventaire
  • Modifications du statut des tâches de workflow
  • Création et mises à jour d'entrées
  • Enregistrement de résultats

Modèle d'intégration :

  1. Configurez le routage des événements vers AWS EventBridge dans les paramètres de Benchling
  2. Créez les règles EventBridge pour filtrer les événements
  3. Routez les événements vers des fonctions Lambda ou d'autres cibles
  4. Traitez les événements et mettez à jour les systèmes externes

Cas d'usage :

  • Synchroniser les données Benchling vers des bases de données externes
  • Déclencher les processus en aval lors de la fin du workflow
  • Envoyer les notifications lors des modifications d'entités
  • Journalisation de la piste d'audit

Consultez la documentation sur les événements de Benchling pour les schémas d'événements et la configuration.

7. Entrepôt de données et analytique

Interrogez les données historiques de Benchling en utilisant SQL via l'entrepôt de données.

Méthode d'accès : L'entrepôt de données Benchling fournit un accès SQL aux données Benchling pour l'analytique et le reporting. Connectez-vous à l'aide de clients SQL standard avec les identifiants fournis.

Requêtes courantes :

  • Agréger les résultats expérimentaux
  • Analyser les tendances d'inventaire
  • Générer les rapports de conformité
  • Exporter les données pour l'analyse externe

Intégration avec les outils d'analyse :

  • Notebooks Jupyter pour l'analyse interactive
  • Outils BI (Tableau, Looker, PowerBI)
  • Tableaux de bord personnalisés

Bonnes pratiques

Gestion des erreurs

Le SDK réessaye automatiquement les demandes échouées :

# Nouvelle tentative automatique pour les codes de statut 429, 502, 503, 504
# Jusqu'à 5 tentatives avec backoff exponentiel
# Personnalisez le comportement de nouvelle tentative si nécessaire
from benchling_sdk.retry import RetryStrategy

benchling = Benchling(
    url="https://your-tenant.benchling.com",
    auth_method=ApiKeyAuth("your_api_key"),
    retry_strategy=RetryStrategy(max_retries=3)
)

Efficacité de la pagination

Utilisez les générateurs pour une pagination efficace en mémoire :

# Itération basée sur des générateurs
for page in benchling.dna_sequences.list():
    for sequence in page:
        process(sequence)

# Vérifier le nombre estimé sans charger toutes les pages
total = benchling.dna_sequences.list().estimated_count()

Aide pour les champs de schéma

Utilisez l'aide fields() pour les champs de schéma personnalisés :

# Convertir le dict en objet Fields
custom_fields = benchling.models.fields({
    "concentration": "100 ng/μL",
    "date_prepared": "2025-10-20",
    "notes": "High quality prep"
})

Compatibilité prospective

Le SDK gère gracieusement les valeurs d'énumération et les types inconnus :

  • Les valeurs d'énumération inconnues sont préservées
  • Les types polymorphes non reconnus retournent UnknownType
  • Permet de travailler avec des versions API plus récentes

Considérations de sécurité

  • Ne validez jamais les clés API dans le contrôle de version
  • Utilisez les variables d'environnement pour les identifiants
  • Faites pivoter les clés en cas de compromission
  • Accordez les permissions minimales nécessaires pour les applications
  • Utilisez OAuth pour les scénarios multi-utilisateurs

Ressources

references/

Documentation de référence détaillée pour les informations approfondies :

  • authentication.md - Guide d'authentification complet, incluant OIDC, bonnes pratiques de sécurité et gestion des identifiants
  • sdk_reference.md - Référence SDK Python détaillée avec des modèles avancés, des exemples et tous les types d'entités
  • api_endpoints.md - Référence des endpoints d'API REST pour les appels HTTP directs sans le SDK

Chargez ces références selon les besoins pour des exigences d'intégration spécifiques.

scripts/

Cette compétence inclut actuellement des scripts d'exemple qui peuvent être supprimés ou remplacés par des scripts d'automatisation personnalisés pour vos workflows Benchling spécifiques.

Cas d'usage courants

1. Importation d'entités en masse :

# Importer plusieurs séquences depuis un fichier FASTA
from Bio import SeqIO

for record in SeqIO.parse("sequences.fasta", "fasta"):
    benchling.dna_sequences.create(
        DnaSequenceCreate(
            name=record.id,
            bases=str(record.seq),
            is_circular=False,
            folder_id="fld_abc123"
        )
    )

2. Audit d'inventaire :

# Énumérer tous les conteneurs dans un emplacement spécifique
containers = benchling.containers.list(
    parent_storage_id="box_abc123"
)

for page in containers:
    for container in page:
        print(f"{container.name}: {container.barcode}")

3. Automatisation de workflows :

# Mettre à jour toutes les tâches en attente pour un workflow
tasks = benchling.workflow_tasks.list(
    workflow_id="wf_abc123",
    status="pending"
)

for page in tasks:
    for task in page:
        # Effectuer des vérifications automatisées
        if auto_validate(task):
            benchling.workflow_tasks.update(
                task_id=task.id,
                workflow_task=WorkflowTaskUpdate(
                    status_id="status_complete"
                )
            )

4. Exportation de données :

# Exporter toutes les séquences avec des propriétés spécifiques
sequences = benchling.dna_sequences.list()
export_data = []

for page in sequences:
    for seq in page:
        if seq.schema_id == "target_schema_id":
            export_data.append({
                "id": seq.id,
                "name": seq.name,
                "bases": seq.bases,
                "length": len(seq.bases)
            })

# Enregistrer dans un CSV ou une base de données
import csv
with open("sequences.csv", "w") as f:
    writer = csv.DictWriter(f, fieldnames=export_data[0].keys())
    writer.writeheader()
    writer.writerows(export_data)

Ressources supplémentaires

Skills similaires

imaging-data-commons
mkurman / zorai

Interroger et télécharger des données d'imagerie médicale publiques depuis NCI IDC.

309
warehouse-init
astronomer / agents

Initialiser et générer un fichier de référence complet du schéma d'entrepôt de données.

382
diagnosing-failed-warehouse-syncs
posthog / skills

Diagnostiquer et réparer les synchronisations défaillantes d'un entrepôt de données.

45
omni-query
exploreomni / omni-agent-skills

Interroger la couche sémantique Omni via CLI pour extraire des données structurées.

17
zarr-python
mkurman / zorai

Stocker et manipuler efficacement de grands tableaux N-dimensionnels avec chunking et compression.

309