tamarind

Tamarind Bio

Tamarind Bio es una plataforma en la nube que ejecuta herramientas de biología computacional (predicción de estructuras, diseño de proteínas y anticuerpos, acoplamiento, afinidad de unión, generación de MSAs y dinámica molecular) en GPUs gestionadas. Los usuarios envían secuencias o estructuras y reciben estructuras predichas, diseños y puntuaciones biofísicas, sin necesidad de aprovisionar su propio hardware. Expone cientos de herramientas (AlphaFold, Boltz-2, Chai-1, RFdiffusion, ProteinMPNN, BoltzGen, ESMFold2, DiffDock, Autodock Vina y muchas más) a través de una API de trabajos unificada.

Documentación oficial: app.tamarind.bio/api-docs · Interfaz de plataforma en app.tamarind.bio

Fuentes canónicas: obtén estas, no te bases en una copia desactualizada

Tamarind publica fuentes legibles por máquina en vivo. Es preferible obtenerlas en tiempo de ejecución en lugar de confiar en cualquier lista codificada: los nombres de las herramientas, los esquemas y los puntos finales cambian con frecuencia:

• https://app.tamarind.bio/llms.txt — Índice para LLM: enlaces a la especificación, documentación de la API y guía de MCP.
• https://app.tamarind.bio/openapi.yaml — Especificación OpenAPI 3.0 para los 8 endpoints principales de trabajos (enviar-trabajo/-lote, trabajos, resultado, subir, archivos, eliminar-trabajo/-archivo; autenticación ApiKeyAuth). Obtén esto para esas formas exactas. Los endpoints de descubrimiento/gestión (/tools, /usage-statistics, pipelines, ...) no están incluidos; usa las herramientas de descubrimiento MCP/REST para esos.
• https://docs.tamarind.bio/llms.txt — Índice de documentación; cada página tiene un formulario .md (ej. docs.tamarind.bio/tamarind/batch.md, /tamarind/api.md, /tamarind/pipelines.md).
• Descubrimiento de herramientas en vivo — GET /tools (REST) o MCP getAvailableTools + getJobSchema(jobType) son la fuente de verdad sobre qué herramientas existen y sus parámetros.

Esta skill enseña la superficie más los comportamientos no obvios que esas fuentes no detallan (consulta los archivos de referencia). Ante la duda sobre una forma, obtén openapi.yaml.

Cuándo usar esta skill

Usa Tamarind cuando el usuario quiera:

• Predecir la estructura de una proteína, complejo o sistema proteína-ligando (AlphaFold, Boltz-2, Chai-1, ESMFold2, co-plegamiento Chai/Boltz)
• Diseñar proteínas o ligandos (RFdiffusion, BoltzGen, BindCraft, plegamiento inverso ProteinMPNN/LigandMPNN)
• Diseñar o caracterizar anticuerpos/nanocuerpos (generación de secuencias, humanización, desarrollabilidad, inmunogenicidad)
• Acoplar moléculas pequeñas a una proteína (DiffDock, Autodock Vina) o predecir la afinidad de unión
• Generar MSAs para plegamiento posterior
• Ejecutar dinámica molecular u otros flujos de trabajo biofísicos en GPUs gestionadas
• Evaluar por lotes muchas secuencias o diseños a través de la misma herramienta
• Encadenar herramientas en pipelines (ej. diseñar → plegar → puntuar) usando la salida de un trabajo como entrada del siguiente

Esta skill es la opción correcta cuando el trabajo debe ejecutarse en la nube gestionada de Tamarind en lugar de en una instalación local. Para quimioinformática puramente local o E/S de secuencias de una sola vez, usa una biblioteca local (RDKit, BioPython).

Acceso y autenticación

1. Inicia sesión en app.tamarind.bio y crea una clave API desde la configuración de cuenta/API.
2. Autentica cada solicitud REST con el encabezado x-api-key.
3. Nunca codifiques la clave. Lée la variable de entorno TAMARIND_API_KEY o un archivo .env (usa python-dotenv). Nunca envíes claves al control de código fuente.

Precios: Cada usuario tiene 10 trabajos gratuitos. Para un uso mayor, contacta a [email protected] para comprar una suscripción.

export TAMARIND_API_KEY="tu_clave_api"
# Listar herramientas disponibles
curl https://app.tamarind.bio/api/tools \
  -H "x-api-key: $TAMARIND_API_KEY"

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

No hay un SDK oficial de Python — el paquete PyPI llamado tamarind es una herramienta de Neo4j no relacionada. No ejecutes uv pip install tamarind. Escribe llamadas requests simples contra la API REST (las formas de los endpoints están en openapi.yaml), o usa el servidor MCP para hosts de agentes.

Dos formas de llamar a Tamarind

Servidor MCP (mejor para agentes de IA)

Tamarind aloja un servidor MCP en https://mcp.tamarind.bio/mcp (autenticación con clave API a través del encabezado X-API-Key). Cuando tu host de agente sea compatible con MCP, prefierlo: las herramientas reflejan la API REST con esquemas amigables para agentes:

• listModalities() / listTags() — el vocabulario de filtro en vivo (tipo de molécula / función) con etiquetas + recuentos de herramientas; llámalos para aprender los valores válidos de modality/function en lugar de codificarlos
• getAvailableTools(modality?, function?, search?, custom?) — descubre herramientas (category/tag son alias obsoletos pero aún aceptados)
• getJobSchema(jobType) — esquema de parámetros exacto para una herramienta, más un exampleJob de carga útil inicial (valídelo antes de enviar)
• validateJob(jobName, type, settings) — validación de prueba antes de enviar
• submitJob(jobName, type, settings) / submitBatch(batchName, type, settings[], jobNames[])
• getJobs(jobName?, batch?, limit?, includeSequences?) — listar/inspeccionar trabajos y estados (el blob de entrada voluminoso por trabajo se omite por defecto; pasa includeSequences=true para mantenerlo)
• getJobLogs(jobName) — obtener registros de salida para depuración
• listJobFiles(jobName) — listar archivos de salida (devuelve s3Path para encadenamiento)
• getResult(jobName, fileName?) — descargar resultados
• uploadFile(filename) — URL de subida prefirmada; o uploadFileContent(filename, content, encoding?) para enviar contenido de archivo a través de MCP cuando el host no pueda alcanzar S3 (agentes en entorno aislado)

Nota de ámbito: Las herramientas de consulta de MCP (getJobs, getResult, listJobFiles, …) están limitadas a la cuenta autenticada.

API REST (universal)

Usa HTTP simple con requests — las formas de los endpoints están en openapi.yaml. El bucle principal está a continuación; references/workflows.md tiene recetas completas.

Flujo de trabajo principal

Sigue siempre el proceso: descubrir → esquema → validar → enviar → consultar → resultados. No codifiques nombres de herramientas o configuraciones: el catálogo cambia con frecuencia.

import os, time, requests

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

# 1. Descubrir herramientas. REST /tools devuelve la lista completa; filtra del lado del cliente.
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in tools if t["name"] == "alphafold")

# 2. Obtener el esquema exacto para la herramienta elegida.
#    REST: cada entrada de /tools ya incluye su esquema `settings` en línea
#          (lista de parámetros) — encuentra la entrada cuyo nombre sea igual a tu tipo de trabajo.
#    MCP:  getJobSchema(jobType) devuelve el mismo detalle por herramienta.

# 3. Enviar un trabajo. `settings` es específico de la herramienta — coincide exactamente con el esquema.
payload = {
    "jobName": "mi-ejecucion-alphafold",          # ^[a-zA-Z0-9_-]+$, <=100 caracteres, único
    "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 solicitud incorrecta; 403 presupuesto excedido; 401 no autorizado

# 4. Consultar hasta que se complete.
#    NOTA la forma de la respuesta: GET /jobs?jobName=<nombre> devuelve la FILA del trabajo
#    directamente (sin envoltorio "jobs"); la consulta de lista (sin jobName) devuelve
#    {"jobs": [...]}. No indices ["jobs"][0] en la respuesta por nombre.
while True:
    job = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": "mi-ejecucion-alphafold"}).json()
    if job["JobStatus"] in ("Complete", "Stopped", "Deleted"):
        break
    time.sleep(30)

# 5. Recuperar resultados. POST /result devuelve una *cadena* de URL prefirmada;
#    Haz GET a esa URL para descargar el zip de resultados real (dos pasos).
url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "mi-ejecucion-alphafold"}).text.strip('"')
open("mi-ejecucion-alphafold.zip", "wb").write(requests.get(url).content)

Para la versión agentiva de este bucle usando herramientas MCP, y para ejemplos más ricos, consulta references/workflows.md.

Descubrimiento de herramientas

El catálogo tiene cientos de herramientas. Enuméralas siempre en tiempo de ejecución; nunca te bases en una lista codificada.

REST GET /tools devuelve la lista completa (no filtra del lado del servidor); cada elemento es {name, displayName, github, paper, description, settings} donde settings es el esquema de parámetros en línea de esa herramienta. Filtra del lado del cliente:

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

Nota: ambas superficies devuelven una fila por nombre de herramienta: tanto REST /tools como MCP getAvailableTools están desduplicados (el MCP mantiene la versión más nueva de la herramienta), por lo que una coincidencia de nombre devuelve una sola fila.

MCP getAvailableTools(search=..., modality=..., function=...) filtra del lado del servidor y agrega categories/tags por herramienta (category/tag son alias obsoletos de modality/function, aún aceptados). No codifiques el vocabulario: se modifica. Obtén los valores en vivo de listModalities() / listTags() (cada uno devuelve value, label, description y toolCount), o lee las matrices de faceta availableCategories / availableTags devueltas en cada respuesta de getAvailableTools. Las modalidades son tipos de moléculas (proteína, anticuerpo, péptido, molécula pequeña, ácido nucleico, …); las funciones son lo que hace una herramienta (predicción de estructura, diseño de ligandos, acoplamiento proteína-ligando, …).

Un conjunto representativo de herramientas ampliamente utilizadas (verifica con /tools): alphafold, boltz (Boltz-2), chai (Chai-1), esmfold / esmfold2, rfdiffusion, proteinmpnn, ligandmpnn, boltzgen, bindcraft, diffdock. Consulta references/tool_catalog.md para el mapa completo de categorías/etiquetas y cómo leer los metadatos de las herramientas.

Elegir la herramienta adecuada

El catálogo tiene muchas herramientas por tarea; no codifiques una favorita: filtra por function (y modality), luego lee la description de cada candidato y hazla coincidir con el objetivo real del usuario (entrada que tienes, salida que necesitas, restricciones como velocidad o "sin MSA"). Los campos description y tags son la señal pública de "para qué sirve"; déjalos, junto con validateJob, guiar la elección. Orientación rápida por tarea:

• Plegar una proteína/complejo individual (function=structure-prediction): las reproducciones de clase AlphaFold3 — boltz/chai/openfold/protenix/intfold — son el valor predeterminado preciso para todo, incluidos sistemas solo de proteínas; también manejan complejos de ácidos nucleicos + moléculas pequeñas, así que recurre a ellos cada vez que un ligando/ARN/ADN sea parte del sistema (y boltz agrega afinidad de unión). alphafold (AF2) sigue siendo una opción sólida para monómeros + multímeros (une cadenas con :). esmfold es de secuencia única (sin MSA) y rápido: recurre a él cuando quieras velocidad y no tengas MSA; esmfold2 es más nuevo y por defecto condiciona en un MSA (su configuración model ofrece un modo de secuencia única más rápido). Existen plegadores especializados para anticuerpos (abodybuilder, immunebuilder), péptidos cíclicos (highfold) y conjuntos conformacionales (afcluster, alphaflow) — filtra y lee las descripciones.
• Diseñar un ligando (function=binder-design): bindcraft (ligandos de miniproteína de novo) y boltzgen (ligandos para dianas de proteína y molécula pequeña, incl. nanocuerpos/anticuerpos/péptidos) son las herramientas de novo para ligandos; rfdiffusion también realiza diseño de ligandos y es la opción para andamiaje de motivos / diversificar un esqueleto existente. Los generadores específicos de anticuerpos se encuentran bajo function=antibody-design.
• Diseñar secuencia para un esqueleto conocido (function=inverse-folding): proteinmpnn (general), ligandmpnn (consciente de ligandos), más variantes termoestables/solubles/anticuerpo de MPNN. El plegamiento inverso toma una estructura y emite secuencias — pliega nuevamente para verificar (consulta encadenamiento).
• Acoplar una molécula pequeña (function=protein-ligand-docking): prefiere boltz/chai — ellos co-plegan el ligando en el complejo y predicen la estructura unida en lugar de acoplarlo en un receptor fijo; recurre a autodock-vina cuando necesites un cribado rápido y a gran escala contra un bolsillo conocido.
• Predecir la afinidad de unión (function=binding-affinity) o generar un MSA (busca msa) — filtra y lee.

Cuando el usuario nombre una herramienta específica, evalúa esa y verifica las alternativas en su grupo de tags: a menudo existe un hermano más rápido o más apropiado. Cuando no estés seguro, usa getJobSchema/validateJob para confirmar que un candidato realmente acepta la entrada que tienes antes de comprometerte.

Configuración de trabajos, esquemas y validación

Cada herramienta tiene su propio esquema de settings. Obténlo antes de enviar:

• REST entrada /tools: cada parámetro de settings es un diccionario recortado. Solo name y required están siempre presentes; type, default, description, options aparecen solo cuando es relevante (≈60 % tienen type) — así que usa param.get("type"), no param["type"]. Las claves de control avanzadas (exclude, conditionals) NO están en la respuesta REST en absoluto.
• MCP getJobSchema(jobType): el esquema completo, incluidos exclude, conditionals y límites. Usa MCP cuando necesites razonar sobre esas claves de control. (restrictOrgs se elimina en ambas superficies: un parámetro restringido por organización que no puedes usar simplemente se omite; consulta references/api_reference.md.)

Siempre usa validateJob (MCP) antes de enviar — es la protección confiable. Ejecuta la misma validación que /submit-job sin enviar, y señala el primer campo faltante/no válido. No intentes deducir manualmente qué campos eliminar de las claves del esquema (en REST de todos modos no puedes verlos) — deja que validateJob te lo diga. (La respuesta puede incluir un campo source, ej. "static-fallback" — una nota interna sobre qué fuente de esquema validó; valid: true/false es la señal en la que actúas.)

validateJob devuelve una vista normalized de tu configuración con los valores predeterminados completados. Envía la misma configuración settings limpia que validaste; trata normalized como informativo (puede incluir valores predeterminados que no configuraste y, para algunas herramientas, campos gestionados por la plataforma), así que construye tu envío a partir de tu propia configuración en lugar del blob normalizado.

Secuencias: cadena de aminoácidos; separa las cadenas de un multímero con : (dos puntos). Consulta el esquema de la herramienta para conocer la sintaxis exacta del formato de entrada.

Resultados y archivos

Cuando un trabajo se completa, los resultados están disponibles para descargar. La estructura de archivos depende de la herramienta; consulta la documentación de la herramienta o la entrada del catálogo.

• Listar archivos: GET /files (REST) o listJobFiles(jobName) (MCP) devuelve una lista de nombres de archivos disponibles. Cada entrada incluye s3Path para encadenar como entrada a otro trabajo.
• Descargar un archivo específico: POST /result con {"jobName": "...", "fileName": "..."} devuelve una URL prefirmada para ese archivo.
• Descargar todo (zip): POST /result con {"jobName": "..."} (sin fileName) devuelve una URL prefirmada para un zip de todos los archivos de salida.
• Subir un archivo para usarlo como entrada: POST /upload (REST) devuelve una URL de subida prefirmada; luego sube el archivo allí. O usa uploadFile/uploadFileContent de MCP. El s3Path resultante se puede usar en la configuración settings de trabajos posteriores.

Precios y límites

Cada cuenta comienza con 10 trabajos gratuitos (sujetos a recursos de GPU). Cuando se agoten, los trabajos fallarán con un código de estado 403. Para continuar usando la plataforma, contacta a [email protected] para comprar una suscripción. No hay límite explícito en la duración del trabajo, pero los trabajos de muy larga duración pueden fallar en el límite de tiempo de espera de la plataforma (actualmente varias horas para herramientas individuales).

Prácticas recomendadas

• Sigue siempre el flujo: descubre -> esquema -> valida -> envía -> consulta -> resultados. No omitas pasos.
• No codifiques: los nombres de herramientas, parámetros o categorías cambian. Siempre obtén los datos en vivo.
• Usa MCP cuando sea posible: las herramientas MCP proporcionan esquemas más ricos y capacidades de validación.
• Mantén las claves API seguras: usa variables de entorno, nunca las codifiques.
• Nombres de trabajos únicos: cada trabajo debe tener un jobName único dentro de tu cuenta. Usa marcas de tiempo o UUIDs para evitar colisiones.
• Consulta con cortesía: un intervalo de 30 segundos entre consultas es suficiente; respeta el límite de velocidad de la plataforma.
• Comprueba primero el trabajo existente: antes de enviar uno nuevo, lista los trabajos existentes con getJobs para ver si un trabajo con el mismo nombre ya se ejecutó y se pueden reutilizar los resultados.

Resolución de problemas

• 401 No autorizado: verifica que tu clave API sea correcta y esté configurada en la variable de entorno TAMARIND_API_KEY, y que estés pasando el encabezado x-api-key.
• 403 Presupuesto excedido: has agotado tus trabajos gratuitos. Contacta a ventas para obtener una suscripción.
• 400 Solicitud incorrecta: la configuración no coincide con el esquema de la herramienta. Usa validateJob para encontrar el error exacto.
• Trabajo atascado en "En cola": la plataforma puede estar ocupada; espera pacientemente. Los trabajos generalmente se completan en minutos.
• Error al descargar resultados si el trabajo falló: los trabajos fallidos pueden no tener archivos de salida. Consulta el estado y los registros del trabajo (getJobLogs) para determinar la causa.

Para problemas más complejos, consulta references/workflows.md y la documentación oficial. Si todo lo demás falla, comunícate con el soporte de Tamarind.