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

{boltz2_python_client-0.2 → boltz2_python_client-0.3.0}/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.0}/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.0}/INSTALL_TESTPYPI.md

@@ -92,8 +92,8 @@ asyncio.run(visualize_prediction())
 
 ### **Package Information**
 
-- **TestPyPI URL:** https://test.pypi.org/project/boltz2-python-client/0.1.10/
-- **Version:** 0.1.10
+- **TestPyPI URL:** https://test.pypi.org/project/boltz2-python-client/0.2.1/
+- **Version:** 0.2.1
 - **Python Requirements:** >=3.8
 
 ### **Features Available**

{boltz2_python_client-0.2 → boltz2_python_client-0.3.0}/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-0.3.0}/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.0
+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,7 @@ 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
 - ✅ **Comprehensive Examples** - Ready-to-use code samples
 
 ## 📦 **Installation**
@@ -87,8 +74,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 .
 ```
 
@@ -122,8 +109,6 @@ async def quick_prediction():
 
 if __name__ == "__main__":
     asyncio.run(quick_prediction())
-```
-
 
 ### CLI Usage
 
@@ -145,6 +130,15 @@ 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
 ```
 
 ### Affinity Prediction
@@ -175,6 +169,40 @@ 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.
+
 ### Virtual Screening
 
 ```python
@@ -197,6 +225,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 +338,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 +349,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
@@ -397,7 +456,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 +499,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 +544,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,6 +594,7 @@ 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
 - **[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
@@ -530,4 +616,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**