alterlab-adaptyv

Adaptyv

Adaptyv Bio は Foundry クラウドラボを運営しています。タンパク質配列とターゲットを送信すると、ラボがアッセイを実施し、結合・親和性、熱安定性、発現、蛍光の実験データを取得できます。公開されている Foundry API を使うと、ライフサイクル全体をプログラムから操作できます。所要期間は数週間程度です。固定の期間を前提にせず、実験ごとの見積もりで最新の目安を確認してください。

リクエスト／レスポンスの正確な形式は変更される場合があります。このスキルは、https://foundry-api-public.adaptyvbio.com/api/v1/openapi.json に公開されている OpenAPI ドキュメント（v0.0.2、2026-09-23 確認）をもとに、API の仕様をまとめています。この仕様では https://devs.adaptyvbio.com が本番環境のベース URL として記載されています。両方のホストで同じ /api/v1 ルートを利用できます。https://docs.adaptyvbio.com も参照してください。

このスキルを使用する場面

Adaptyv のクラウドラボで、設計 → テスト → 学習のサイクルを回す際に使用します。カタログからターゲットを選び、設計した配列を事前にスクリーニングして送信し、見積もりから製造まで実験の進捗を追跡して、結合、安定性、発現、蛍光、エピトープビニング、酵素活性のデータを取得できます。

対象外の場面

シナリオ	代わりに使用するもの
ウェットラボ工程に進む前に、固定バックボーン用の配列を設計する（逆フォールディング）	alterlab-proteinmpnn
タンパク質言語モデルの埋め込み、または ESM3 / ESM C による生成設計	alterlab-esm
Ginkgo のクラウドラボ（RAC）での無細胞発現やその他のプロトコル	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 - 初期の溶解性フィルタリング（どちらもウェブサービスであり、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 スイートの一部です。