tamarind

Tamarind Bio

Tamarind 在托管计算上运行分子设计与结构生物学工具： 结构预测、蛋白质与抗体设计、对接、结合亲和力 预测、MSA 生成和分子动力学。当用户请求 Tamarind、其 REST API/MCP 服务，或这些科学工具的云端执行时使用它。 对于本地序列处理或分子描述符，请使用本地库。

来源与审查范围

REST 契约和公开目录已于 2026-09-30 审查。示例在 针对用户账户验证之前仅为示意；本次审查未运行 需要身份验证的任务，也未确立任何模型的科学准确性。

• API 索引 和 完整指南。
• 当前 OpenAPI 包含发现、 验证、任务、文件，以及较新的流水线/自定义工具接口。 openapi.yaml 也可用。检查 所需路径是否存在：当后端规范无法获取时，合并后的规范可能仅返回经典 接口却仍返回 HTTP 200。
• 公开目录 无需密钥；可按 ?type= 或 ?tag= 查询。它记录公开工具和条件性必填设置，而非 每个可选参数或账户权益。
• 产品文档索引 链接到 Markdown 页面，包括 MCP 指南。

在编排运行之前，获取账户的当前 schema。当文字指南 与 OpenAPI 不一致时，字段形态以操作/schema 为准，并记录任何 未解决的差异，而非猜测。

访问

1. 使用用户的 Tamarind 部署。共享基础地址为 https://app.tamarind.bio/api；专用的组织部署有其自己的 主机和账户数据。以下每个相对 REST 路径都在 /api 下。
2. 从部署的 API 设置中获取密钥，并从 TAMARIND_API_KEY 读取它；将其作为 x-api-key 发送。将密钥排除在文件和日志之外。
3. 在扩大规模之前，检查账户的当前配额和计算预算。 免费使用是每月配额，而非永远无条件承诺十个任务； 计费和权益可能会变化。

# Public discovery requires no credential.
curl --fail-with-body 'https://app.tamarind.bio/tools.json?type=alphafold'
# Account-scoped discovery:
curl --fail-with-body 'https://app.tamarind.bio/api/tools' \
  -H "x-api-key: $TAMARIND_API_KEY"

对于 REST 示例，请在执行环境中安装 requests。官方 命令行发行版是 tamarind-cli，其 Custom Tools Python 客户端导入 方式为 from tamarind import Tamarind；名为 tamarind 的不相关包并非 此客户端。参见 SDK 参考。 以下核心任务配方直接使用 HTTP。

工作流

1. 发现。 读取 GET /tools，将用户的科学任务与工具描述进行匹配。内置工具返回一个数组；?custom=true 仅列出旧版自定义工具。当前的自定义部署可能缺失于此列表中：在断定其不可用之前，请使用已知的已部署名称及其 schema。
2. 读取 schema。 GET /tools/{name}/schema 返回 settings 对象的 JSON Schema。GET /tools 也提供一份精简的 settings 参数列表。检查依赖任务的字段、文件扩展名、列表值和默认值。
3. 验证。 发送 POST /validate-job，附带 type、settings 和可选的 jobName。先检查 HTTP 状态，再检查 JSON 中的 valid。成功后，检查并使用 normalized 作为要提交的 settings。如果返回 unrecognized_settings，即使同时带有 valid: true 也要处理：否则可选字段的拼写错误可能会静默地使默认值继续生效。验证只检查字段，不检查所有提交策略、队列限制或部署就绪状态。
4. 提交一次。 POST /submit-job 接受 jobName、type、settings、可选的 version（用于自定义工具构建）以及可选/组织要求的 projectTag。持久保存提交的名称和 settings。成功响应是纯文本，而不是 JSON 回执。使用返回的存储名称。
5. 轮询。 GET /jobs?jobName=... 直接返回一行。单任务的终止状态为 Complete、Stopped 和 Failed；处理旧版 Deleted 或精确查找错误时不要无限循环。使用 batchStatus 轮询批处理父任务，并在较新流水线各自的运行端点上轮询它们。
6. 下载并检查。 POST /result 在 200 时返回 JSON 字符串 URL，或在 202 时返回 status: "preparing"。在 202 之后重试获取结果，而不要重新提交计算。使用 GET 获取签名 URL 时不要带 Tamarind API-key 请求头。仅对成功的运行下载归档；对于已停止/失败的任务，请求 fileName: "output.log"。下载后验证科学输出。

工作流配方 实现了验证、存储名称、有界轮询、202 处理、批处理验证和分页。它们已使用模拟响应在本地进行了冒烟测试；经过身份验证的执行仍未测试。

选择工具与解读结果

根据输入、预期输出和建模假设进行选择，然后在实时目录中确认候选工具。以下仅为参考锚点，并非保证的目录：

任务	候选工具与决策
蛋白质/复合物结构	alphafold 用于 AF2 单体/多聚体；boltz、chai 或 protenix 用于共折叠，包括配体/核酸；esmfold 用于快速单序列蛋白质折叠。单独检查 esmfold2：其当前目录包括蛋白质、DNA、RNA 和配体复合物。
结合体/基序设计	bindcraft、boltzgen、rfdiffusion；根据靶标类型、支架约束和所需结构输入进行选择。
反向折叠	proteinmpnn/ligandmpnn 消耗结构并设计序列。重新折叠设计结果，并与预期的骨架/界面进行比较。
小分子对接	autodock-vina 用于固定受体和搜索框；diffdock 用于扩散对接；boltz/chai 用于共折叠。应为任务选择建模方法，而不是为了避免提供必需输入。
抗体/可开发性/MSA/MD	根据具体任务筛选描述和 schema；可用性和输入因工具而异。

置信度分数描述的是模型置信度，而非实验结合、特异性或亲和力。比较设计的骨架、界面、冲突、链/残基映射和可开发性。检查配体化学和立体化学；对接分数与实测结合自由能不能互换。记录工具/模型、输入来源、链映射、种子/样本、MSA/模板选择、标准化设置以及任何用户选择的过滤阈值。

尊重用户选择的工具和预算。对于常规选择，使用授权的默认值；在大型任务之前，暴露那些对科学任务或计算范围有重大影响的未解决选择。绝不要因为其输入更容易提供而暗中替换为不同的科学任务。

文件输入与链式调用

• 使用 PUT /upload/{filename} 上传结构（二进制正文；遵循文档中的重定向），然后引用注册的相对名称，例如 target.pdb，或当使用了 ?folder=inputs 时引用 inputs/target.pdb。
• 使用 GET /files 确认名称；它返回所选文件夹的非分页数组，而不是某个任务的输出列表。
• 优先使用这些路径，而不是内联文件内容。当前指南说明冗余的账户邮箱前缀会被剥离；不再存在通用的双重前缀失败。任意字符串不一定是文件引用。
• 将已完成任务的文件作为 JobName/path/to/file.ext 复用，并匹配下一个参数支持的扩展名以及列表/标量形状。不要猜测文件名。
• ProteinMPNN 设计必须输入到折叠工具的 sequence 字段。结构模板字段并不意味着“折叠这个设计的序列”。读取生成的 FASTA/CSV 序列，并为每个序列验证一个折叠设置对象。
• 不要编写内部字段，例如 submit_method、msa 或 monomer_msa。

批处理与流水线

POST /submit-batch 接受一个 type、一个非空的 settings 数组、batchName，以及可选的并行 jobNames。使用数组模式 /validate-job 校验每一行（每次调用最多 1,000 行），并采用每一行规范化后的 settings。提交最多允许 30,000 个展开作业，其中计入 design fan-out，并且有单独的约 4.5 MB 请求限制。需同时针对这两个约束进行拆分。不要假设旧的 weightedHoursBudget、maxRuntimeSeconds 或 gpuType 请求字段会强制执行上限：它们已不在当前 batch schema 中。请使用已确认的账户控制项，以及商定的作业/样本数量。

轮询 GET /jobs?jobName=<batchName>，直到 batchStatus 为 Complete、Stopped 或 AggregationFailed。子作业可能在聚合完成前就已结束。通过 /result 获取归档并处理 202；resultUrl 是可选的，并不是可靠的就绪信号。使用 startKey 分页 GET /jobs?batch=... 以检查子作业。

对于新的已保存工作流，使用 /pipelines 下的 template/run API：阅读当前 pipeline 图契约，使用 POST /pipelines/validate 校验拟议的运行，使用 POST /pipelines/submit 提交（必需 name、bindings，以及 templateId/pipeline 之一），并轮询 GET /pipelines/runs/{run_id}。其状态为小写，且与作业状态相互独立。旧版 /submit-pipeline 和 /run-pipeline 仍有文档记录；API reference 给出了它们实际必需的字段。

MCP 替代方案

使用 OAuth 2.1 或 x-api-key 头连接到 https://mcp.tamarind.bio/mcp。官方指南确认了 submitJob、submitBatch、getJobs、getResult、uploadFile 和 getFiles。在使用签名或解读结果 envelope 之前，请先阅读所连接服务的 tools/list schema。

如果连接声明提供诸如 getAvailableTools、getJobSchema 或 validateJob 等发现/校验辅助工具，请使用其当前 schema。额外辅助工具、过滤词表、submitBatch(fromJob=...) 以及通过 MCP 上传的变体并未得到公开指南的保证。本次审查的匿名 tools/list 请求返回了 401，因此其当前契约未经验证。需要时请使用已有文档的 REST 等效方式。

恢复

HTTP 认证失败因路由而异：经典端点可能返回 400，作业可能返回 401 或网关 403，用量可能返回 401。403 并不能证明是预算错误。在更改设置前，请检查状态和实际响应正文。无论 Content-Type 如何，提交错误都可能是 JSON 或纯文本。

提交时的超时/5xx 并不能证明没有内容入队。重试前先查询已持久化的名称；对于 campaign，使用 POST /jobs/search，每次请求最多 1,000 个名称。遵守速率限制，并避免在大规模场景下对每个作业单独发起一次轮询请求。413 会在创建作业前拒绝超大请求；请拆分请求正文，或单独上传文件内容。DELETE /delete-job 是软删除：它会隐藏作业，并使已存储的结果文件保持原样。

参考文件

• API reference：端点形态、校验、分页、认证差异，以及旧版/新版 pipeline 边界。
• Tool catalog：schema 解读与发现。
• Examples：当前基于 catalog 的 settings 示例及工具特定注意事项，明确以验证范围为其边界。
• Workflows：带本地 mock 验证的可执行 HTTP 配方；本次审查未运行任何需要认证的科学作业。