boltz2-python-client 0.2__tar.gz → 0.3.2__tar.gz

{boltz2_python_client-0.2 → boltz2_python_client-0.3.2}/ASYNC_GUIDE.md

@@ -271,6 +271,41 @@ async def process_in_chunks(sequences, chunk_size=10):
 
 ## Performance Optimization
 
+### Multi-Endpoint for Maximum Throughput
+
+For the highest throughput, use multiple Boltz-2 endpoints with load balancing:
+
+```python
+from boltz2_client import MultiEndpointClient, LoadBalanceStrategy
+
+# Configure multiple endpoints
+multi_client = MultiEndpointClient(
+    endpoints=[
+        "http://localhost:8000",
+        "http://localhost:8001",
+        "http://localhost:8002",
+    ],
+    strategy=LoadBalanceStrategy.LEAST_LOADED,
+    is_async=True
+)
+
+# Use with async batch processing
+async def multi_endpoint_batch(sequences):
+    tasks = []
+    for seq in sequences:
+        request = PredictionRequest(
+            polymers=[Polymer(id="A", molecule_type="protein", sequence=seq)],
+            recycling_steps=1,
+            sampling_steps=20
+        )
+        tasks.append(multi_client.predict(request))
+    
+    results = await asyncio.gather(*tasks)
+    return results
+```
+
+See [MULTI_ENDPOINT_GUIDE.md](MULTI_ENDPOINT_GUIDE.md) for detailed setup instructions.
+
 ### Optimal Concurrency Settings
 
 ```python
@@ -467,4 +502,9 @@ start = time.time()
 print(f"Total time: {time.time() - start:.2f}s")
 ```
 
-This guide provides a comprehensive foundation for async protein folding with the Boltz-2 Python client. Start with the simple examples and gradually implement more advanced patterns as needed. 
+This guide provides a comprehensive foundation for async protein folding with the Boltz-2 Python client. Start with the simple examples and gradually implement more advanced patterns as needed.
+---
+
+## Disclaimer
+
+This software is provided as-is without warranties of any kind. No guarantees are made regarding the accuracy, reliability, or fitness for any particular purpose. The underlying models and APIs are experimental and subject to change without notice. Users are responsible for validating all results and assessing suitability for their specific use cases.

{boltz2_python_client-0.2 → boltz2_python_client-0.3.2}/COVALENT_COMPLEX_GUIDE.md

@@ -204,4 +204,9 @@ The `boltz2-python-client` package is now fully functional for covalent protein-
 - ✅ Comprehensive error handling and validation
 - ✅ Professional file output and result management
 
-You can now use this package for production covalent complex predictions! 🧪✨ 
+You can now use this package for production covalent complex predictions! 🧪✨
+---
+
+## Disclaimer
+
+This software is provided as-is without warranties of any kind. No guarantees are made regarding the accuracy, reliability, or fitness for any particular purpose. The underlying models and APIs are experimental and subject to change without notice. Users are responsible for validating all results and assessing suitability for their specific use cases.

{boltz2_python_client-0.2 → boltz2_python_client-0.3.2}/PARAMETERS.md

@@ -12,8 +12,9 @@ This document provides a comprehensive reference for all available Boltz-2 API p
 4. [Constraints](#constraints)
 5. [Advanced Parameters](#advanced-parameters)
 6. [MSA Parameters](#msa-parameters)
-7. [Parameter Combinations](#parameter-combinations)
-8. [Usage Examples](#usage-examples)
+7. [Affinity Prediction Parameters](#affinity-prediction-parameters)
+8. [Parameter Combinations](#parameter-combinations)
+9. [Usage Examples](#usage-examples)
 
 ## Core Parameters
 
@@ -235,6 +236,90 @@ polymer = Polymer(
 )
 ```
 
+## Affinity Prediction Parameters
+
+### Ligand-Specific Parameters
+
+#### `predict_affinity` (bool)
+- **Description**: Enable affinity prediction for a specific ligand
+- **Default**: False
+- **Required**: No
+- **Note**: Only ONE ligand per request can have this enabled
+- **Example**:
+```python
+ligand = Ligand(
+    id="LIG",
+    smiles="CC(=O)OC1=CC=CC=C1C(=O)O",
+    predict_affinity=True  # Enable affinity prediction
+)
+```
+
+### Global Affinity Parameters
+
+#### `sampling_steps_affinity` (int)
+- **Description**: Number of sampling steps for affinity prediction
+- **Range**: 10-1000
+- **Default**: 200
+- **Effect**: Higher values may improve accuracy but increase runtime
+- **Recommendations**:
+  - 50-100: Fast testing
+  - 200-300: Production use
+  - 500-1000: High accuracy research
+
+#### `diffusion_samples_affinity` (int)
+- **Description**: Number of diffusion samples for affinity prediction
+- **Range**: 1-10
+- **Default**: 5
+- **Effect**: Higher values provide ensemble predictions and reliability
+- **Recommendations**:
+  - 1-3: Fast predictions
+  - 5-8: Balanced accuracy
+  - 10: Maximum ensemble diversity
+
+#### `affinity_mw_correction` (bool)
+- **Description**: Apply molecular weight correction to affinity predictions
+- **Default**: False
+- **Effect**: Adjusts predictions based on ligand molecular weight
+- **Usage**: Recommended for diverse ligand libraries
+
+### Affinity Response Fields
+
+The response includes an `affinities` dictionary with the following fields for each ligand:
+
+- `affinity_pred_value`: Raw affinity predictions (log scale)
+- `affinity_pic50`: pIC50 values (-log10 of IC50 in M)
+- `affinity_probability_binary`: Binary binding probability (0-1)
+- `model_*_affinity_*`: Individual model predictions for ensemble analysis
+
+### Affinity Usage Example
+
+```python
+from boltz2_client import Boltz2Client, Polymer, Ligand
+
+client = Boltz2Client()
+
+# Define protein and ligand
+protein = Polymer(id="A", molecule_type="protein", sequence="YOUR_SEQUENCE")
+ligand = Ligand(id="LIG", smiles="YOUR_SMILES", predict_affinity=True)
+
+# Predict with affinity
+result = await client.predict_structure(
+    polymers=[protein],
+    ligands=[ligand],
+    sampling_steps_affinity=300,
+    diffusion_samples_affinity=8,
+    affinity_mw_correction=True
+)
+
+# Access results
+if result.affinities and "LIG" in result.affinities:
+    affinity = result.affinities["LIG"]
+    ic50_nm = 10**(-affinity.affinity_pic50[0]) * 1e9
+    print(f"pIC50: {affinity.affinity_pic50[0]:.2f}")
+    print(f"IC50: {ic50_nm:.1f} nM")
+    print(f"Binding probability: {affinity.affinity_probability_binary[0]:.1%}")
+```
+
 ## Parameter Combinations
 
 ### High-Quality Prediction
@@ -551,4 +636,9 @@ For complete CLI documentation, run:
 boltz2 --help
 boltz2 covalent --help
 boltz2 examples
-``` 
+```
+---
+
+## Disclaimer
+
+This software is provided as-is without warranties of any kind. No guarantees are made regarding the accuracy, reliability, or fitness for any particular purpose. The underlying models and APIs are experimental and subject to change without notice. Users are responsible for validating all results and assessing suitability for their specific use cases.

{boltz2_python_client-0.2/boltz2_python_client.egg-info → boltz2_python_client-0.3.2}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.4
 Name: boltz2-python-client
-Version: 0.2
-Summary: Python client for Boltz-2 protein structure prediction API with covalent complex support
-Author: NVIDIA Corporation
-Maintainer: NVIDIA Corporation
+Version: 0.3.2
+Summary: Python client for Boltz-2 protein structure prediction API with covalent complex and multi-endpoint support
+Author-email: NVIDIA Corporation <bionemo-support@nvidia.com>
+Maintainer-email: NVIDIA Corporation <bionemo-support@nvidia.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/NVIDIA/bionemo-examples/tree/add-boltz2-python-client/examples/nims/boltz-2
-Project-URL: Repository, https://github.com/NVIDIA/bionemo-examples/tree/add-boltz2-python-client/examples/nims/boltz-2
+Project-URL: Homepage, https://github.com/NVIDIA/digital-biology-examples/tree/main/examples/nims/boltz-2
+Project-URL: Repository, https://github.com/NVIDIA/digital-biology-examples/tree/main/examples/nims/boltz-2
+Project-URL: Documentation, https://github.com/NVIDIA/digital-biology-examples/tree/main/examples/nims/boltz-2/README.md
+Project-URL: Bug Reports, https://github.com/NVIDIA/digital-biology-examples/issues
 Keywords: protein,structure,prediction,AI,machine learning,bioinformatics,covalent,complex,boltz2
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
@@ -34,22 +36,6 @@ Requires-Dist: PyYAML>=6.0.0
 Requires-Dist: py3Dmol>=2.0.0
 Dynamic: license-file
 
-# Boltz-2 NIM
-
-Boltz-2 NIM is a next-generation structural biology foundation model that shows strong performance for both structure and affinity prediction. Boltz-2 is the first deep learning model to approach the accuracy of free energy perturbation (FEP) methods in predicting binding affinities of small molecules and proteins—achieving strong correlations on benchmarks while being nearly 1000× more computationally efficient.
-
-Boltz-2 NIM can be acceseed at [build.nvidia.com](https://docs.api.nvidia.com/nim/reference/mit-boltz2).
-
-Example notebooks on how to use Boltz-2 NIM endpoint: 
-- [Predicting protein-liagnd covalent complex](./examples/boltz2_nim_protein_ligand_covalent_complex_molstar_visualization.ipynb)
-- [Predicting protein-DNA complex](./examples/boltz2_nim_DNA_Protein_Complex_example_py3Dmol.ipynb)
-
-However, there's an easier way to access Boltz-2 NIM functionalities using the Boltz-2 client:
-- [Boltz-2 client demo](./examples/boltz2_demo.ipynb)
-
-Below is the description of the Boltz-2 client. Enjoy!
-
-
 # Boltz-2 Python Client
 
 Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved.
@@ -71,6 +57,9 @@ A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure predic
 - ✅ **YAML Configuration** - Official Boltz format support
 - ✅ **Affinity Prediction** - Predict binding affinity (IC50) for protein-ligand complexes
 - ✅ **Virtual Screening** - High-level API for drug discovery campaigns
+- ✅ **MSA Search Integration** - GPU-accelerated MSA generation with NVIDIA MSA Search NIM
+- ✅ **A3M to Multimer MSA** - Convert ColabFold A3M files to paired multimer format (NEW)
+- ✅ **Multi-Endpoint Load Balancing** - Distribute predictions across multiple NIMs
 - ✅ **Comprehensive Examples** - Ready-to-use code samples
 
 ## 📦 **Installation**
@@ -87,8 +76,8 @@ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://
 
 ### From Source
 ```bash
-git clone https://github.com/NVIDIA/boltz2-python-client.git
-cd boltz2-python-client
+git clone https://github.com/NVIDIA/digital-biology-examples.git
+cd digital-biology-examples/examples/nims/boltz-2
 pip install -e .
 ```
 
@@ -124,7 +113,6 @@ if __name__ == "__main__":
     asyncio.run(quick_prediction())
 ```
 
-
 ### CLI Usage
 
 ```bash
@@ -145,6 +133,25 @@ boltz2 covalent "SEQUENCE" --ccd U4U --bond A:11:SG:L:C22
 
 # Virtual screening campaign
 boltz2 screen "TARGET_SEQUENCE" compounds.csv -o screening_results/
+
+# MSA search
+boltz2 msa-search "PROTEIN_SEQUENCE" --databases Uniref30_2302 colabfold_envdb_202108 --output msa.a3m
+
+# MSA search + structure prediction
+boltz2 msa-predict "PROTEIN_SEQUENCE" --databases Uniref30_2302 --max-sequences 1000
+
+# MSA search + ligand affinity
+boltz2 msa-ligand "PROTEIN_SEQUENCE" --smiles "LIGAND_SMILES" --predict-affinity
+
+# Convert ColabFold A3M files to paired multimer CSV
+boltz2 convert-msa chain_A.a3m chain_B.a3m -c A,B -o paired.csv
+
+# One-command multimer prediction from A3M files (NEW)
+boltz2 multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif
+
+# Multi-endpoint multimer prediction
+boltz2 --multi-endpoint --base-url "http://gpu1:8000,http://gpu2:8000" \
+    multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif
 ```
 
 ### Affinity Prediction
@@ -175,6 +182,137 @@ if result.affinities and "LIG" in result.affinities:
     print(f"Binding probability: {affinity.affinity_probability_binary[0]:.1%}")
 ```
 
+### MSA Search Integration (NEW)
+
+Integrate GPU-accelerated MSA Search NIM for enhanced protein structure predictions:
+
+```python
+from boltz2_client import Boltz2Client
+
+# Initialize and configure MSA Search
+client = Boltz2Client()
+client.configure_msa_search(
+    msa_endpoint_url="https://health.api.nvidia.com/v1/biology/nvidia/msa-search",
+    api_key="your_nvidia_api_key"  # Or set NVIDIA_API_KEY env var
+)
+
+# One-step MSA search + structure prediction
+result = await client.predict_with_msa_search(
+    sequence="MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
+    databases=["Uniref30_2302", "PDB70_220313"],
+    max_msa_sequences=1000,
+    e_value=0.0001
+)
+
+print(f"Confidence: {result.confidence_scores[0]:.3f}")
+
+# Or just search MSA and save in different formats
+msa_path = await client.search_msa(
+    sequence="YOUR_PROTEIN_SEQUENCE",
+    output_format="a3m",  # Options: a3m, fasta, csv, sto
+    save_path="protein_msa.a3m"
+)
+```
+
+See the [MSA Search Guide](MSA_SEARCH_GUIDE.md) for detailed usage and parameters.
+
+### A3M to Multimer MSA Conversion (NEW)
+
+Convert ColabFold-generated A3M monomer MSA files to paired multimer format for Boltz2:
+
+```python
+from boltz2_client import (
+    Boltz2Client,
+    convert_a3m_to_multimer_csv,
+    create_paired_msa_per_chain,
+    Polymer, PredictionRequest
+)
+
+# Convert A3M files to paired MSA (auto-detects pairing mode)
+result = convert_a3m_to_multimer_csv(
+    a3m_files={'A': 'chain_A.a3m', 'B': 'chain_B.a3m'}
+)
+print(f"Paired {result.num_pairs} sequences")
+
+# Create per-chain MSA structures for Boltz2
+msa_per_chain = create_paired_msa_per_chain(result)
+
+# Create polymers with paired MSA
+protein_A = Polymer(id="A", molecule_type="protein", 
+                    sequence=result.query_sequences['A'],
+                    msa=msa_per_chain['A'])
+protein_B = Polymer(id="B", molecule_type="protein",
+                    sequence=result.query_sequences['B'],
+                    msa=msa_per_chain['B'])
+
+# Predict complex structure
+client = Boltz2Client(base_url="http://localhost:8000")
+response = await client.predict(PredictionRequest(
+    polymers=[protein_A, protein_B],
+    recycling_steps=3,
+    sampling_steps=200
+))
+```
+
+#### CLI One-Command Prediction
+```bash
+# Predict directly from A3M files (converts + predicts in one step)
+boltz2 --base-url http://localhost:8000 multimer-msa \
+    chain_A.a3m chain_B.a3m \
+    -c A,B \
+    -o complex.cif
+
+# Save all outputs: structure, paired CSVs, and confidence scores
+boltz2 --base-url http://localhost:8000 multimer-msa \
+    chain_A.a3m chain_B.a3m \
+    -c A,B \
+    -o complex.cif \
+    --save-csv \    # Save paired CSV files
+    --save-all      # Save scores JSON (confidence, pLDDT, pTM, etc.)
+
+# With multi-endpoint load balancing
+boltz2 --multi-endpoint \
+    --base-url "http://gpu1:8000,http://gpu2:8000,http://gpu3:8000" \
+    multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif --save-all
+```
+
+**Output files with `--save-all --save-csv`:**
+```
+output/
+├── complex.cif              # 3D structure (mmCIF)
+├── complex.scores.json      # Confidence scores, pLDDT, pTM, metrics
+├── complex_chain_A.csv      # Paired MSA for chain A
+└── complex_chain_B.csv      # Paired MSA for chain B
+```
+
+#### Save All Outputs (Python API)
+```python
+from boltz2_client import save_prediction_outputs, get_prediction_summary
+
+# Save all outputs with one function call
+paths = save_prediction_outputs(
+    response=response,
+    output_dir=Path("results"),
+    base_name="my_complex",
+    save_structure=True,   # Save CIF file(s)
+    save_scores=True,      # Save scores JSON
+    save_csv=True,         # Save paired CSVs
+    conversion_result=result  # From convert_a3m_to_multimer_csv
+)
+print(paths)
+# {'structure': Path('results/my_complex.cif'),
+#  'scores': Path('results/my_complex.scores.json'),
+#  'csv_A': Path('results/my_complex_chain_A.csv'),
+#  'csv_B': Path('results/my_complex_chain_B.csv')}
+
+# Get a quick summary of prediction quality
+summary = get_prediction_summary(response)
+print(f"Confidence: {summary['confidence']:.2f}")
+print(f"Quality: {summary['quality_assessment']}")  # Very High/High/Medium/Low
+```
+
+See the [A3M to Multimer MSA Guide](examples/A3M_TO_MULTIMER_MSA.md) for detailed usage.
+
 ### Virtual Screening
 
 ```python
@@ -197,6 +335,37 @@ result = quick_screen(
 print(result.get_top_hits(n=5))
 ```
 
+### Multi-Endpoint Virtual Screening (NEW)
+
+Parallelize screening across multiple Boltz-2 NIM endpoints for better throughput:
+
+```python
+from boltz2_client import MultiEndpointClient, LoadBalanceStrategy, VirtualScreening
+
+# Configure multiple endpoints
+multi_client = MultiEndpointClient(
+    endpoints=[
+        "http://localhost:8000",
+        "http://localhost:8001",
+        "http://localhost:8002",
+    ],
+    strategy=LoadBalanceStrategy.LEAST_LOADED
+)
+
+# Use with virtual screening
+vs = VirtualScreening(client=multi_client)
+result = await vs.screen(
+    target_sequence="YOUR_PROTEIN_SEQUENCE",
+    compound_library=compounds,
+    predict_affinity=True
+)
+
+# View endpoint statistics
+multi_client.print_status()
+```
+
+See [MULTI_ENDPOINT_GUIDE.md](MULTI_ENDPOINT_GUIDE.md) for detailed setup instructions.
+
 ### 3D Visualization
 
 ```python
@@ -279,7 +448,7 @@ docker run -it \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.1.0
+    nvcr.io/nim/mit/boltz2:1.0.0
 ```
 
 #### Option B: Use Specific GPU (e.g., GPU 0)
@@ -290,7 +459,7 @@ docker run -it \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.1.0
+    nvcr.io/nim/mit/boltz2:1.0.0
 ```
 
 ### Step 5: Verify Installation
@@ -361,6 +530,9 @@ The `examples/` directory contains comprehensive examples:
 - **06_yaml_configurations.py** - YAML config files
 - **07_advanced_parameters.py** - Advanced API parameters
 - **08_affinity_prediction.py** - Binding affinity prediction (IC50/pIC50)
+- **15_a3m_to_multimer_csv.py** - A3M to multimer MSA conversion
+- **16_colabfold_a3m_to_multimer.ipynb** - Interactive notebook for multimer MSA (NEW)
+- **A3M_TO_MULTIMER_MSA.md** - Comprehensive guide for A3M conversion (NEW)
 
 ## 🧪 **Supported Prediction Types**
 
@@ -397,7 +569,7 @@ async def batch_predictions():
 # With MSA file
 result = await client.predict_protein_structure(
     sequence="YOUR_SEQUENCE",
-    msa_file="path/to/alignment.a3m"
+    msa_files=[("path/to/alignment.a3m", "a3m")]
 )
 ```
 
@@ -440,6 +612,32 @@ if result.affinities and "LIG" in result.affinities:
     print(f"Binding probability: {affinity.affinity_probability_binary[0]:.3f}")
 ```
 
+#### 🧬 MSA-Guided Affinity Prediction
+Combine MSA search with affinity prediction for improved accuracy:
+
+```python
+# Configure MSA Search
+client.configure_msa_search("http://your-msa-nim:8000")
+
+# Predict with MSA + affinity in one call
+result = await client.predict_ligand_with_msa_search(
+    protein_sequence="YOUR_SEQUENCE",
+    ligand_smiles="CC(=O)OC1=CC=CC=C1C(=O)O",
+    predict_affinity=True,
+    databases=["Uniref30_2302", "PDB70_220313"],
+    max_msa_sequences=1000,
+    sampling_steps_affinity=300
+)
+
+# Or use existing MSA file
+result = await client.predict_protein_ligand_complex(
+    protein_sequence="YOUR_SEQUENCE",
+    ligand_smiles="LIGAND_SMILES",
+    msa_files=[("alignment.a3m", "a3m")],
+    predict_affinity=True
+)
+```
+
 #### CLI Usage
 ```bash
 # Basic affinity prediction
@@ -459,8 +657,8 @@ boltz2 ligand "PROTEIN_SEQUENCE" --ccd Y7W \
 
 ### Setup Development Environment
 ```bash
-git clone https://github.com/NVIDIA/boltz2-python-client.git
-cd boltz2-python-client
+git clone https://github.com/NVIDIA/digital-biology-examples.git
+cd digital-biology-examples/examples/nims/boltz-2
 pip install -e ".[dev]"
 ```
 
@@ -509,10 +707,13 @@ Third-party dependencies are licensed under their respective licenses - see the
 ## 📚 **Documentation**
 
 ### Guides
+- **[MSA Search Guide](MSA_SEARCH_GUIDE.md)** - GPU-accelerated MSA generation with NVIDIA MSA Search NIM
+- **[A3M to Multimer MSA Guide](examples/A3M_TO_MULTIMER_MSA.md)** - Convert ColabFold A3M files to paired multimer format (NEW)
 - **[Affinity Prediction Guide](AFFINITY_PREDICTION_GUIDE.md)** - Comprehensive guide for binding affinity prediction
 - **[YAML Configuration Guide](YAML_GUIDE.md)** - Working with YAML configuration files
 - **[Async Programming Guide](ASYNC_GUIDE.md)** - Best practices for async operations
 - **[Covalent Complex Guide](COVALENT_COMPLEX_GUIDE.md)** - Predicting covalent bonds
+- **[Multi-Endpoint Guide](MULTI_ENDPOINT_GUIDE.md)** - Load balancing across multiple NIMs
 - **[Parameters Guide](PARAMETERS.md)** - Detailed parameter documentation
 
 ## 🔗 **Links**
@@ -530,4 +731,10 @@ Third-party dependencies are licensed under their respective licenses - see the
 
 ---
 
+## Disclaimer
+
+This software is provided as-is without warranties of any kind. No guarantees are made regarding the accuracy, reliability, or fitness for any particular purpose. The underlying models and APIs are experimental and subject to change without notice. Users are responsible for validating all results and assessing suitability for their specific use cases.
+
+---
+
 **Made with ❤️ for the computational biology community**