Tamarind Bio

Tamarind Bio 是做什么的？

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

官方文档： app.tamarind.bio/api-docs · 平台界面 at 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、pipeline 等）不包含在其中——请使用 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 的托管云上运行而不是本地安装时，此技能是合适的选择。对于纯本地的化学信息学或一次性序列 I/O，请使用本地库（RDKit、BioPython）。

访问与认证

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

定价： 每个用户有 10 个免费作业。对于更大使用量，联系 [email protected] 购买订阅。

export TAMARIND_API_KEY="your_api_key"
# 列出可用工具
curl https://app.tamarind.bio/api/tools \
  -H "x-api-key: $TAMARIND_API_KEY"

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

没有官方 Python SDK —— 名为 tamarind 的 PyPI 包是一个无关的 Neo4j 工具。不要 uv pip install tamarind。请针对 REST API 编写普通的 requests 调用（端点形状在 openapi.yaml 中），或为代理主机使用 MCP 服务器。

调用 Tamarind 的两种方式

MCP 服务器（最适合 AI 代理）

Tamarind 在 https://mcp.tamarind.bio/mcp 托管 MCP 服务器（通过 X-API-Key 头进行 API 密钥认证）。当您的代理主机支持 MCP 时，请优先使用它——这些工具以代理友好的模式映射 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?) —— 列出/检查作业和状态（默认省略体积大的每个作业输入 blob；传递 includeSequences=true 以保留它）
• getJobLogs(jobName) —— 获取输出日志以进行调试
• listJobFiles(jobName) —— 列出输出文件（返回 s3Path 用于链式调用）
• getResult(jobName, fileName?) —— 下载结果
• uploadFile(filename) —— 预签名的上传 URL；或 uploadFileContent(filename, content, encoding?) 在主机无法访问 S3 时通过 MCP 发送文件内容（沙盒代理）

范围说明：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. 发现工具。REST /tools 返回完整列表；在客户端筛选。
tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()
alphafold = next(t for t in tools if t["name"] == "alphafold")

# 2. 获取所选工具的精确模式。
#    REST：每个 /tools 条目已包含其内联 `settings` 模式
#          （参数列表）——找到名称与您的作业类型匹配的条目。
#    MCP：getJobSchema(jobType) 返回相同的每个工具详细信息。

# 3. 提交作业。`settings` 是工具特定的——精确匹配模式。
payload = {
    "jobName": "my-alphafold-run",          # ^[a-zA-Z0-9_-]+$，<=100 字符，唯一
    "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 错误请求；403 预算超限；401 未授权

# 4. 轮询完成。
#    注意响应形状：GET /jobs?jobName=<name> 直接返回作业行
#    （没有 "jobs" 包装器）；列表查询（无 jobName）返回
#    {"jobs": [...]}。不要按名称响应上索引 ["jobs"][0]。
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. 检索结果。POST /result 返回一个预签名的 URL *字符串*；
#    获取该 URL 以下载实际的结果 zip 文件（两步）。
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 工具的此循环的代理版本，以及更丰富的示例，请参见 references/workflows.md。

发现工具

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

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

tools = requests.get(f"{BASE}/tools", headers=HEADERS).json()   # 一个列表
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 分面数组。Modalities 是分子类型（protein、antibody、peptide、small-molecule、nucleic-acid 等）；functions 是工具的功能（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 视为信息性的（它可以携带您未设置的默认值，以及某些工具的平台管理字段），因此从您自己的设置构建提交，而不是从标准化 blob。

序列： 氨基酸字符串；用 : 分隔多聚体的链。对于蛋白质-配体系统，将蛋白质序列放在首位。对于蛋白质-核酸系统，将蛋白质序列放在首位。validateJob 将报告任何格式问题。