boltz2-python-client 0.3.3__tar.gz → 0.4.0__tar.gz

{boltz2_python_client-0.3.3 → boltz2_python_client-0.4.0}/PARAMETERS.md

@@ -22,7 +22,7 @@ This document provides a comprehensive reference for all available Boltz-2 API p
 
 #### `polymers` (List[Polymer])
 - **Description**: List of polymers (DNA, RNA, or Protein) to predict
-- **Range**: 1-5 polymers
+- **Range**: 1-12 polymers (v1.5+), 1-5 (v1.3)
 - **Required**: Yes
 - **Example**:
 ```python
@@ -56,7 +56,7 @@ ligands = [
 
 ### `recycling_steps` (int)
 - **Description**: Number of recycling steps for iterative refinement
-- **Range**: 1-6
+- **Range**: 1-10 (v1.5+), 1-6 (v1.3)
 - **Default**: 3
 - **Effect**: Higher values improve accuracy but increase computation time
 - **Recommendations**:
@@ -76,7 +76,7 @@ ligands = [
 
 ### `diffusion_samples` (int)
 - **Description**: Number of independent diffusion samples
-- **Range**: 1-5
+- **Range**: 1-25 (v1.5+), 1-5 (v1.3)
 - **Default**: 1
 - **Effect**: Multiple samples provide diversity and ensemble predictions
 - **Usage**: Use >1 for uncertainty estimation or best-of-N selection
@@ -530,11 +530,11 @@ request = PredictionRequest(
 
 ### Speed vs Quality Trade-offs
 
-| Parameter | Fast | Balanced | High Quality |
-|-----------|------|----------|--------------|
-| recycling_steps | 1-2 | 3-4 | 5-6 |
+| Parameter | Fast | Balanced | High Quality (v1.5+) |
+|-----------|------|----------|----------------------|
+| recycling_steps | 1-2 | 3-4 | 6-10 |
 | sampling_steps | 10-30 | 50-100 | 200-1000 |
-| diffusion_samples | 1 | 1-2 | 3-5 |
+| diffusion_samples | 1 | 1-2 | 5-25 |
 | step_scale | 1.638 | 1.2-2.0 | 0.8-1.5 |
 
 ### Memory Usage
@@ -560,11 +560,11 @@ diffusion_samples=2
 step_scale=1.2
 ```
 
-#### High-Accuracy Research
+#### High-Accuracy Research (v1.5+)
 ```python
-recycling_steps=6
+recycling_steps=10      # Up to 10 in v1.5
 sampling_steps=500
-diffusion_samples=5
+diffusion_samples=25    # Up to 25 in v1.5
 step_scale=1.0
 ```
 
@@ -584,7 +584,7 @@ step_scale=1.0
 try:
     request = PredictionRequest(
         polymers=[],  # Empty list not allowed
-        recycling_steps=10  # Outside range 1-6
+        recycling_steps=15  # Outside range 1-10 (v1.5)
     )
 except ValidationError as e:
     print(f"Validation error: {e}")

{boltz2_python_client-0.3.3/boltz2_python_client.egg-info → boltz2_python_client-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boltz2-python-client
-Version: 0.3.3
+Version: 0.4.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>
@@ -48,6 +48,7 @@ A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure predic
 
 ## 🚀 **Features**
 
+- ✅ **Boltz2 NIM v1.5 Support** - Compatible with the latest NVIDIA Boltz2 NIM
 - ✅ **Full API Coverage** - Complete Boltz-2 API support
 - ✅ **Async & Sync Clients** - Choose your preferred programming style
 - ✅ **Rich CLI Interface** - Beautiful command-line tools with progress bars
@@ -58,8 +59,11 @@ A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure predic
 - ✅ **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
+- ✅ **A3M to Multimer MSA** - Convert ColabFold A3M files to paired multimer format
+- ✅ **Multi-Endpoint Load Balancing** - Distribute predictions across multiple NIMs (default: least-loaded)
+- ✅ **PAE/PDE Matrix Output** - Full Predicted Aligned Error and Distance Error matrices
+- ✅ **PDB Output Format** - Export structures as PDB in addition to mmCIF
+- ✅ **Structural Templates** - Template-guided structure prediction
 - ✅ **Comprehensive Examples** - Ready-to-use code samples
 
 ## 📦 **Installation**
@@ -146,12 +150,19 @@ 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)
+# One-command multimer prediction from A3M files
 boltz2 multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif
 
-# Multi-endpoint multimer prediction
+# With PAE matrix output and PDB format
+boltz2 multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.pdb \
+    --output-format pdb --write-full-pae --save-all
+
+# High-quality prediction with v1.5 limits (up to 10 recycling, 25 diffusion samples)
+boltz2 protein "MKTVRQ..." --recycling-steps 10 --diffusion-samples 25
+
+# Multi-endpoint multimer prediction (default: least-loaded balancing)
 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
+    multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif --save-all
 ```
 
 ### Affinity Prediction
@@ -276,11 +287,12 @@ boltz2 --multi-endpoint \
     multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif --save-all
 ```
 
-**Output files with `--save-all --save-csv`:**
+**Output files with `--save-all --save-csv --write-full-pae`:**
 ```
 output/
-├── complex.cif              # 3D structure (mmCIF)
-├── complex.scores.json      # Confidence scores, pLDDT, pTM, metrics
+├── complex.cif              # 3D structure (mmCIF) or .pdb with --output-format pdb
+├── complex.scores.json      # Confidence scores, pLDDT, pTM, ipTM, metrics
+├── complex.pae.json         # PAE matrix (with --write-full-pae)
 ├── complex_chain_A.csv      # Paired MSA for chain A
 └── complex_chain_B.csv      # Paired MSA for chain B
 ```
@@ -335,21 +347,21 @@ result = quick_screen(
 print(result.get_top_hits(n=5))
 ```
 
-### Multi-Endpoint Virtual Screening (NEW)
+### Multi-Endpoint Virtual Screening
 
 Parallelize screening across multiple Boltz-2 NIM endpoints for better throughput:
 
 ```python
 from boltz2_client import MultiEndpointClient, LoadBalanceStrategy, VirtualScreening
 
-# Configure multiple endpoints
+# Configure multiple endpoints (default strategy: LEAST_LOADED)
 multi_client = MultiEndpointClient(
     endpoints=[
         "http://localhost:8000",
         "http://localhost:8001",
         "http://localhost:8002",
-    ],
-    strategy=LoadBalanceStrategy.LEAST_LOADED
+    ]
+    # strategy=LoadBalanceStrategy.LEAST_LOADED  # This is the default
 )
 
 # Use with virtual screening
@@ -445,10 +457,11 @@ chmod -R 777 $LOCAL_NIM_CACHE
 ```bash
 docker run -it \
     --runtime=nvidia \
+    --shm-size=16G \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.0.0
+    nvcr.io/nim/mit/boltz2:1.5.0
 ```
 
 #### Option B: Use Specific GPU (e.g., GPU 0)
@@ -456,10 +469,11 @@ docker run -it \
 docker run -it \
     --runtime=nvidia \
     --gpus='"device=0"' \
+    --shm-size=16G \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.0.0
+    nvcr.io/nim/mit/boltz2:1.5.0
 ```
 
 ### Step 5: Verify Installation
@@ -583,6 +597,66 @@ result = await client.predict_with_advanced_parameters(
 )
 ```
 
+### Boltz2 NIM v1.5 Features
+
+The client supports all v1.5 parameters and limits:
+
+```python
+from boltz2_client import Boltz2Client, PredictionRequest, Polymer
+
+client = Boltz2Client(base_url="http://localhost:8000")
+
+# High-quality prediction with v1.5 limits
+request = PredictionRequest(
+    polymers=[Polymer(id="A", molecule_type="protein", sequence="MKTVRQ...")],
+    recycling_steps=10,      # Up to 10 (was 6 in v1.3)
+    diffusion_samples=25,    # Up to 25 (was 5 in v1.3)
+    write_full_pae=True,     # Output full PAE matrix
+    write_full_pde=True,     # Output full PDE matrix
+)
+
+result = await client.predict(request)
+
+# Access PAE/PDE matrices
+if result.pae:
+    print(f"PAE shape: {len(result.pae)}x{len(result.pae[0])}x{len(result.pae[0][0])}")
+```
+
+**v1.5 Parameter Limits:**
+| Parameter | v1.3 Limit | v1.5 Limit |
+|-----------|------------|------------|
+| `recycling_steps` | 1-6 | 1-10 |
+| `diffusion_samples` | 1-5 | 1-25 |
+| `polymers` | 5 | 12 |
+| `ligands` | 5 | 20 |
+
+### PAE/PDE Matrix Output
+
+```python
+from boltz2_client import save_pae_matrix, get_pae_summary
+
+# Save PAE matrix to file
+save_pae_matrix(result.pae, "output.pae.json")
+save_pae_matrix(result.pae, "output.pae.npy", format="npy")  # NumPy format
+
+# Get summary statistics
+summary = get_pae_summary(result.pae)
+print(f"Mean PAE: {summary['mean_pae']:.2f}")
+print(f"Quality: {summary['quality']}")  # Very High/High/Medium/Low
+```
+
+### PDB Output Format
+
+```python
+from boltz2_client import convert_cif_to_pdb
+
+# Convert mmCIF to PDB format
+convert_cif_to_pdb("structure.cif", "structure.pdb")
+
+# CLI: Use --output-format pdb
+# boltz2 protein "SEQUENCE" -o output.pdb --output-format pdb
+```
+
 ### 🆕 Affinity Prediction
 Predict binding affinity (IC50/pIC50) for protein-ligand complexes:
 

{boltz2_python_client-0.3.3 → boltz2_python_client-0.4.0}/README.md

@@ -10,6 +10,7 @@ A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure predic
 
 ## 🚀 **Features**
 
+- ✅ **Boltz2 NIM v1.5 Support** - Compatible with the latest NVIDIA Boltz2 NIM
 - ✅ **Full API Coverage** - Complete Boltz-2 API support
 - ✅ **Async & Sync Clients** - Choose your preferred programming style
 - ✅ **Rich CLI Interface** - Beautiful command-line tools with progress bars
@@ -20,8 +21,11 @@ A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure predic
 - ✅ **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
+- ✅ **A3M to Multimer MSA** - Convert ColabFold A3M files to paired multimer format
+- ✅ **Multi-Endpoint Load Balancing** - Distribute predictions across multiple NIMs (default: least-loaded)
+- ✅ **PAE/PDE Matrix Output** - Full Predicted Aligned Error and Distance Error matrices
+- ✅ **PDB Output Format** - Export structures as PDB in addition to mmCIF
+- ✅ **Structural Templates** - Template-guided structure prediction
 - ✅ **Comprehensive Examples** - Ready-to-use code samples
 
 ## 📦 **Installation**
@@ -108,12 +112,19 @@ 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)
+# One-command multimer prediction from A3M files
 boltz2 multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif
 
-# Multi-endpoint multimer prediction
+# With PAE matrix output and PDB format
+boltz2 multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.pdb \
+    --output-format pdb --write-full-pae --save-all
+
+# High-quality prediction with v1.5 limits (up to 10 recycling, 25 diffusion samples)
+boltz2 protein "MKTVRQ..." --recycling-steps 10 --diffusion-samples 25
+
+# Multi-endpoint multimer prediction (default: least-loaded balancing)
 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
+    multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif --save-all
 ```
 
 ### Affinity Prediction
@@ -238,11 +249,12 @@ boltz2 --multi-endpoint \
     multimer-msa chain_A.a3m chain_B.a3m -c A,B -o complex.cif --save-all
 ```
 
-**Output files with `--save-all --save-csv`:**
+**Output files with `--save-all --save-csv --write-full-pae`:**
 ```
 output/
-├── complex.cif              # 3D structure (mmCIF)
-├── complex.scores.json      # Confidence scores, pLDDT, pTM, metrics
+├── complex.cif              # 3D structure (mmCIF) or .pdb with --output-format pdb
+├── complex.scores.json      # Confidence scores, pLDDT, pTM, ipTM, metrics
+├── complex.pae.json         # PAE matrix (with --write-full-pae)
 ├── complex_chain_A.csv      # Paired MSA for chain A
 └── complex_chain_B.csv      # Paired MSA for chain B
 ```
@@ -297,21 +309,21 @@ result = quick_screen(
 print(result.get_top_hits(n=5))
 ```
 
-### Multi-Endpoint Virtual Screening (NEW)
+### Multi-Endpoint Virtual Screening
 
 Parallelize screening across multiple Boltz-2 NIM endpoints for better throughput:
 
 ```python
 from boltz2_client import MultiEndpointClient, LoadBalanceStrategy, VirtualScreening
 
-# Configure multiple endpoints
+# Configure multiple endpoints (default strategy: LEAST_LOADED)
 multi_client = MultiEndpointClient(
     endpoints=[
         "http://localhost:8000",
         "http://localhost:8001",
         "http://localhost:8002",
-    ],
-    strategy=LoadBalanceStrategy.LEAST_LOADED
+    ]
+    # strategy=LoadBalanceStrategy.LEAST_LOADED  # This is the default
 )
 
 # Use with virtual screening
@@ -407,10 +419,11 @@ chmod -R 777 $LOCAL_NIM_CACHE
 ```bash
 docker run -it \
     --runtime=nvidia \
+    --shm-size=16G \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.0.0
+    nvcr.io/nim/mit/boltz2:1.5.0
 ```
 
 #### Option B: Use Specific GPU (e.g., GPU 0)
@@ -418,10 +431,11 @@ docker run -it \
 docker run -it \
     --runtime=nvidia \
     --gpus='"device=0"' \
+    --shm-size=16G \
     -p 8000:8000 \
     -e NGC_API_KEY \
     -v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
-    nvcr.io/nim/mit/boltz2:1.0.0
+    nvcr.io/nim/mit/boltz2:1.5.0
 ```
 
 ### Step 5: Verify Installation
@@ -545,6 +559,66 @@ result = await client.predict_with_advanced_parameters(
 )
 ```
 
+### Boltz2 NIM v1.5 Features
+
+The client supports all v1.5 parameters and limits:
+
+```python
+from boltz2_client import Boltz2Client, PredictionRequest, Polymer
+
+client = Boltz2Client(base_url="http://localhost:8000")
+
+# High-quality prediction with v1.5 limits
+request = PredictionRequest(
+    polymers=[Polymer(id="A", molecule_type="protein", sequence="MKTVRQ...")],
+    recycling_steps=10,      # Up to 10 (was 6 in v1.3)
+    diffusion_samples=25,    # Up to 25 (was 5 in v1.3)
+    write_full_pae=True,     # Output full PAE matrix
+    write_full_pde=True,     # Output full PDE matrix
+)
+
+result = await client.predict(request)
+
+# Access PAE/PDE matrices
+if result.pae:
+    print(f"PAE shape: {len(result.pae)}x{len(result.pae[0])}x{len(result.pae[0][0])}")
+```
+
+**v1.5 Parameter Limits:**
+| Parameter | v1.3 Limit | v1.5 Limit |
+|-----------|------------|------------|
+| `recycling_steps` | 1-6 | 1-10 |
+| `diffusion_samples` | 1-5 | 1-25 |
+| `polymers` | 5 | 12 |
+| `ligands` | 5 | 20 |
+
+### PAE/PDE Matrix Output
+
+```python
+from boltz2_client import save_pae_matrix, get_pae_summary
+
+# Save PAE matrix to file
+save_pae_matrix(result.pae, "output.pae.json")
+save_pae_matrix(result.pae, "output.pae.npy", format="npy")  # NumPy format
+
+# Get summary statistics
+summary = get_pae_summary(result.pae)
+print(f"Mean PAE: {summary['mean_pae']:.2f}")
+print(f"Quality: {summary['quality']}")  # Very High/High/Medium/Low
+```
+
+### PDB Output Format
+
+```python
+from boltz2_client import convert_cif_to_pdb
+
+# Convert mmCIF to PDB format
+convert_cif_to_pdb("structure.cif", "structure.pdb")
+
+# CLI: Use --output-format pdb
+# boltz2 protein "SEQUENCE" -o output.pdb --output-format pdb
+```
+
 ### 🆕 Affinity Prediction
 Predict binding affinity (IC50/pIC50) for protein-ligand complexes:
 

{boltz2_python_client-0.3.3 → boltz2_python_client-0.4.0}/boltz2_client/__init__.py

@@ -26,7 +26,7 @@ Example:
     >>> print(f"Confidence: {result.confidence_scores[0]:.3f}")
 """
 
-__version__ = "0.3.3"
+__version__ = "0.4.0"
 __author__ = "NVIDIA Corporation"
 __email__ = "bionemo-support@nvidia.com"
 
@@ -43,6 +43,8 @@ from .models import (
     AlignmentFormat,
     HealthStatus,
     ServiceMetadata,
+    StructuralTemplate,
+    Modification,
 )
 from .models_affinity import AffinityPrediction
 from .exceptions import (
@@ -81,6 +83,11 @@ from .a3m_to_csv_converter import (
     create_paired_msa_per_chain,
     save_prediction_outputs,
     get_prediction_summary,
+    save_pae_matrix,
+    save_pde_matrix,
+    get_pae_summary,
+    convert_cif_to_pdb,
+    convert_pdb_to_cif,
     ConversionResult,
     GreedyPairingStrategy,
     CompletePairingStrategy,
@@ -130,6 +137,8 @@ __all__ = [
     "HealthStatus",
     "ServiceMetadata",
     "AffinityPrediction",
+    "StructuralTemplate",
+    "Modification",
     
     # Exceptions
     "Boltz2Error",
@@ -167,6 +176,11 @@ __all__ = [
     "create_paired_msa_per_chain",
     "save_prediction_outputs",
     "get_prediction_summary",
+    "save_pae_matrix",
+    "save_pde_matrix",
+    "get_pae_summary",
+    "convert_cif_to_pdb",
+    "convert_pdb_to_cif",
     "ConversionResult",
     "GreedyPairingStrategy",
     "CompletePairingStrategy",