@bgicli/bgicli 2.1.1 → 2.2.1

package/data/skills/bindcraft/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: bindcraft
+description: >
+  End-to-end binder design using BindCraft hallucination. Use this skill when:
+  (1) Designing protein binders with built-in AF2 validation,
+  (2) Running production-quality binder campaigns,
+  (3) Using different design protocols (fast, default, slow),
+  (4) Need joint backbone and sequence optimization,
+  (5) Want high experimental success rate.
+
+  For backbone-only generation, use rfdiffusion.
+  For QC thresholds, use protein-qc.
+  For tool selection guidance, use binder-design.
+license: MIT
+category: design-tools
+tags: [structure-design, sequence-design, binder, pipeline]
+proteinbase_slug: bindcraft
+proteinbase_url: https://proteinbase.com/design-methods/bindcraft
+biomodals_script: modal_bindcraft.py
+---
+
+# BindCraft Binder Design
+
+## Prerequisites
+
+| Requirement | Minimum | Recommended |
+|-------------|---------|-------------|
+| Python | 3.9+ | 3.10 |
+| CUDA | 11.7+ | 12.0+ |
+| GPU VRAM | 32GB | 48GB (L40S) |
+| RAM | 32GB | 64GB |
+
+## How to run
+
+> **First time?** See [Installation Guide](../../docs/installation.md) to set up Modal and biomodals.
+
+### Option 1: Modal (recommended)
+```bash
+cd biomodals
+modal run modal_bindcraft.py \
+  --target-pdb target.pdb \
+  --target-chain A \
+  --binder-lengths 70-100 \
+  --hotspots "A45,A67,A89" \
+  --num-designs 50
+```
+
+**GPU**: L40S (48GB) | **Timeout**: 3600s default
+
+### Option 2: Local installation
+```bash
+git clone https://github.com/martinpacesa/BindCraft.git
+cd BindCraft
+pip install -r requirements.txt
+
+python bindcraft.py \
+  --target target.pdb \
+  --target_chains A \
+  --binder_lengths 70-100 \
+  --hotspots A45,A67,A89 \
+  --num_designs 50
+```
+
+## Key parameters
+
+| Parameter | Default | Range | Description |
+|-----------|---------|-------|-------------|
+| `--target-pdb` | required | path | Target structure |
+| `--target-chain` | required | A-Z | Target chain(s) |
+| `--binder-lengths` | 70-100 | 40-150 | Length range |
+| `--hotspots` | None | residues | Target hotspots |
+| `--num-designs` | 50 | 1-500 | Number of designs |
+| `--protocol` | default | fast/default/slow | Quality vs speed |
+
+## Protocols
+
+| Protocol | Speed | Quality | Use Case |
+|----------|-------|---------|----------|
+| fast | Fast | Lower | Initial screening |
+| default | Medium | Good | Standard campaigns |
+| slow | Slow | High | Final production |
+
+## Output format
+
+```
+output/
+├── design_0/
+│   ├── binder.pdb         # Final design
+│   ├── complex.pdb        # Binder + target
+│   ├── metrics.json       # QC scores
+│   └── trajectory/        # Optimization trajectory
+├── design_1/
+│   └── ...
+└── summary.csv            # All metrics
+```
+
+### Metrics Output
+```json
+{
+  "plddt": 0.89,
+  "ptm": 0.78,
+  "iptm": 0.62,
+  "pae": 8.5,
+  "rmsd": 1.2,
+  "sequence": "MKTAYIAK..."
+}
+```
+
+## Sample output
+
+### Successful run
+```
+$ modal run modal_bindcraft.py --target-pdb target.pdb --num-designs 50
+[INFO] Loading BindCraft model...
+[INFO] Target: target.pdb (chain A)
+[INFO] Hotspots: A45, A67, A89
+[INFO] Protocol: default
+[INFO] Generating 50 designs...
+
+Design 1/50:
+  Length: 78 AA
+  pLDDT: 0.89, ipTM: 0.62
+  Saved: output/design_0/
+
+Design 50/50:
+  Length: 85 AA
+  pLDDT: 0.86, ipTM: 0.58
+  Saved: output/design_49/
+
+[INFO] Campaign complete. Summary: output/summary.csv
+Pass rate: 32/50 (64%) with ipTM > 0.5
+```
+
+**What good output looks like:**
+- pLDDT: > 0.85 for most designs
+- ipTM: > 0.5 for passing designs
+- Pass rate: 30-70% depending on target
+- Diverse sequences across designs
+
+## Decision tree
+
+```
+Should I use BindCraft?
+│
+├─ What type of design?
+│  ├─ Production-quality binders → BindCraft ✓
+│  ├─ High diversity exploration → RFdiffusion
+│  └─ All-atom precision → BoltzGen
+│
+├─ What matters most?
+│  ├─ Experimental success rate → BindCraft ✓
+│  ├─ Speed / diversity → RFdiffusion + ProteinMPNN
+│  ├─ AF2 gradient optimization → ColabDesign
+│  └─ All-atom control → BoltzGen
+│
+└─ Compute resources?
+   ├─ Have L40S/A100 → BindCraft ✓
+   └─ Only A10G → RFdiffusion + ProteinMPNN
+```
+
+## Typical performance
+
+| Campaign Size | Time (L40S) | Cost (Modal) | Notes |
+|---------------|-------------|--------------|-------|
+| 50 designs | 2-4h | ~$15 | Quick campaign |
+| 100 designs | 4-8h | ~$30 | Standard |
+| 200 designs | 8-16h | ~$60 | Large campaign |
+
+**Expected pass rate**: 30-70% with ipTM > 0.5 (target-dependent).
+
+---
+
+## Verify
+
+```bash
+find output -name "binder.pdb" | wc -l  # Should match num_designs
+```
+
+---
+
+## Troubleshooting
+
+**Low ipTM scores**: Check hotspot selection, increase designs
+**Slow convergence**: Use fast protocol for screening
+**OOM errors**: Reduce num_models, use L40S GPU
+**Poor diversity**: Lower sampling_temp, run multiple seeds
+
+### Error interpretation
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `RuntimeError: CUDA out of memory` | Large target or long binder | Use L40S/A100, reduce binder length |
+| `ValueError: no hotspots` | Hotspots not found | Check residue numbering |
+| `TimeoutError` | Design taking too long | Use fast protocol |
+
+---
+
+**Next**: Rank by `ipsae` → experimental validation.

package/data/skills/binder-design/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: binder-design
+description: >
+  Guidance for choosing the right protein binder design tool.
+  Use this skill when: (1) Deciding between BoltzGen, BindCraft, or RFdiffusion,
+  (2) Planning a binder design campaign,
+  (3) Understanding trade-offs between different approaches,
+  (4) Selecting tools for specific target types.
+
+  For specific tool parameters, use the individual tool skills
+  (boltzgen, bindcraft, rfdiffusion, etc.).
+license: MIT
+category: orchestration
+tags: [guidance, tool-selection, workflow]
+---
+
+# Binder Design Tool Selection
+
+## Decision tree
+
+```
+De novo binder design?
+│
+├─ Standard target → BoltzGen (recommended)
+│   All-atom output (no separate ProteinMPNN step needed)
+│   Better for ligand/small molecule binding
+│   Single-step design (backbone + sequence + side chains)
+│
+├─ Need diversity/exploration → RFdiffusion + ProteinMPNN
+│   Maximum backbone diversity
+│   Two-step: backbone then sequence
+│
+├─ Integrated validation → BindCraft
+│   Built-in AF2 validation
+│   End-to-end pipeline
+│
+├─ Ligand binding → BoltzGen ✓
+│   All-atom diffusion handles ligand context
+│
+├─ Peptide/nanobody → Germinal
+│   VHH/nanobody design
+│   Germline-aware optimization
+│
+└─ Antibody/Nanobody
+    +-- VHH design --> germinal skill
+```
+
+## Tool comparison
+
+| Tool | Strengths | Weaknesses | Best For |
+|------|-----------|------------|----------|
+| BoltzGen | All-atom, single-step, ligand-aware | Higher GPU requirement | Standard (recommended) |
+| BindCraft | End-to-end, built-in AF2 validation | Less diverse | Production campaigns |
+| RFdiffusion | High diversity, fast | Requires ProteinMPNN | Exploration, diversity |
+| Germinal | Nanobody/VHH design | Specialized | Antibody optimization |
+
+## Recommended Pipeline: BoltzGen → Chai → QC
+
+BoltzGen provides all-atom design with built-in side-chain packing:
+
+```
+Target → BoltzGen → Validate → Filter
+ (pdb)  (all-atom)   (chai)     (qc)
+```
+
+### 1. Target preparation
+```bash
+# Fetch structure from PDB
+# Use pdb skill for guidance
+```
+- Trim to binding region + 10A buffer
+- Remove waters and ligands
+- Renumber chains if needed
+
+### 2. Hotspot selection
+- Choose 3-6 exposed residues
+- Prefer charged/aromatic residues
+- Cluster spatially (within 10-15A)
+
+### 3. Design with BoltzGen (Recommended)
+
+First, create a YAML config file (e.g., `binder.yaml`):
+```yaml
+entities:
+  - protein:
+      id: B
+      sequence: 70..100
+
+  - file:
+      path: target.cif
+      include:
+        - chain:
+            id: A
+      binding_types:
+        - chain:
+            id: A
+            binding: 45,67,89
+```
+
+Then run:
+```bash
+modal run modal_boltzgen.py \
+  --input-yaml binder.yaml \
+  --protocol protein-anything \
+  --num-designs 50
+```
+
+**Why BoltzGen?**
+- All-atom output (no separate ProteinMPNN step needed)
+- Better for ligand/small molecule binding
+- Single-step design (backbone + sequence + side chains)
+
+### 4. Alternative: RFdiffusion Pipeline
+For maximum diversity or when backbone-only is preferred:
+```bash
+# Step 1: Backbone generation
+modal run modal_rfdiffusion.py \
+  --pdb target.pdb \
+  --contigs "A1-150/0 70-100" \
+  --hotspot "A45,A67,A89" \
+  --num-designs 500
+
+# Step 2: Sequence design
+modal run modal_ligandmpnn.py \
+  --pdb-path backbone.pdb \
+  --num-seq-per-target 16 \
+  --sampling-temp 0.1
+```
+
+### 5. Validation
+```bash
+modal run modal_chai1.py \
+  --input-faa sequences.fasta \
+  --out-dir predictions/
+```
+
+### 6. Filtering
+Apply standard thresholds:
+- pLDDT > 0.80
+- ipTM > 0.50
+- PAE_interface < 10
+- scRMSD < 2.0 A
+
+See protein-qc skill for details.
+
+## Number of designs
+
+| Stage | Count | Purpose |
+|-------|-------|---------|
+| Backbone generation | 500-1000 | Diversity |
+| Sequences per backbone | 8-16 | Sequence space |
+| AF2 predictions | All | Validation |
+| After filtering | 50-200 | Candidates |
+| Experimental testing | 10-50 | Final selection |
+
+## Common mistakes
+
+### Wrong hotspots
+- Using buried residues
+- Too many hotspots (over-constrain)
+- Wrong chain/residue numbers
+
+### Insufficient diversity
+- Too few designs generated
+- Low temperature in ProteinMPNN
+- Not exploring multiple backbones
+
+### Poor target preparation
+- Including full protein instead of binding region
+- Missing important structural features
+- Wrong protonation states
+
+## Timeline guide
+
+| Step | Compute Time |
+|------|--------------|
+| RFdiffusion (500 designs) | 2-4 hours |
+| ProteinMPNN (8000 sequences) | 1-2 hours |
+| AF2 prediction (8000 sequences) | 12-24 hours |
+| Filtering and analysis | 1-2 hours |
+
+Total: 1-2 days of compute

package/data/skills/binding-characterization/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: binding-characterization
+description: >
+  Guidance for SPR and BLI binding characterization experiments. Use when:
+  (1) Planning binding kinetics experiments,
+  (2) Troubleshooting poor/no binding signal,
+  (3) Interpreting kinetic data artifacts,
+  (4) Choosing between SPR vs BLI platforms.
+license: MIT
+category: experimental
+tags: [binding, spr, bli, validation]
+---
+
+# Binding Characterization: SPR and BLI
+
+## SPR vs BLI Decision Matrix
+
+| Factor | Choose SPR | Choose BLI |
+|--------|------------|------------|
+| **Sensitivity** | Small molecules, fragments (<500 Da) | Large complexes, antibodies |
+| **Throughput** | Low-medium (serial) | High (96-well parallel) |
+| **Sample purity** | Required (clogs fluidics) | Tolerates crude lysates |
+| **Kinetic resolution** | Higher (better for fast kinetics) | Lower |
+| **Mass transport** | More sensitive (may distort kon) | Less sensitive |
+| **Maintenance** | High (fluidics system) | Low (dip-and-read) |
+| **Sample consumption** | Higher (continuous flow) | Lower |
+| **Cost per experiment** | Lower chip cost, higher run cost | Higher tip cost, lower run cost |
+
+## Key differences
+
+### SPR (Surface Plasmon Resonance)
+- **Mechanism**: Detects refractive index changes at gold surface
+- **Surface**: Gold chip with dextran matrix (CM5, CM7, etc.)
+- **Flow**: Continuous microfluidics
+- **Best for**: Small molecules, high-affinity, precise kon/koff
+
+### BLI (Biolayer Interferometry)
+- **Mechanism**: Measures optical interference pattern shift
+- **Surface**: Fiber optic biosensor tips (SA, Ni-NTA, AHC)
+- **Flow**: Dip-and-read (no microfluidics)
+- **Best for**: High-throughput, crude samples, antibody screening
+
+---
+
+## Troubleshooting: Why BLI works but SPR doesn't
+
+| Cause | Mechanism | Solution |
+|-------|-----------|----------|
+| **Hydrophobic CDRs** | Adsorb to SPR gold/dextran surface | Add 0.05% Tween-20, use CM7 chip with longer dextran |
+| **Aggregation** | Mass transport artifacts in SPR fluidics | Filter sample (0.22μm), reduce ligand density |
+| **High instability** | Degrades during continuous flow | Shorter cycle time, add stabilizers (trehalose 5%) |
+| **Charge mismatch** | Nonspecific binding to charged dextran | Adjust buffer pH ±1 from pI, add BSA 1mg/mL |
+| **Slow dissociation** | Long regeneration needed (damages ligand) | Use BLI (disposable tips) |
+
+### Why SPR works but BLI doesn't
+
+| Cause | Mechanism | Solution |
+|-------|-----------|----------|
+| **Small analyte** | BLI less sensitive for <10 kDa | Use SPR with appropriate chip |
+| **Weak affinity (KD >10μM)** | Fast dissociation in BLI dip | Increase analyte concentration |
+| **Low expression** | Not enough signal | Increase biosensor loading |
+
+---
+
+## Mass transport considerations
+
+Mass transport limitation occurs when analyte cannot diffuse to the surface fast enough to maintain equilibrium. This distorts kinetic parameters.
+
+### Symptoms
+- Observed kon appears slower than true kon
+- Linear association phase (instead of exponential)
+- kon varies with ligand density
+- Rmax varies with flow rate
+
+### When mass transport matters
+- **High-affinity interactions** (kon >10^6 M^-1s^-1)
+- **High ligand density** (>500 RU)
+- **Slow flow rates** (<30 μL/min in SPR)
+- **Large analytes** (slow diffusion)
+
+### Mitigation strategies
+
+| Strategy | SPR | BLI |
+|----------|-----|-----|
+| Reduce ligand density | <200 RU for high-affinity | <0.5 nm shift loading |
+| Increase flow rate | 50-100 μL/min | Increase shake speed (1000 rpm) |
+| Use oriented immobilization | His-tag capture | Biotinylated ligand |
+| Include in fitting | Mass transport model (kt) | Usually less critical |
+
+---
+
+## Nonspecific binding mitigation
+
+### Buffer additives (ranked by effectiveness)
+
+| Additive | Concentration | Mechanism | Best For |
+|----------|---------------|-----------|----------|
+| BSA | 0.5-1 mg/mL | Blocks hydrophobic sites | General use |
+| Tween-20 | 0.02-0.05% | Prevents surface adsorption | Hydrophobic analytes |
+| Trehalose | 1-5% | Stabilizes + blocks | Unstable proteins |
+| Sucrose | 5% | BLI-specific blocker | BLI tips |
+| Carboxymethyl dextran | 1 mg/mL | Competitive blocking | SPR with charged proteins |
+| NaCl | 150-500 mM | Reduces ionic interactions | Charged proteins |
+
+### pH optimization
+- Keep buffer pH at least 1 unit away from analyte pI
+- pI near 7: Use pH 6.0 or 8.0 buffer
+- Acidic proteins (pI <5): Use neutral or basic buffer
+- Basic proteins (pI >9): Use slightly acidic buffer
+
+### Reference subtraction
+**Always include**:
+- Blank reference channel (no ligand)
+- Buffer-only injections
+- Non-specific binding controls
+
+---
+
+## Regeneration conditions
+
+### SPR regeneration scouting (try in order)
+
+| Condition | Targets | Caution |
+|-----------|---------|---------|
+| 10 mM Glycine pH 2.0-2.5 | Most protein-protein | May denature ligand |
+| 10 mM Glycine pH 1.5 | Strong interactions | Harsh, limit exposure |
+| 1-2 M NaCl | Ionic interactions | Mild, try first |
+| 10 mM NaOH | Very stable ligands | Can hydrolyze proteins |
+| 10 mM Glycine pH 9-10 | Acid-stable proteins | Can aggregate |
+| 10 mM EDTA | His-tag, metal-dependent | Strips Ni-NTA |
+| 4 M MgCl2 | Hydrophobic interactions | Check ligand stability |
+
+### Regeneration protocol
+1. Start with mildest condition (high salt)
+2. Test 30s contact time
+3. Verify complete dissociation (return to baseline)
+4. Verify retained ligand activity (repeat binding)
+5. Use shortest effective contact time
+
+### BLI tips
+- Tips are often disposable (no regeneration needed)
+- For reuse: Same conditions as SPR, but shorter exposure
+- Anti-His tips: 10 mM Glycine pH 1.5, 30s
+- Streptavidin tips: Generally not regenerable
+
+---
+
+## Common artifacts and solutions
+
+### Biphasic binding
+**Symptoms**: Two-rate association or dissociation
+**Causes**:
+- Sample heterogeneity (aggregates)
+- Ligand heterogeneity (multiple conformations)
+- Avidity effects (bivalent analyte)
+
+**Solutions**:
+- Filter/centrifuge sample
+- Use monovalent Fab fragments
+- Reduce ligand density
+- Fit to heterogeneous model
+
+### Negative dissociation
+**Symptoms**: Signal increases during dissociation phase
+**Causes**:
+- Ligand leaching from surface
+- Analyte aggregation on surface
+- Reference channel drift
+
+**Solutions**:
+- Use capture antibody instead of direct immobilization
+- Increase buffer stringency
+- Better reference subtraction
+
+### Hook effect
+**Symptoms**: Signal decreases at high analyte concentrations
+**Causes**:
+- Surface saturation + rebinding suppression
+- Crowding effects
+
+**Solutions**:
+- Reduce analyte concentration range
+- Reduce ligand density
+- Use smaller analyte fragments
+
+---
+
+## Kinetic data quality checklist
+
+### Before analysis
+- [ ] Reference-subtracted properly
+- [ ] Buffer injection shows flat baseline
+- [ ] Rmax consistent across concentrations
+- [ ] No systematic drift during association
+- [ ] Complete regeneration (return to baseline)
+- [ ] Duplicate/triplicate injections consistent
+
+### Fitting quality
+- [ ] Residuals randomly distributed (no systematic deviation)
+- [ ] Chi² < 10% of Rmax (or < 1 RU² for low signals)
+- [ ] kon and koff errors < 20% of values
+- [ ] KD from kinetics matches equilibrium KD (within 3-fold)
+- [ ] Fitted Rmax reasonable (close to theoretical)
+
+### Red flags
+- kon approaching mass transport limit (>10^7 M^-1s^-1)
+- koff faster than data acquisition (< 0.01 s^-1 requires faster sampling)
+- Rmax >> theoretical maximum (aggregation or avidity)
+- Large difference between kinetic and equilibrium KD
+
+---
+
+## References
+
+### Platform comparisons
+- [BLI vs SPR Comparison - Sartorius](https://www.sartorius.hr/en/news/blog/bli-vs-spr-choosing-the-ideal-method-for-analyzing-biomolecular-interactions/)
+- [BLI vs SPR - Nicoya](https://nicoyalife.com/blog/biolayer-interferometry-vs-surface-plasmon-resonance/)
+
+### SPR protocols
+- [SPR Guidelines - van der Merwe, Oxford](https://www.path.ox.ac.uk/wp-content/uploads/2023/09/SPR-guidelines-1.pdf)
+- [SPR Experiment Guide - Duke DHVI](https://dhvi.duke.edu/sites/default/files/2022-08/SPR%20Experiment%20Guide%20v1.3.pdf)
+
+### Troubleshooting
+- [4 Ways to Reduce NSB in SPR - Nicoya](https://nicoyalife.com/blog/4-ways-reduce-non-specific-binding-spr/)
+- [3 Ways to Limit Mass Transfer Effects - Nicoya](https://nicoyalife.com/blog/3-ways-to-limit-mass-transfer-effects/)
+- [Suppressing NSB in BLI - ACS Omega](https://pubs.acs.org/doi/10.1021/acsomega.1c05659)
+
+### Regeneration
+- [SPR Regeneration - SPRpages](https://www.sprpages.nl/kinetics/regeneration)
+- [Mastering Regeneration - Nicoya](https://nicoyalife.com/blog/regeneration-buffer-spr-experiment/)
+
+### Mass transport
+- [Mass Transport Limitation in SPR - PMC](https://pmc.ncbi.nlm.nih.gov/articles/PMC4134667/)
+- [Mass-Transfer Kinetics - SPRpages](https://www.sprpages.nl/data-fitting/kinetic-models/mass-transfer)