tamarind

Tamarind Bio

Tamarind Bio é uma plataforma em nuvem que executa ferramentas de biologia computacional — predição de estrutura, design de proteínas e anticorpos, docking, afinidade de ligação, geração de MSA e dinâmica molecular — em GPUs gerenciadas. Os usuários submetem sequências ou estruturas e recebem de volta estruturas previstas, designs e pontuações biofísicas, sem precisar provisionar seu próprio hardware. Ela expõe centenas de ferramentas (AlphaFold, Boltz-2, Chai-1, RFdiffusion, ProteinMPNN, BoltzGen, ESMFold2, DiffDock, Autodock Vina e muitas outras) através de uma API de trabalhos uniforme.

Documentos oficiais: app.tamarind.bio/api-docs · interface da plataforma em app.tamarind.bio

Fontes canônicas — busque estas, não confie em uma cópia desatualizada

O Tamarind publica fontes legíveis por máquina e ao vivo. Prefira buscá-las em tempo de execução em vez de confiar em qualquer lista fixa — nomes de ferramentas, esquemas e endpoints mudam com frequência:

• https://app.tamarind.bio/llms.txt — Índice LLM: links para a especificação, documentação da API e guia MCP.
• https://app.tamarind.bio/openapi.yaml — Especificação OpenAPI 3.0 para os 8 endpoints principais de trabalho (submit-job/-batch, jobs, result, upload, files, delete-job/-file; autenticação ApiKeyAuth). Busque-a para obter essas formas exatas. Endpoints de descoberta/gerenciamento (/tools, /usage-statistics, pipelines, …) não estão nela — use as ferramentas de descoberta MCP/REST para esses.
• https://docs.tamarind.bio/llms.txt — Índice de documentação; toda página tem um formulário .md (ex.: docs.tamarind.bio/tamarind/batch.md, /tamarind/api.md, /tamarind/pipelines.md).
• Descoberta ao vivo de ferramentas — GET /tools (REST) ou MCP getAvailableTools + getJobSchema(jobType) são a fonte da verdade sobre quais ferramentas existem e seus parâmetros.

Esta skill ensina a superfície + os comportamentos não óbvios que essas fontes não detalham (veja os arquivos de referência). Em caso de dúvida sobre uma forma, busque openapi.yaml.

Quando usar esta skill

Use o Tamarind quando o usuário quiser:

• Prever estrutura de uma proteína, complexo ou sistema proteína-ligante (AlphaFold, Boltz-2, Chai-1, ESMFold2, co-folding Chai/Boltz)
• Projetar proteínas ou ligantes (RFdiffusion, BoltzGen, BindCraft, ProteinMPNN/LigandMPNN inverse folding)
• Projetar ou caracterizar anticorpos/nanocorpos (geração de sequência, humanização, desenvolvabilidade, imunogenicidade)
• Dockar moléculas pequenas a uma proteína (DiffDock, Autodock Vina) ou prever afinidade de ligação
• Gerar MSAs para folding downstream
• Executar dinâmica molecular ou outros fluxos de trabalho biofísicos em GPUs gerenciadas
• Triar em lote muitas sequências ou designs através da mesma ferramenta
• Encadear ferramentas em pipelines (ex.: design → fold → pontuação) usando a saída de um trabalho como entrada do próximo

Esta skill é a escolha certa quando o trabalho deve ser executado na nuvem gerenciada do Tamarind, em vez de uma instalação local. Para quimioinformática puramente local ou E/S de sequência avulsa, use uma biblioteca local (RDKit, BioPython).

Acesso e autenticação

1. Faça login em app.tamarind.bio e crie uma chave de API nas configurações da conta/API.
2. Autentique toda requisição REST com o cabeçalho x-api-key.
3. Nunca codifique a chave. Leia-a da variável de ambiente TAMARIND_API_KEY ou de um arquivo .env (use python-dotenv). Nunca commite chaves no controle de versão.

Preços: Todo usuário recebe 10 trabalhos grátis. Para uso maior, entre em contato com [email protected] para adquirir uma assinatura.

export TAMARIND_API_KEY="sua_chave_api"
# Listar ferramentas disponíveis
curl https://app.tamarind.bio/api/tools \
  -H "x-api-key: $TAMARIND_API_KEY"

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

Não existe um SDK Python oficial — o pacote PyPI chamado tamarind é uma ferramenta Neo4j não relacionada. Não faça uv pip install tamarind. Escreva chamadas requests simples contra a API REST (as formas dos endpoints estão em openapi.yaml), ou use o servidor MCP para hosts de agentes.

Duas maneiras de chamar o Tamarind

Servidor MCP (melhor para agentes de IA)

O Tamarind hospeda um servidor MCP em https://mcp.tamarind.bio/mcp (autenticação por chave de API via cabeçalho X-API-Key). Quando seu host de agente suportar MCP, prefira-o — as ferramentas espelham a API REST com esquemas amigáveis para agentes:

• listModalities() / listTags() — o vocabulário de filtro ao vivo (tipo de molécula / função) com rótulos + contagens de ferramentas; chame-os para aprender valores válidos de modality/function em vez de codificá-los
• getAvailableTools(modality?, function?, search?, custom?) — descubra ferramentas (category/tag são aliases obsoletos ainda respeitados)
• getJobSchema(jobType) — esquema exato de parâmetros para uma ferramenta, além de um exampleJob com payload inicial (valide-o antes de submeter)
• validateJob(jobName, type, settings) — validação de teste antes de submeter
• submitJob(jobName, type, settings) / submitBatch(batchName, type, settings[], jobNames[])
• getJobs(jobName?, batch?, limit?, includeSequences?) — liste/inspecione trabalhos e status (o blob volumoso de entrada por trabalho é omitido por padrão; passe includeSequences=true para mantê-lo)
• getJobLogs(jobName) — busque logs de saída para depuração
• listJobFiles(jobName) — liste arquivos de saída (retorna s3Path para encadeamento)
• getResult(jobName, fileName?) — baixe resultados
• uploadFile(filename) — URL de upload pré-assinada; ou uploadFileContent(filename, content, encoding?) para enviar conteúdo de arquivo através do MCP quando o host não conseguir alcançar o S3 (agentes em sandbox)

Nota de escopo: As ferramentas de consulta MCP (getJobs, getResult, listJobFiles, …) têm escopo definido para a conta autenticada.

API REST (universal)

Use HTTP simples com requests — as formas dos endpoints estão em openapi.yaml. O loop principal está abaixo; references/workflows.md tem receitas completas.

Fluxo de trabalho principal

Sempre siga: descobrir → esquema → validar → submeter → poll → resultados. Não codifique nomes de ferramentas ou configurações — o catálogo muda com frequência.

import os, time, requests

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

# 1. Descobrir ferramentas. REST /tools retorna a lista completa; filtre no lado do cliente.
ferramentas = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in ferramentas if t["name"] == "alphafold")

# 2. Obter o esquema exato para a ferramenta escolhida.
#    REST: cada entrada de /tools já inclui seu esquema de `settings` inline
#          (lista de parâmetros) — encontre a entrada cujo nome == seu tipo de trabalho.
#    MCP:  getJobSchema(jobType) retorna o mesmo detalhe por ferramenta.

# 3. Submeter um trabalho. `settings` é específico da ferramenta — corresponda ao esquema exatamente.
payload = {
    "jobName": "minha-execucao-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 requisição ruim; 403 orçamento excedido; 401 não autorizado

# 4. Poll até a conclusão.
#    NOTA sobre a forma da resposta: GET /jobs?jobName=<nome> retorna a LINHA do trabalho
#    diretamente (sem wrapper "jobs"); a consulta de lista (sem jobName) retorna
#    {"jobs": [...]}. Não indexe ["jobs"][0] na resposta por nome.
while True:
    job = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": "minha-execucao-alphafold"}).json()
    if job["JobStatus"] in ("Complete", "Stopped", "Deleted"):
        break
    time.sleep(30)

# 5. Recuperar resultados. POST /result retorna uma *string* de URL pré-assinada;
#    Faça GET nessa URL para baixar o zip real dos resultados (duas etapas).
url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "minha-execucao-alphafold"}).text.strip('"')
open("minha-execucao-alphafold.zip", "wb").write(requests.get(url).content)

Para a versão agentic deste loop usando ferramentas MCP, e para exemplos mais ricos, veja references/workflows.md.

Descobrindo ferramentas

O catálogo tem centenas de ferramentas. Sempre enumere em tempo de execução — nunca confie em uma lista fixa.

REST GET /tools retorna a lista completa (ela não filtra no servidor); cada item é {name, displayName, github, paper, description, settings} onde settings é o esquema inline de parâmetros daquela ferramenta. Filtre no lado do cliente:

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

Nota: ambas as superfícies retornam uma linha por nome de ferramenta — REST /tools e MCP getAvailableTools são ambos desduplicados (o MCP mantém a versão mais nova da ferramenta), então uma correspondência de nome retorna uma única linha.

MCP getAvailableTools(search=..., modality=..., function=...) filtra no servidor e adiciona categories/tags por ferramenta (category/tag são aliases obsoletos de modality/function, ainda respeitados). Não codifique o vocabulário — ele muda. Obtenha os valores ao vivo de listModalities() / listTags() (cada um retorna value, label, description e toolCount), ou leia os arrays de facetas availableCategories / availableTags retornados em toda resposta de getAvailableTools. Modalidades são tipos de molécula (proteína, anticorpo, peptídeo, molécula pequena, ácido nucleico, …); funções são o que uma ferramenta faz (predição de estrutura, design de ligante, docking proteína-ligante, …).

Um conjunto representativo de ferramentas amplamente usadas (verifique com /tools): alphafold, boltz (Boltz-2), chai (Chai-1), esmfold / esmfold2, rfdiffusion, proteinmpnn, ligandmpnn, boltzgen, bindcraft, diffdock. Veja references/tool_catalog.md para o mapa completo de categoria/tag e como ler metadados de ferramentas.

Escolhendo a ferramenta certa

O catálogo tem muitas ferramentas por tarefa; não codifique uma favorita — filtre por function (e modality), depois leia a description de cada candidato e corresponda ao objetivo real do usuário (entrada que você tem, saída que precisa, restrições como velocidade ou "sem MSA"). Os campos description e tags são o sinal público "para que serve"; deixe-os, mais validateJob, guiar a escolha. Orientação rápida por tarefa:

• Dobrar uma única proteína / complexo (function=structure-prediction): as reproduções da classe AlphaFold3 — boltz/chai/openfold/protenix/intfold — são o padrão preciso para tudo, incluindo sistemas só de proteína; elas também lidam com complexos de ácido nucleico + molécula pequena, então recorra a elas sempre que um ligante/RNA/DNA fizer parte do sistema (e boltz adiciona afinidade de ligação). alphafold (AF2) continua sendo uma escolha sólida para monômeros + multímeros (junte cadeias com :). esmfold é de sequência única (sem MSA) e rápida — recorra a ela quando quiser velocidade e não tiver MSA; esmfold2 é mais nova e condiciona em um MSA por padrão (sua configuração model oferece um modo mais rápido de sequência única). Existem dobradores especializados para anticorpos (abodybuilder, immunebuilder), peptídeos cíclicos (highfold) e ensembles conformacionais (afcluster, alphaflow) — filtre e leia as descrições.
• Projetar um ligante (function=binder-design): bindcraft (ligantes de novo de miniproteína) e boltzgen (ligantes para alvos de proteína e molécula pequena, incl. nanocorpos/anticorpos/peptídeos) são as ferramentas de ligante de novo de referência; rfdiffusion também faz design de ligante e é a escolha para scaffolding de motivo / diversificar um backbone existente. Geradores específicos de anticorpos estão sob function=antibody-design.
• Projetar sequência para um backbone conhecido (function=inverse-folding): proteinmpnn (geral), ligandmpnn (ciente de ligante), além de variantes termoestáveis/solúveis/anticorpo MPNN. Inverse folding pega uma estrutura e emite sequências — dobre-as de volta para verificar (veja encadeamento).
• Dockar uma molécula pequena (function=protein-ligand-docking): prefira boltz/chai — eles co-dobram o ligante no complexo e predizem a estrutura ligada em vez de dockar em um receptor fixo; recorra a autodock-vina quando precisar de triagem rápida e em larga escala contra um bolsão conhecido.
• Prever afinidade de ligação (function=binding-affinity) ou gerar um MSA (pesquise msa) — filtre e leia.

Quando o usuário nomear uma ferramenta específica, avalie aquela e verifique as alternativas em seu grupo de tag — geralmente existe um irmão mais rápido ou mais apropriado. Quando estiver em dúvida, use getJobSchema/validateJob para confirmar se um candidato realmente aceita a entrada que você tem antes de se comprometer.

Configurações de trabalho, esquemas e validação

Cada ferramenta tem seu próprio esquema de settings. Busque-o antes de submeter:

• REST entrada de /tools: cada parâmetro de settings é um dicionário aparado. Apenas name e required estão sempre presentes; type, default, description, options aparecem apenas quando relevantes (≈60% têm type) — então use param.get("type"), não param["type"]. As chaves de bloqueio avançadas (exclude, conditionals) NÃO estão na resposta REST.
• MCP getJobSchema(jobType): o esquema completo, incluindo exclude, conditionals e limites. Use MCP quando precisar raciocinar sobre essas chaves de bloqueio. (restrictOrgs é removido em ambas as superfícies — um parâmetro bloqueado por organização que você não pode usar é simplesmente omitido; veja references/api_reference.md.)

Sempre validateJob (MCP) antes de submeter — é a proteção confiável. Ela executa a mesma validação que /submit-job sem submeter, e mostra o primeiro campo ausente/inválido. Não tente derivar manualmente quais campos remover das chaves do esquema (pelo REST você não pode vê-los de qualquer forma) — deixe validateJob lhe dizer. (A resposta pode incluir um campo source, ex. "static-fallback" — uma nota interna sobre qual fonte de esquema validou; valid: true/false é o sinal no qual você age.)

validateJob ecoa uma visão normalized de suas configurações com valores padrão preenchidos. Submeta as mesmas configurações settings limpas que você validou; trate normalized como informativo (pode carregar valores padrão que você não definiu, e para algumas ferramentas campos gerenciados pela plataforma), então construa sua submissão a partir de suas próprias configurações, em vez do blob normalizado.

Sequências: string de aminoácidos; separe cadeias de um multímero com ...

[... truncado para tradução]