tamarind

Tamarind Bio

Tamarind Bio est une plateforme cloud qui exécute des outils de biologie computationnelle — prédiction de structure, conception de protéines et d'anticorps, docking, affinité de liaison, génération de MSA et dynamique moléculaire — sur des GPU gérés. Les utilisateurs soumettent des séquences ou des structures et reçoivent des structures prédites, des conceptions et des scores biophysiques, sans provisionner leur propre matériel. Elle expose des centaines d'outils (AlphaFold, Boltz-2, Chai-1, RFdiffusion, ProteinMPNN, BoltzGen, ESMFold2, DiffDock, Autodock Vina, et bien d'autres) via une API de jobs uniforme.

Documentation officielle : app.tamarind.bio/api-docs · interface utilisateur sur app.tamarind.bio

Sources canoniques — récupérez-les, ne vous fiez pas à une copie obsolète

Tamarind publie des sources vivantes et lisibles par machine. Préférez les récupérer à l'exécution plutôt que de faire confiance à une liste codée en dur — les noms d'outils, schémas et points d'accès changent fréquemment :

• https://app.tamarind.bio/llms.txt — Index LLM : liens vers la spécification, la documentation API et le guide MCP.
• https://app.tamarind.bio/openapi.yaml — Spécification OpenAPI 3.0 pour les 8 points d'accès principaux de jobs (submit-job/-batch, jobs, result, upload, files, delete-job/-file ; auth ApiKeyAuth). Récupérez-la pour ces formes exactes. Les points d'accès de découverte/gestion (/tools, /usage-statistics, pipelines, …) n'y figurent pas — utilisez les outils de découverte MCP/REST pour ceux-ci.
• https://docs.tamarind.bio/llms.txt — Index de documentation ; chaque page a une forme .md (par exemple docs.tamarind.bio/tamarind/batch.md, /tamarind/api.md, /tamarind/pipelines.md).
• Découverte en direct des outils — GET /tools (REST) ou MCP getAvailableTools + getJobSchema(jobType) sont la source de vérité pour savoir quels outils existent et leurs paramètres.

Ce skill enseigne la surface + les comportements non évidents que ces sources ne précisent pas (voir les fichiers de référence). En cas de doute sur une forme, récupérez openapi.yaml.

Quand utiliser ce skill

Utilisez Tamarind lorsque l'utilisateur souhaite :

• Prédire la structure d'une protéine, d'un complexe ou d'un système protéine-ligand (AlphaFold, Boltz-2, Chai-1, ESMFold2, co-repliement Chai/Boltz)
• Concevoir des protéines ou des liants (RFdiffusion, BoltzGen, BindCraft, repliement inverse ProteinMPNN/LigandMPNN)
• Concevoir ou caractériser des anticorps/nanocorps (génération de séquences, humanisation, développement, immunogénicité)
• Docker de petites molécules sur une protéine (DiffDock, Autodock Vina) ou prédire l'affinité de liaison
• Générer des MSA pour le repliement en aval
• Exécuter une dynamique moléculaire ou d'autres workflows biophysiques sur GPU gérés
• Cribler par lots de nombreuses séquences ou conceptions avec le même outil
• Enchaîner des outils en pipelines (par exemple conception → repliement → score) en utilisant la sortie d'un job comme entrée du suivant

Ce skill est approprié lorsque le travail doit s'exécuter sur le cloud géré de Tamarind plutôt que sur une installation locale. Pour la chémoinformatique purement locale ou la gestion de séquences ponctuelles, utilisez une bibliothèque locale (RDKit, BioPython) à la place.

Accès et authentification

1. Connectez-vous sur app.tamarind.bio et créez une clé API dans les paramètres du compte/API.
2. Authentifiez chaque requête REST avec l'en-tête x-api-key.
3. Ne codez jamais la clé en dur. Lisez-la depuis la variable d'environnement TAMARIND_API_KEY ou un fichier .env (utilisez python-dotenv). Ne commettez jamais de clés dans le contrôle de source.

Tarification : Chaque utilisateur reçoit 10 jobs gratuits. Pour une utilisation plus importante, contactez [email protected] pour acheter un abonnement.

export TAMARIND_API_KEY="votre_cle_api"
# Lister les outils disponibles
curl https://app.tamarind.bio/api/tools \
  -H "x-api-key: $TAMARIND_API_KEY"

URL de base : https://app.tamarind.bio/api/

Il n'existe pas de SDK Python officiel — le package PyPI nommé tamarind est un outil Neo4j sans rapport. N'utilisez pas uv pip install tamarind. Écrivez des appels requests simples contre l'API REST (les formes des points d'accès se trouvent dans openapi.yaml), ou utilisez le serveur MCP pour les hôtes d'agents.

Deux façons d'appeler Tamarind

Serveur MCP (meilleur pour les agents IA)

Tamarind héberge un serveur MCP sur https://mcp.tamarind.bio/mcp (authentification par clé API via l'en-tête X-API-Key). Lorsque votre hôte d'agent prend en charge MCP, préférez-le — les outils reflètent l'API REST avec des schémas adaptés aux agents :

• listModalities() / listTags() — le vocabulaire de filtrage en direct (type de molécule / fonction) avec des libellés + des compteurs d'outils ; appelez-les pour apprendre les valeurs valides modality/function au lieu de les coder en dur
• getAvailableTools(modality?, function?, search?, custom?) — découvrir les outils (category/tag sont des alias obsolètes toujours honorés)
• getJobSchema(jobType) — schéma exact des paramètres pour un outil, plus un exampleJob de charge utile de départ (validez-le avant de le soumettre)
• validateJob(jobName, type, settings) — validation à blanc avant soumission
• submitJob(jobName, type, settings) / submitBatch(batchName, type, settings[], jobNames[])
• getJobs(jobName?, batch?, limit?, includeSequences?) — lister/inspecter les jobs et leurs statuts (le volumineux blob d'entrée par job est omis par défaut ; passez includeSequences=true pour le conserver)
• getJobLogs(jobName) — récupérer les journaux de sortie pour le débogage
• listJobFiles(jobName) — lister les fichiers de sortie (renvoie s3Path pour l'enchaînement)
• getResult(jobName, fileName?) — télécharger les résultats
• uploadFile(filename) — URL de téléchargement présignée ; ou uploadFileContent(filename, content, encoding?) pour envoyer le contenu du fichier via MCP lorsque l'hôte ne peut pas atteindre S3 (agents en bac à sable)

Note sur la portée : les outils de requête MCP (getJobs, getResult, listJobFiles, …) sont limités au compte authentifié.

API REST (universelle)

Utilisez HTTP simple avec requests — les formes des points d'accès se trouvent dans openapi.yaml. La boucle principale est ci-dessous ; references/workflows.md contient des recettes complètes.

Workflow principal

Suivez toujours découvrir → schéma → valider → soumettre → interroger → résultats. Ne codez pas en dur les noms d'outils ou les paramètres — le catalogue change fréquemment.

import os, time, requests

BASE = "https://app.tamarind.bio/api"
HEADERS = {"x-api-key": os.environ["TAMARIND_API_KEY"]}

# 1. Découvrir les outils. REST /tools renvoie la liste complète ; filtrez côté client.
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in tools if t["name"] == "alphafold")

# 2. Obtenir le schéma exact pour l'outil choisi.
#    REST : chaque entrée /tools inclut déjà son schéma `settings` en ligne
#          (liste de paramètres) — trouvez l'entrée dont le nom == votre type de job.
#    MCP  : getJobSchema(jobType) renvoie le même détail par outil.

# 3. Soumettre un job. `settings` est spécifique à l'outil — correspond exactement au schéma.
payload = {
    "jobName": "ma-execution-alphafold",          # ^[a-zA-Z0-9_-]+$, <=100 caractères, unique
    "type": "alphafold",
    "settings": {
        "sequence": "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
        "numRecycles": 3,
    },
}
resp = requests.post(f"{BASE}/submit-job", headers=HEADERS, json=payload)
resp.raise_for_status()   # 200 ok ; 400 mauvaise requête ; 403 budget dépassé ; 401 non autorisé

# 4. Interroger jusqu'à la fin.
#    NOTE sur la forme de la réponse : GET /jobs?jobName=<nom> renvoie la LIGNE du job
#    directement (pas d'encapsulation "jobs") ; la requête de liste (sans jobName) renvoie
#    {"jobs": [...]}. N'indexez pas ["jobs"][0] sur la réponse par nom.
while True:
    job = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": "ma-execution-alphafold"}).json()
    if job["JobStatus"] in ("Complete", "Stopped", "Deleted"):
        break
    time.sleep(30)

# 5. Récupérer les résultats. POST /result renvoie une URL présignée *sous forme de chaîne* ;
#    GET cette URL pour télécharger le zip de résultats réel (deux étapes).
url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "ma-execution-alphafold"}).text.strip('"')
open("ma-execution-alphafold.zip", "wb").write(requests.get(url).content)

Pour la version agentique de cette boucle utilisant les outils MCP, et pour des exemples plus riches, voir references/workflows.md.

Découvrir les outils

Le catalogue contient des centaines d'outils. Énumérez toujours à l'exécution — ne vous fiez jamais à une liste codée en dur.

REST GET /tools renvoie la liste complète (elle ne filtre pas côté serveur) ; chaque élément est {name, displayName, github, paper, description, settings} où settings est le schéma de paramètres en ligne de cet outil. Filtrez côté client :

tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()   # une liste
boltz = [t for t in tools if "boltz" in t["name"].lower()]

Remarque : les deux surfaces renvoient une ligne par nom d'outil — REST /tools et MCP getAvailableTools sont tous les deux dédupliqués (le MCP conserve la version la plus récente de l'outil), donc une correspondance de nom renvoie une seule ligne.

MCP getAvailableTools(search=..., modality=..., function=...) filtre côté serveur et ajoute categories/tags par outil (category/tag sont des alias obsolètes de modality/function, toujours honorés). Ne codez pas le vocabulaire en dur — il dérive. Obtenez les valeurs en direct depuis listModalities() / listTags() (chacune renvoie value, label, description et toolCount), ou lisez les tableaux de facettes availableCategories / availableTags renvoyés dans chaque réponse getAvailableTools. Les modalités sont des types de molécules (protéine, anticorps, peptide, petite molécule, acide nucléique, …) ; les fonctions sont ce que fait un outil (prédiction de structure, conception de liant, docking protéine-ligand, …).

Un ensemble représentatif d'outils largement utilisés (vérifiez avec /tools) : alphafold, boltz (Boltz-2), chai (Chai-1), esmfold / esmfold2, rfdiffusion, proteinmpnn, ligandmpnn, boltzgen, bindcraft, diffdock. Voir references/tool_catalog.md pour la carte complète des catégories/tags et comment lire les métadonnées des outils.

Choisir le bon outil

Le catalogue comporte de nombreux outils par tâche ; ne codez pas en dur un favori — filtrez par function (et modality), puis lisez la description de chaque candidat et faites correspondre l'objectif réel de l'utilisateur (entrée que vous avez, sortie dont vous avez besoin, contraintes comme la vitesse ou "pas de MSA"). Les champs description et tags sont le signal public "à quoi ça sert" ; laissez-les, avec validateJob, guider le choix. Orientation rapide par tâche :

• Replier une seule protéine / complexe (function=structure-prediction) : les reproductions de classe AlphaFold3 — boltz/chai/openfold/protenix/intfold — sont la valeur par défaut précise pour tout, y compris les systèmes composés uniquement de protéines ; ils gèrent également les complexes acide nucléique + petite molécule, alors utilisez-les dès qu'un ligand/ARN/ADN fait partie du système (et boltz ajoute l'affinité de liaison). alphafold (AF2) reste un bon choix pour les monomères + multimères (joignez les chaînes avec :). esmfold est à séquence unique (pas de MSA) et rapide — utilisez-le lorsque vous voulez de la vitesse et n'avez pas de MSA ; esmfold2 est plus récent et s'appuie par défaut sur un MSA (son paramètre model offre un mode à séquence unique plus rapide). Des replieurs spécialisés existent pour les anticorps (abodybuilder, immunebuilder), les peptides cycliques (highfold) et les ensembles conformationnels (afcluster, alphaflow) — filtrez et lisez les descriptions.
• Concevoir un liant (function=binder-design) : bindcraft (liants miniprotéines de novo) et boltzgen (liants pour cibles protéiques et petites molécules, incl. nanocorps/anticorps/peptides) sont les outils de novo de référence pour les liants ; rfdiffusion fait également de la conception de liants et est le choix pour l'échafaudage de motifs / la diversification d'un squelette existant. Les générateurs spécifiques aux anticorps se trouvent sous function=antibody-design.
• Concevoir une séquence pour un squelette connu (function=inverse-folding) : proteinmpnn (général), ligandmpnn (conscient des ligands), plus des variantes MPNN thermostables/solubles/anticorps. Le repliement inverse prend une structure et émet des séquences — repliez-les pour vérifier (voir enchaînement).
• Docker une petite molécule (function=protein-ligand-docking) : préférez boltz/chai — ils co-replient le ligand dans le complexe et prédisent la structure liée plutôt que de le docker dans un récepteur fixe ; utilisez autodock-vina lorsque vous avez besoin d'un criblage rapide et à grande échelle contre une poche connue.
• Prédire l'affinité de liaison (function=binding-affinity) ou générer un MSA (recherchez msa) — filtrez et lisez.

Lorsque l'utilisateur nomme un outil spécifique, évaluez celui-ci et vérifiez les alternatives dans son groupe tag — un équivalent plus rapide ou plus approprié existe souvent. En cas de doute, utilisez getJobSchema/validateJob pour confirmer qu'un candidat accepte réellement l'entrée que vous avez avant de vous engager.

Paramètres de job, schémas et validation

Chaque outil a son propre schéma settings. Récupérez-le avant de soumettre :

• REST entrée /tools : chaque paramètre settings est un dictionnaire allégé. Seuls name et required sont toujours présents ; type, default, description, options apparaissent uniquement lorsque cela est pertinent (≈60 % ont type) — utilisez donc param.get("type"), pas param["type"]. Les clés de contrôle avancées (exclude, conditionals) ne sont PAS du tout dans la réponse REST.
• MCP getJobSchema(jobType) : le schéma complet, incluant exclude, conditionals et limites. Utilisez MCP lorsque vous devez raisonner sur ces clés de contrôle. (restrictOrgs est supprimé sur les deux surfaces — un paramètre limité à une organisation que vous ne pouvez pas utiliser est simplement omis ; voir references/api_reference.md.)

Utilisez toujours validateJob (MCP) avant de soumettre — c'est la protection fiable. Il exécute la même validation que /submit-job sans soumettre, et signale le premier champ manquant/invalide. N'essayez pas de dériver manuellement quels champs supprimer des clés du schéma (de toute façon vous ne pouvez pas les voir via REST) — laissez validateJob vous le dire. (La réponse peut inclure un champ source, par exemple "static-fallback" — une note interne sur la source du schéma qui a validé ; valid: true/false est le signal sur lequel vous agissez.)

validateJob renvoie une vue normalized de vos paramètres avec les valeurs par défaut remplies. Soumettez les mêmes settings propres que vous avez validés ; traitez normalized comme informatif (il peut contenir des valeurs par défaut que vous n'avez pas définies, et pour certains outils des champs gérés par la plateforme), donc construisez votre soumission à partir de vos propres paramètres plutôt que du blob normalisé.

Séquences : chaîne d'acides aminés ; séparez les chaînes d'un multimère avec : (par exemple MKT...YEE:MKTV...GG — ne pas échapper). Structures : jusqu'à 30 000 résidus (limite de la plateforme, non négociable). Tape stricte : les outils rejettent un pdbContent passé comme fastaContent. Voir references/api_reference.md pour les types d'entrée complets.

Validation (MCP uniquement)

Appelez validateJob (qui prend jobName, type et settings exactement comme /submit-job) et vérifiez response["valid"] est true avant de soumettre.

Récupération des résultats

REST (deux étapes)

1. POST /result avec {"jobName": "..."} → renvoie une URL présignée sous forme de chaîne JSON.
2. GET cette URL → télécharge le zip de sortie (ou le fichier nommé si fileName a été spécifié dans GET /result?jobName=...&fileName=...). La réponse de l'étape 1 peut être un tableau pour les jobs par lots (chaque élément contient jobName + url).

url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "ma-execution-alphafold"}).text.strip('"')
open("resultats.zip", "wb").write(requests.get(url).content)

MCP

getResult(jobName, fileName?) — renvoie l'URL présignée et le type de contenu. listJobFiles(jobName) renvoie les noms de fichiers et s3Path (peut être passé directement comme fileName de getResult, et peut être utilisé dans uploadFile sans avoir besoin de spécifier un bucket).

Enchaînement de jobs (pipelines)

Les pipelines ne sont pas encore disponibles via REST ou MCP — utilisez les pipelines dans l'interface utilisateur ou l'API GraphQL. Un enchaînement manuel fonctionne : soumettez le job #1, récupérez les résultats, extrayez les fichiers nécessaires, soumettez le job #2 en les utilisant.

L'enchaînement est principalement structure-ou-séquence → séquence-ou-structure :

• Repliement inverse (ex. ProteinMPNN) → la sortie est un fichier .fa ; soumettez-le directement comme fastaContent dans un job de repliement ultérieur (ex. alphafold). ProteinMPNN inclut les séquences dans son JSON de sortie à ["sequences"] — c'est plus rapide que l'analyse du fichier FASTA.
• Conception de liants/de novo (ex. RFdiffusion, BoltzGen) → la sortie inclut des fichiers .pdb ; passez pdbContent à un job de repliement inverse pour charger les conceptions. rfdiffusion met en cache l'état de diffusion intermédiaire — utilisez {"contig": "..."} pour diversifier.
• BindCraft produit déjà des paires séquence-structure — le plus souvent pas besoin de le replier.

Erreurs courantes

• 403 Forbidden (budget dépassé). L'erreur se produit au moment de la soumission. Aucun job gratuit restant. Dépannez en suggérant un abonnement payant.
• 401 Unauthorized (mauvaise clé/variable d'environnement manquante). Vérifiez que TAMARIND_API_KEY est définie. Ne divulguez jamais la clé.
• 400 Bad Request (paramètres invalides/malformés). Utilisez validateJob pour obtenir des retours précis.
• La réponse de GET /jobs sans jobName est encapsulée dans {"jobs": [...]} mais une requête AVEC jobName renvoie l'objet job directement. Ne codez pas le déballage de ["jobs"][0] sur une requête par nom.
• La réponse de POST /result est une URL sous forme de chaîne JSON (avec des guillemets). Utilisez .strip('"') pour l'analyser.
• tamarind sur PyPI n'est pas lié à Tamarind Bio. N'essayez pas de l'installer. Utilisez requests brut.
• Les formes des paramètres du schéma diffèrent entre REST et MCP. REST peut omettre type ; MCP peut omettre default. Utilisez validateJob pour la validation au moment de l'exécution.

Références

Ce répertoire (skills/tamarind/references/) contient des fichiers de référence qui guident le comportement d'un agent IA :

• workflows.md — Recettes pas à pas (découverte, alphafold, chai, boltz-gen, proteinmpnn, pipelines, batch, gestion des fichiers, gestion des erreurs). Commencez ici.
• api_reference.md — Dictionnaire complet des schémas de paramètres, notes de comportement pour chaque outil majeur, structure des réponses, types d'entrée (séquences/PDB/fasta/nucléiques/ligands), et notes sur la pagination.
• tool_catalog.md — Définitions des catégories, fonctions et tags, avec explication de la lecture des métadonnées des outils.
• mcp_tools.md — Miroir de l'API MCP avec détails complets de schéma pour tous les outils et types.

Chargez ces fichiers selon les besoins pour guider les appels API et la prise de décision. Récupérez les sources canoniques (OpenAPI spec, LLM index, outil de découverte en direct) à chaque session plutôt que de vous fier à des copies statiques.