tamarind

Tamarind Bio

Tamarind Bio 是一个云平台，可在托管 GPU 上运行计算生物学工具，包括结构预测、蛋白质和抗体设计、分子对接、结合亲和力预测、MSA 生成和分子动力学。用户提交序列或结构，即可获取预测结构、设计结果和生物物理评分，无需自行配置硬件。平台通过统一的作业 API 提供数百种工具（AlphaFold、Boltz-2、Chai-1、RFdiffusion、ProteinMPNN、BoltzGen、ESMFold2、DiffDock、Autodock Vina 等）。

官方文档： app.tamarind.bio/api-docs · 平台界面：app.tamarind.bio

规范来源——请获取这些内容，不要依赖过时副本

Tamarind 提供实时、机器可读的来源。请优先在运行时获取，而非依赖任何硬编码列表——工具名称、架构和端点经常变化：

• https://app.tamarind.bio/llms.txt — LLM 索引：包含规范、API 文档和 MCP 指南的链接。
• https://app.tamarind.bio/openapi.yaml — 8 个核心作业端点（submit-job/-batch、jobs、result、upload、files、delete-job/-file；认证方式为 ApiKeyAuth）的 OpenAPI 3.0 规范。请获取此规范以了解这些端点的确切结构。它不包含发现/管理端点（/tools、/usage-statistics、pipelines 等）——请使用 MCP/REST 发现工具。
• https://docs.tamarind.bio/llms.txt — 文档索引；每个页面都有 .md 版本（例如 docs.tamarind.bio/tamarind/batch.md、/tamarind/api.md、/tamarind/pipelines.md）。
• 实时工具发现 — GET /tools（REST）或 MCP getAvailableTools + getJobSchema(jobType) 是查询现有工具及其参数的权威来源。

本技能介绍了可用功能，以及这些来源未说明的特殊行为（请参阅参考文件）。如不确定结构，请获取 openapi.yaml。

何时使用此技能

用户希望执行以下操作时，请使用 Tamarind：

• 预测结构：蛋白质、复合物或蛋白质-配体体系（AlphaFold、Boltz-2、Chai-1、ESMFold2、Chai/Boltz 共折叠）
• 设计蛋白质或结合剂（RFdiffusion、BoltzGen、BindCraft、ProteinMPNN/LigandMPNN 逆折叠）
• 设计或表征抗体/纳米抗体（序列生成、人源化、可开发性、免疫原性）
• 将小分子对接到蛋白质（DiffDock、Autodock Vina），或预测结合亲和力
• 生成 MSA，用于后续折叠
• 在托管 GPU 上运行分子动力学或其他生物物理工作流
• 批量筛选大量序列或设计结果，并使用同一工具
• 使用某项作业的输出作为下一项作业的输入，将多个工具串联成流水线（例如：设计 → 折叠 → 评分）

如果任务应在 Tamarind 的托管云上运行，而非本地安装环境，本技能就适用。对于纯本地的化学信息学或一次性的序列输入/输出，请改用本地库（RDKit、BioPython）。

访问和身份验证

1. 登录 app.tamarind.bio，并在账户/API 设置中创建 API 密钥。
2. 每个 REST 请求都必须使用 x-api-key 标头进行身份验证。
3. 切勿将密钥硬编码。 请从 TAMARIND_API_KEY 环境变量或 .env 文件中读取（使用 python-dotenv）。切勿将密钥提交到源代码管理中。

定价： 每位用户均可免费使用 10 个作业。如需更多，请联系 [email protected] 购买订阅。

export TAMARIND_API_KEY="your_api_key"
# List available tools
curl https://app.tamarind.bio/api/tools \
  -H "x-api-key: $TAMARIND_API_KEY"

基础 URL： https://app.tamarind.bio/api/

没有官方 Python SDK——PyPI 上名为 tamarind 的软件包是一个无关的 Neo4j 工具。请勿运行 uv pip install tamarind。请针对 REST API 编写普通的 requests 调用（端点结构见 openapi.yaml），或为 Agent 宿主使用 MCP 服务。

调用 Tamarind 的两种方式

MCP 服务（最适合 AI Agent）

Tamarind 在 https://mcp.tamarind.bio/mcp 托管了一个 MCP 服务（通过 X-API-Key 标头进行 API 密钥身份验证）。当你的 Agent 主机支持 MCP 时，优先使用它——这些工具以适合 Agent 的架构映射了 REST API：

• listModalities() / listTags() — 获取实时筛选词汇表（分子类型 / 功能），包括标签和工具数量；调用这些函数来了解有效的 modality / function 值，而不要将其硬编码
• getAvailableTools(modality?, function?, search?, custom?) — 发现工具（category / tag 是已弃用但仍受支持的别名）
• getJobSchema(jobType) — 获取工具的精确参数架构，以及一个起始载荷 exampleJob（提交前请先验证）
• validateJob(jobName, type, settings) — 提交前进行试运行验证
• submitJob(jobName, type, settings) / submitBatch(batchName, type, settings[], jobNames[])
• getJobs(jobName?, batch?, limit?, includeSequences?) — 列出 / 检查任务及其状态（默认省略每个任务体积较大的输入数据；传入 includeSequences=true 可保留）
• getJobLogs(jobName) — 获取输出日志以进行调试
• listJobFiles(jobName) — 列出输出文件（返回可用于串联的 s3Path）
• getResult(jobName, fileName?) — 下载结果
• uploadFile(filename) — 获取预签名上传 URL；或者使用 uploadFileContent(filename, content, encoding?)，通过 MCP 发送文件内容（适用于无法访问 S3 的主机，如沙盒 Agent）

范围说明：MCP 查询工具（getJobs、getResult、listJobFiles 等）仅限经过身份验证的账户使用。

REST API（通用）

使用 requests 发送普通 HTTP 请求——端点格式见 openapi.yaml。核心流程如下；完整操作示例见 references/workflows.md。

核心工作流

始终遵循发现 → 架构 → 验证 → 提交 → 轮询 → 获取结果的流程。不要将工具名称或设置硬编码——目录会频繁变化。

import os, time, requests

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

# 1. Discover tools. REST /tools returns the full list; filter client-side.
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in tools if t["name"] == "alphafold")

# 2. Get the exact schema for the chosen tool.
#    REST: each /tools entry already includes its inline `settings` schema
#          (parameter list) — find the entry whose name == your job type.
#    MCP:  getJobSchema(jobType) returns the same per-tool detail.

# 3. Submit a job. `settings` is tool-specific — match the schema exactly.
payload = {
    "jobName": "my-alphafold-run",          # ^[a-zA-Z0-9_-]+$, <=100 chars, 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 bad request; 403 budget exceeded; 401 unauthorized

# 4. Poll for completion.
#    NOTE the response shape: GET /jobs?jobName=<name> returns the job ROW
#    directly (no "jobs" wrapper); the list query (no jobName) returns
#    {"jobs": [...]}. Don't index ["jobs"][0] on the by-name response.
while True:
    job = requests.get(f"{BASE}/jobs", headers=HEADERS,
                       params={"jobName": "my-alphafold-run"}).json()
    if job["JobStatus"] in ("Complete", "Stopped", "Deleted"):
        break
    time.sleep(30)

# 5. Retrieve results. POST /result returns a presigned URL *string*;
#    GET that URL to download the actual results zip (two-step).
url = requests.post(f"{BASE}/result", headers=HEADERS,
                    json={"jobName": "my-alphafold-run"}).text.strip('"')
open("my-alphafold-run.zip", "wb").write(requests.get(url).content)

关于使用 MCP 工具实现此流程的 Agent 版本，以及更多示例，请参阅 references/workflows.md。

发现工具

目录中有数百种工具。始终在运行时枚举，切勿依赖硬编码列表。

REST GET /tools 会返回完整列表（不会在服务器端筛选）；每个条目均包含 {name, displayName, github, paper, description, settings}，其中 settings 是该工具的内联参数架构。在客户端进行筛选：

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

注意：两个接口都按工具名称返回一行——REST /tools 和 MCP getAvailableTools 都会去重（MCP 会保留最新版本的工具），因此匹配某个名称时只会返回一行。

MCP getAvailableTools(search=..., modality=..., function=...) 会在服务器端筛选，并为每个工具添加 categories / tags（category / tag 是 modality / function 的已弃用别名，但仍受支持）。不要将词汇表硬编码——它会变化。请通过 listModalities() / listTags() 获取实时值（每项均返回 value、label、description 和 toolCount），或读取每个 getAvailableTools 响应中返回的 availableCategories / availableTags 分类数组。Modality 表示分子类型（protein、antibody、peptide、small-molecule、nucleic-acid 等）；function 表示工具的用途（structure-prediction、binder-design、protein-ligand-docking 等）。

一些具有代表性的常用工具（请通过 /tools 验证）：alphafold、boltz（Boltz-2）、chai（Chai-1）、esmfold / esmfold2、rfdiffusion、proteinmpnn、ligandmpnn、boltzgen、bindcraft、diffdock。完整的类别 / 标签映射及工具元数据读取方法，请参阅 references/tool_catalog.md。

选择合适的工具

目录中每项任务都有许多工具；不要硬编码偏好的工具——按 function（和 modality）筛选，然后阅读每个候选工具的 description，并根据用户的实际目标进行匹配（你拥有的输入、需要的输出，以及速度或「不使用 MSA」等限制）。description 和 tags 字段是公开的「用途」信号；选择时以它们和 validateJob 为依据。以下是按任务分类的快速指引：

• 预测单个蛋白质／复合物的结构（function=structure-prediction）：AlphaFold3 级别的复现工具——boltz／chai／openfold／protenix／intfold——适用于所有情况，是准确度不错的默认选择，包括仅含蛋白质的体系；它们也能处理核酸与小分子复合物，因此只要体系中包含配体／RNA／DNA，就可以使用这些工具（而 boltz 还会预测结合亲和力）。alphafold（AF2）仍然是预测单体和多聚体的可靠选择（用 : 连接链）。esmfold 只需单序列（无需 MSA）且速度快——需要快速预测且没有 MSA 时可以使用；esmfold2 更新一些，默认会以 MSA 为条件（其 model 设置提供更快的单序列模式）。抗体（abodybuilder、immunebuilder）、环肽（highfold）和构象集合（afcluster、alphaflow）也有专用的折叠工具——请筛选并阅读说明。
• 设计结合蛋白（function=binder-design）：bindcraft（从头设计微型蛋白结合体）和 boltzgen（针对蛋白质和小分子靶标的结合体，包括纳米抗体／抗体／肽）是首选的从头结合体设计工具；rfdiffusion 也能设计结合体，适合基序支架设计／扩展现有骨架的多样性。抗体专用生成工具位于 function=antibody-design 下。
• 为已知骨架设计序列（function=inverse-folding）：proteinmpnn（通用）、ligandmpnn（考虑配体），以及适用于耐热性、可溶性和抗体的 MPNN 变体。逆折叠以结构为输入并生成序列——还需折叠这些序列以进行验证（参见链式调用）。
• 对接小分子（function=protein-ligand-docking）：优先使用 boltz／chai——它们会将配体与复合物共同折叠，并预测结合状态下的结构，而不是将配体对接到固定受体上；需要针对已知结合口袋进行快速、大规模筛选时，则使用 autodock-vina。
• 预测结合亲和力（function=binding-affinity）或生成 MSA（搜索 msa）——请筛选并阅读说明。

用户指定某个工具时，请评估该工具，并对其 tag 组中的替代工具进行合理性检查——通常会有速度更快或更合适的同类工具。不确定时，可先用 getJobSchema／validateJob 确认候选工具确实接受你拥有的输入，再做决定。

作业设置、架构与验证

每种工具都有自己的 settings 架构。提交前先获取该架构：

• REST /tools 条目：每个 settings 参数都是一个经过精简的字典。始终存在的只有 name 和 required；只有在相关时才会出现 type、default、description、options（约 60% 的参数有 type）——因此请使用 param.get("type")，而不是 param["type"]。高级门控键（exclude、conditionals）完全不会出现在 REST 响应中。
• MCP getJobSchema(jobType)：完整架构，包括 exclude、conditionals 和边界值。需要根据这些门控键进行判断时，请使用 MCP。（restrictOrgs 在这两个接口中都会被移除——无法使用的组织门控参数会直接省略；参见 references/api_reference.md。）

提交前务必使用 validateJob（MCP）——这是可靠的检查方式。它会运行与 /submit-job 相同的验证，但不会提交作业，并会指出第一个缺失或无效的字段。不要尝试根据架构键手动推断要移除哪些字段（通过 REST 根本看不到这些键）——让 validateJob 来告诉你。（响应中可能包含 source 字段，例如 "static-fallback"——这是关于使用哪种架构来源进行验证的内部说明；你应以 valid: true/false 作为判断依据。）

validateJob 会返回设置的 normalized 视图，其中已填入默认值。提交时应使用你验证过的同一份干净 settings；将 normalized 仅视为参考信息（其中可能包含你未设置的默认值，以及某些工具的平台管理字段），因此请根据自己的设置构建提交内容，而不要直接使用 normalized 整体内容。

**序列：**氨基酸字符串；多聚体的不同链之间用冒号（:）分隔，例如 "MVLS...:EVQL..."。请注意，有些工具（例如 boltz、chai）需要的不只是 sequence——boltz 还需要 inputFormat（并接受 yamlFile/molecules）。务必使用 getJobSchema/validateJob 了解工具必需的字段；不要假设只提供 sequence 就足够。

平台内部字段——切勿自行设置；这些字段由平台管理：submit_method、monomer_msa、msa。完整的字段处理规则请参见 references/api_reference.md。

提交前应告知用户会产生重要影响的选择，不要默默采用默认值。 如果请求已明确指定要运行的内容，请直接执行。但如果请求较为开放，或某项设置会显著影响结果、运行时间或成本（模型/变体、样本数或随机种子数、是否启用 MSA、GPU 层级、批次大小），请先列出有意义的选项和你原本会采用的默认值，让用户在提交前选择——不要先默默决定，等作业排队后才告知。这时，getJobSchema 和 validateJob 的 normalized 会准确显示你准备代用户填写的选项，因此你可以标出值得快速确认的少数几项。对于批量作业，这一点尤其重要，因为一个共享设置会影响每个作业。

文件输入（PDB、CIF、SDF，……）

带有文件参数的工具接受以下 3 种输入方式：

1. 先上传，再通过裸文件名引用。 PUT /upload/{filename}，或 MCP uploadFile → 预签名 URL → curl -X PUT -T file "<url>"。如果你的主机无法访问 S3（例如没有出站网络的沙箱 Agent），请改用 MCP uploadFileContent(filename, content, encoding?)，通过 MCP 通道发送文件内容——默认按文本处理，二进制文件使用 encoding="base64"。文件会存储在 S3 键 {email}/{filename} 下，但在 settings 中引用时，只能使用裸 filename（例如 "targetFile": "GLP1R_ECD.pdb"）——平台会自动将其限定到你的账户。请勿添加 email 前缀：传入 {email}/{filename} 会导致查找时重复添加前缀，submit-job 会以 400 错误失败，并提示 "The following files have not been uploaded: <email>/<file>"。使用 MCP getFiles(search=...) / REST GET /files 确认存储区登记的确切名称（这是仅含裸文件名的列表）。
2. 通过路径引用先前作业的输出：JobName/path/to/file.ext（这就是串联作业的方式——见下文）。
3. 内联内容。 直接将文件的文本内容作为字段值发送。

易踩的坑： 对于文件类型参数，纯字符串值会被视为内联文件内容，而不是现有对象的路径。若要指向已上传的文件，请使用裸 filename（而非 {email}/... S3 键）；若要引用先前作业的输出，请使用 JobName/... 路径格式——不要使用你期望能解析为新内容的裸字符串。

validateJob 注意事项。 响应可能包含 source 字段（例如 "static-fallback"）——它标记的是工具 schema 的解析方式（内置工具始终返回 static-fallback），而非验证器是否可访问，因此应依据 valid 而非 source 行事。对于文件参数：请使用已上传文件的裸文件名进行引用（见上文）——裸文件名会解析到限定于你账户的对象，而带 email 前缀的字符串可能会被视为内联内容，并导致文件类型检查失败（"... must contain ATOM records"）。此外，传入内联文件内容会使 validateJob 在验证前同步上传文件，这可能会很慢；建议优先按名称引用已上传文件（见上文）。如果试运行耗时过长，请跳过它，直接让 submit-job 进行验证。

将任务串联成流水线

已完成任务的输出会成为下一个任务的输入，无需下载再上传。输入类型要与下一个工具的实际要求匹配： 序列设计工具（ProteinMPNN）会输出序列，因此要将每条序列作为 sequence 传入，以便进行折叠；需要文件参数的工具则接收路径。

最简洁的设计→折叠链是使用 MCP submitBatch(fromJob=...)，它会读取已完成设计任务生成的序列，并将每条序列作为一个任务进行折叠：

# ProteinMPNN designs sequences -> fold every one with AlphaFold, one call:
submitBatch(batchName="verify-designs", type="alphafold", fromJob="my-proteinmpnn-job")

对于文件输入（例如需要 .pdb/.cif 的工具），在文件参数中使用路径格式 JobName/path/to/file.ext 引用之前任务的输出。有两点需要注意，且均已通过验证确认：(1) 文件类型要符合参数要求——例如，AlphaFold 的 templateFiles 仅接受 .cif，且该参数是列表，并且需要设置 templateMode: "custom" 才能使用；(2) templateFiles 用于结构模板，而不是“折叠设计出的序列”——要折叠序列，请传入 sequence。将文件参数用于链式调用前，务必使用 getJobSchema/validateJob 确认其类型和条件。

要查找任务的准确输出路径，请使用 MCP listJobFiles(job1)——它会返回每个文件的 s3Path，可直接用于下一个 submitJob。（REST GET /files 会以扁平名称列表的形式列出你账号中已上传的文件；它不会枚举任务的输出。）Tamarind 还支持保存的流水线：在 UI 中创建流水线，然后通过 /run-pipeline（{pipelineName, initialInputs, inputs}）运行；或者通过 /submit-pipeline 内联定义 stages[]（每个阶段都指定一个 task 和 toolSettings，并使用 "pdbFile": "pipe" 将一个阶段的输出传递给下一个阶段）。参见 references/workflows.md。

批量提交

一次调用中提交多个使用同一工具的任务。Python 写法使用并行的 settings[] 和 jobNames[] 数组（长度相同，最多 100 个）：

requests.post(f"{BASE}/submit-batch", headers=HEADERS, json={
    "batchName": "egfr-binder-screen",
    "type": "alphafold",
    "jobNames": ["seq1", "seq2", "seq3"],
    "settings": [{"sequence": "..."}, {"sequence": "..."}, {"sequence": "..."}],
    # optional: "maxRuntimeSeconds": 3600, "weightedHoursBudget": 100,
    # (some accounts also accept an optional "gpuType" — confirm with support)
})

查询批次状态时，应轮询批次父任务的 batchStatus，而不是子任务的 JobStatus。 一个批次会创建一个父任务（Type: "batch"）和多个子任务。子任务完成计算后会立即变为 Complete，但批次随后还要花几分钟汇总结果，生成最终可下载输出。按名称获取父任务并查看 batchStatus：

import time
while True:
    # ?jobName= returns the parent ROW directly (no "jobs" wrapper)
    parent = requests.get(f"{BASE}/jobs", headers=HEADERS,
                          params={"jobName": "egfr-binder-screen"}).json()
    bs = parent.get("batchStatus")
    if bs == "Complete":
        break
    if bs in ("Stopped", "AggregationFailed"):
        raise RuntimeError(parent.get("AggregationError", bs))
    time.sleep(15)   # Running / Aggregating -> keep waiting
# When Complete, the parent carries a presigned `resultUrl` and a `statuses`
# subjob tally ({Complete, Running, In Queue, Stopped}).
open("batch.zip", "wb").write(requests.get(parent["resultUrl"]).content)

在 GET /jobs?batch=<name> 中添加 includeSubjobs=true，即可列出每个子任务的行。

任务状态生命周期

单个任务会报告 JobStatus；批次父任务会报告 batchStatus（批次应轮询该状态，见上文）。

状态	含义
In Queue	已接受，等待可用容量
Running	正在工作节点上执行
Complete	已成功完成——结果可用
Stopped	已停止（失败、超时、手动停止或预算限制）
Deleted	任务已在带外删除
Aggregating	（仅批次父任务）子任务已完成；正在生成最终输出
AggregationFailed	（仅批次父任务）汇总步骤失败

已完成的任务会附带 Score（特定于工具的指标，例如折叠任务的 pLDDT/pTM/ipTM）和 WeightedHours。将 Complete/Stopped/Deleted（批次还包括 AggregationFailed）视为终态；每隔 15-30s 轮询一次。遇到任何终态都应退出轮询循环，而不只是 Complete/Stopped——否则，轮询期间变为 Deleted 的任务可能导致循环永不结束。对于 Stopped 任务，请获取 getJobLogs(jobName) 查看原因。WeightedHours 是按任务计费的用量单位；使用 weightedHoursBudget 为批次设定上限，提交时收到 403 表示已达到预算（参见 references/api_reference.md 和 /usage-statistics 端点）。

错误处理

代码	含义	操作
400	错误请求 / 设置无效	根据 schema 重新检查；先运行 validateJob
401	未授权	检查 x-api-key
403	超出预算（组织/团队）	缩小范围或提高预算
429	请求过多，触发速率限制	等待后重试
500	服务器错误	重试；若问题持续，请联系支持人员

参考文件

openapi.yaml 规范是端点结构的事实来源；这些文件补充了规范未明确说明的行为和注意事项：

• references/examples.md — 按常见工具（alphafold/boltz/diffdock/autodock-vina/proteinmpnn/batch）提供已验证的 settings 负载、可直接复制粘贴的自检示例、“哪些情况会失败及对应的确切错误”列表，以及输出结构说明。想要获取可用的负载，请从这里开始。
• references/api_reference.md — 端点速查，以及一些不明显的结构：按名称查询 /jobs 会返回一条原始记录（而不是 {jobs:[...]}），/result 是两步下载，批处理父任务通过 batchStatus 轮询，/files 是扁平的名称列表，以及 settings 字段处理规则。
• references/tool_catalog.md — 类别/标签映射、如何读取工具和参数元数据，以及常见工具系列。
• references/workflows.md — 端到端配方：折叠序列、提交前验证、上传并引用文件、设计→折叠串联、通过聚合轮询筛选批次、用量统计、分页，以及非阻塞的“立即提交、稍后检查”长任务模式。

相关技能

• rowan：Rowan 是一个云原生分子建模和药物化学工作流平台，提供 Python API。
• adaptyv：如何使用 Adaptyv Bio Foundry API 和 Python SDK 进行蛋白质实验设计、提交和结果检索。
• diffdock：DiffDock 和 DiffDock-L 分子对接。