Run protein binding experiments from Python

Quick start • Features • API reference • Examples

---

Quick start

git clone https://github.com/adaptyvbio/adaptyv-sdk.git
cd adaptyv-sdk
pip install -e .

from adaptyv import lab

# Uses ADAPTYV_API_KEY and ADAPTYV_API_URL from your environment

@lab.experiment(target="PD-L1")
def design_binders():
    return {
        "design_a": "MVKVGVNG...",
        "design_b": "MKVLVAG...",
    }

result = design_binders()
print(f"Experiment: {result.experiment_url}")

# Additional decorator parameters:
# @lab.experiment(
#     target="PD-L1",
#     auto_confirm=True,              # Auto-confirm quote
#     experiment_type="screening",    # screening/affinity/thermostability/fluorescence/expression
#     method="bli",                   # bli/spr
#     n_replicates=3,                 # Number of replicates
# )

---

Features

• Picks up ADAPTYV_API_KEY and ADAPTYV_API_URL from environment
• Retries on failure with exponential backoff
• Type hints throughout
• Context managers for cleanup

---

Configuration

Set your credentials as environment variables:

export ADAPTYV_API_KEY=your_api_key
export ADAPTYV_API_URL=https://foundry-api-public.adaptyvbio.com/api/v1
export ADAPTYV_ORGANIZATION_ID=your_org_id  # Optional

Or configure programmatically:

from adaptyv import Lab

lab = Lab.setup(
    api_key="your_api_key",
    base_url="https://foundry-api-public.adaptyvbio.com/api/v1",
    organization_id="your_org_id",  # Optional
)

---

API reference

List targets

from adaptyv import lab

# Single page
targets = lab.list_targets()

# Iterate through all pages
for target in lab.list_all_targets():
    print(target["name"])

# Search
results = lab.search_targets("PD-L1")

Create experiment

from adaptyv import lab

result = lab.create_experiment(
    name="My Experiment",
    sequences={
        "clone_1": "MVKVGVNG...",
        "clone_2": "MKVLVAG...",
    },
    target_id="...",  # from targets list
    experiment_type="screening",
)

print(f"Created: {result.experiment_url}")

Get experiment status

from adaptyv import lab

result = lab.get_experiment("experiment-uuid")
print(f"Status: {result.status}")

Confirm experiment

from adaptyv import lab

# Waits for quote, then confirms
result = lab.confirm_experiment("experiment-uuid")
print(f"Confirmed at: {result.confirmed_at}")

Get results

from adaptyv import FoundryClient

client = FoundryClient(api_key="...", base_url="https://foundry-api-public.adaptyvbio.com/api/v1")

# Retrieve results for a completed experiment
results = client.experiments.get_results("experiment-uuid")
for result in results.results:
    print(f"{result.title}: {result.result_type}")

---

Examples

Using the client directly

from adaptyv import FoundryClient

client = FoundryClient(api_key="...", base_url="https://foundry-api-public.adaptyvbio.com/api/v1")

# List experiments
experiments = client.experiments.list()

# Get cost estimate before creating
estimate = client.experiments.cost_estimate({
    "experiment_type": "screening",
    "target_id": "...",
    "sequences": {"seq1": "MVKVG..."},
})

# Get experiment quote
quote = client.experiments.get_quote("experiment-uuid")

# Get invoice
invoice = client.experiments.get_invoice("experiment-uuid")

# List status updates
updates = client.experiments.list_updates("experiment-uuid")

---

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check
mypy src