alterlab-adaptyv

Adaptyv

Adaptyv Bio 运营着 Foundry 云实验室：提交蛋白质序列和靶标，实验室会执行检测，随后你可以获取实验数据（结合／亲和力、热稳定性、表达量、荧光）。公开的 Foundry API 可通过编程方式驱动完整流程。周转时间通常以周计；请根据每项实验的报价确认当前预估时间，不要假设时间固定。

请求／响应的具体格式会不断变化。本技能根据 OpenAPI 文档（v0.0.2，2026-09-23 检查）中公布的 API 契约编写，文档地址为 https://foundry-api-public.adaptyvbio.com/api/v1/openapi.json；该规范将 https://devs.adaptyvbio.com 列为生产环境基础 URL，且两个主机都提供相同的 /api/v1 路由。另请参阅 https://docs.adaptyvbio.com。

何时使用此技能

使用此技能，通过 Adaptyv 的云实验室完成设计 → 测试 → 学习：选择目录中的靶标， 对设计的序列进行预筛选并提交，通过报价和生产阶段跟踪实验， 并获取结合、稳定性、表达量、荧光、表位分组或酶活性数据。

不适用场景

场景	改用
在任何湿实验室步骤之前，为固定骨架设计序列（逆向折叠）	alterlab-proteinmpnn
使用 ESM3 / ESM C 生成蛋白质语言模型嵌入或进行生成式设计	alterlab-esm
在 Ginkgo 云实验室（RACs）进行无细胞表达或其他实验方案	alterlab-ginkgo-cloud
在 ELN/LIMS 中记录构建体、质粒和结果	alterlab-benchling

优先使用官方工具

Adaptyv 提供了自己的集成方案——应优先使用这些方案，而非自行编写 requests：

• 官方 Python SDK — github.com/adaptyvbio/adaptyv-sdk（MIT）。基于装饰器：使用 @lab.experiment(target=...) 包装设计函数；从环境变量读取 ADAPTYV_API_KEY / ADAPTYV_API_URL（以及可选的 ADAPTYV_ORGANIZATION_ID）。从源码安装（克隆后运行 pip install -e .——尚未确认是否发布到 PyPI；固定版本前请先核实）。
• Adaptyv 自有的 Claude Code 技能 — github.com/adaptyvbio/protein-design-skills。可作为蛋白质设计和 Foundry 工作流的有用参考。

如果无法使用 SDK，或需要精细控制整个流程，请使用本技能中基于原始 requests 的示例。

快速入门

身份验证设置

1. 在 Foundry 门户中创建令牌：https://foundry.adaptyvbio.com/ → Organization → Settings → Tokens（选择角色：Member = 读写，Viewer = 只读；设置过期时间）。令牌值只会显示一次——请立即复制。
2. 将其设置为环境变量（切勿提交到代码库）：

export ADAPTYV_API_KEY="your_token_here"

或者将其放入被 git 忽略的 .env 文件中：

ADAPTYV_API_KEY=your_token_here

安装

如果直接使用原始 API：

uv pip install requests python-dotenv

基本用法

API 采用 draft → submit → confirm quote 流程：创建实验（初始状态为 draft），提交实验（随后 Adaptyv 会异步生成报价，状态为 waiting_for_confirmation），然后确认报价以创建发票。sequences 是 {label: amino_acid_string} 映射（值也可以是 {"aa_string": "...", "control": true} 等对象；多链构建体以冒号连接各链，例如 "heavy:light"）。

import os
import requests
from dotenv import load_dotenv

load_dotenv()

api_key = os.getenv("ADAPTYV_API_KEY")
base_url = "https://foundry-api-public.adaptyvbio.com/api/v1"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

# 1. Create a draft experiment
resp = requests.post(
    f"{base_url}/experiments",
    headers=headers,
    json={
        "name": "mini-binder round 1",
        "experiment_spec": {
            "experiment_type": "affinity",   # screening|affinity|thermostability|fluorescence|expression|epitope_binning|enzyme_activity
            "method": "bli",                 # bli|spr (for binding-type assays)
            "target_id": "<target uuid from GET /targets>",
            "sequences": {
                "design_a": "MKVLWALLGLLGAA...",
                "design_b": "MATGVLWALLG...",
            },
        },
    },
)
resp.raise_for_status()
experiment_id = resp.json()["experiment_id"]

# 2. Submit the reviewed draft; the quote is generated asynchronously afterwards
requests.post(f"{base_url}/experiments/{experiment_id}/submit", headers=headers).raise_for_status()

# 3. Poll GET /experiments/{id}/quote until it exists, review totals/expiry, then accept it
#    (creates the invoice; the JSON body is required even when empty)
quote = requests.get(f"{base_url}/experiments/{experiment_id}/quote", headers=headers)
requests.post(f"{base_url}/experiments/{experiment_id}/quote/confirm",
              headers=headers, json={}).raise_for_status()

可用实验类型

Foundry 支持以下 experiment_type 值：

• screening - 通过生物层干涉（BLI）或 SPR 检测结合。需要靶标。
• affinity - 通过 BLI/SPR 测定动力学常数（KD、kon、koff）。需要靶标。
• thermostability - 通过 DSF 测定熔解温度（Tm）。不需要靶标。
• fluorescence - 测定荧光强度。不需要靶标。
• expression - 定量蛋白质产量。不需要靶标。
• epitope_binning - 对结合物进行表位分组；需要靶标，且序列数须为 4–28 条，并为 4 的倍数。
• enzyme_activity - 酶活性检测。不需要靶标。

有关各项检测及其输出的详细信息，请参阅 reference/experiments.md。

蛋白质序列优化

提交序列前，请对其进行优化，以提高表达量和稳定性：

需要解决的常见问题：

• 未配对的半胱氨酸会形成不需要的二硫键
• 疏水区域过多，导致聚集
• 预测的溶解性较差

推荐工具：

• NetSolP / SoluProt — 初步溶解性筛选（两者都是 Web 服务，而非 pip 包）
• SolubleMPNN — 偏向溶解性的序列重新设计（ProteinMPNN / LigandMPNN 系列中的一组权重）
• ESM（fair-esm）— 序列似然度 / 自然度评分
• ipTM（AlphaFold-Multimer / ColabFold）— 评估结合剂设计的界面稳定性
• pSAE — 根据预测或已知结构评估溶剂可及的疏水性暴露

详细的优化工作流和工具用法，请参阅 reference/protein_optimization.md。

API 参考

完整的 API 文档（包括所有端点、请求 / 响应格式和身份验证详情）请参阅 reference/api_reference.md。

示例

常见用例的具体代码示例（实验提交、状态跟踪、结果检索、批处理）请参阅 reference/examples.md。

重要说明

• Foundry API 是公开的，但仍在不断演进——请以 OpenAPI 文档（/api/v1/openapi.json）为准，并在依赖字段名称前进行核实。
• 提交分阶段进行：创建 draft（可先通过 POST /experiments/cost-estimate 估价），调用 POST .../submit，然后审核并调用 POST .../quote/confirm。确认报价前不会开具账单。创建时可使用 skip_draft / auto_accept_quote，以支持预先验证的自动化流水线——仅在用户已批准费用时使用。
• affinity / screening / epitope_binning 需要目录中的 target_id（GET /targets）；affinity / screening 还需要 method（bli|spr）；thermostability、fluorescence、expression 和 enzyme_activity 均不需要这些参数。
• 身份验证方式为 Authorization: Bearer <token>；GET /whoami 可确认令牌所属的组织。
• 周转时间需要数周——请查看实验或报价中的预估时间，不要假定为固定时长。
• 支持与文档：[email protected] / https://docs.adaptyvbio.com。
• 适用于高通量、由 AI 驱动的蛋白质设计工作流（闭环设计 → 测试 → 学习）。

AlterLab Academic Skills 套件的一部分。