# 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.
[](https://badge.fury.io/py/boltz2-python-client)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
A comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure prediction service. This package provides both synchronous and asynchronous interfaces, a rich CLI, and built-in 3D visualization capabilities.
## 🚀 **Features**
- ✅ **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
- ✅ **3D Visualization** - Built-in py3Dmol integration for structure viewing
- ✅ **Flexible Endpoints** - Support for both local and NVIDIA hosted services
- ✅ **Type Safety** - Full Pydantic model validation
- ✅ **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
- ✅ **Comprehensive Examples** - Ready-to-use code samples
## 📦 **Installation**
### From PyPI (Recommended)
```bash
pip install boltz2-python-client
```
### From TestPyPI (Latest Development)
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ boltz2-python-client
```
### From Source
```bash
git clone https://github.com/NVIDIA/boltz2-python-client.git
cd boltz2-python-client
pip install -e .
```
## 🎯 **Quick Start**
### Python API
```python
import asyncio
from boltz2_client import Boltz2Client
async def quick_prediction():
client = Boltz2Client(base_url="http://localhost:8000")
seq = "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
# --- BASIC (no MSA) --------------------------------------------
basic = await client.predict_protein_structure(sequence=seq)
print("basic confidence", basic.confidence_scores[0])
# --- MSA-GUIDED --------------------------------------------------
msa_path = "msa-kras-g12c_combined.a3m" # any *.a3m/*.sto/*.fasta file
msa = [(msa_path, "a3m")]
msa_res = await client.predict_protein_structure(
sequence=seq,
msa_files=msa, # NEW helper will auto-convert ➜ nested-dict
sampling_steps=50,
recycling_steps=3,
)
print("msa confidence", msa_res.confidence_scores[0])
if __name__ == "__main__":
asyncio.run(quick_prediction())
```
### CLI Usage
```bash
# Health check
boltz2 health
# Protein structure prediction
boltz2 protein "MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG"
# Protein-ligand complex
boltz2 ligand "PROTEIN_SEQUENCE" --smiles "CC(=O)OC1=CC=CC=C1C(=O)O"
# Protein-ligand with affinity prediction
boltz2 ligand "PROTEIN_SEQUENCE" --smiles "CC(=O)OC1=CC=CC=C1C(=O)O" --predict-affinity
# Covalent complex with bond constraints
boltz2 covalent "SEQUENCE" --ccd U4U --bond A:11:SG:L:C22
# Virtual screening campaign
boltz2 screen "TARGET_SEQUENCE" compounds.csv -o screening_results/
```
### Affinity Prediction
```python
from boltz2_client import Boltz2Client, Polymer, Ligand, PredictionRequest
client = Boltz2Client()
# Create protein and ligand with affinity prediction
protein = Polymer(id="A", molecule_type="protein", sequence="YOUR_SEQUENCE")
ligand = Ligand(id="LIG", smiles="CC(=O)OC1=CC=CC=C1C(=O)O", predict_affinity=True)
request = PredictionRequest(
polymers=[protein],
ligands=[ligand],
sampling_steps_affinity=200, # Affinity-specific parameters
diffusion_samples_affinity=5
)
result = await client.predict(request)
# Access affinity results
if result.affinities and "LIG" in result.affinities:
affinity = result.affinities["LIG"]
print(f"pIC50: {affinity.affinity_pic50[0]:.2f}")
print(f"IC50: {10**(-affinity.affinity_pic50[0])*1e9:.1f} nM")
print(f"Binding probability: {affinity.affinity_probability_binary[0]:.1%}")
```
### Virtual Screening
```python
from boltz2_client import quick_screen
# Minimal virtual screening
compounds = [
{"name": "Aspirin", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"},
{"name": "Ibuprofen", "smiles": "CC(C)CC1=CC=C(C=C1)C(C)C(=O)O"}
]
result = quick_screen(
target_sequence="YOUR_PROTEIN_SEQUENCE",
compounds=compounds,
target_name="My Target",
output_dir="screening_results"
)
# Show top hits
print(result.get_top_hits(n=5))
```
### 3D Visualization
```python
import py3Dmol
from boltz2_client import Boltz2Client
client = Boltz2Client()
result = await client.predict_protein_structure(sequence="YOUR_SEQUENCE", recycling_steps=6, sampling_steps=50 )
# Create 3D visualization
view = py3Dmol.view(width=800, height=600)
view.addModel(result.structures[0].structure, 'cif')
view.setStyle({'cartoon': {'color': 'spectrum'}})
view.zoomTo()
view.show()
```
## 🔧 **Configuration**
### Local Endpoint (Default)
```python
client = Boltz2Client(base_url="http://localhost:8000")
```
### NVIDIA Hosted Endpoint
```python
client = Boltz2Client(
base_url="https://health.api.nvidia.com",
api_key="your_api_key",
endpoint_type="nvidia_hosted"
)
```
### Environment Variables
```bash
export NVIDIA_API_KEY="your_api_key"
export BOLTZ2_BASE_URL="http://localhost:8000"
```
## 🐳 **Local Deployment Setup**
To run Boltz-2 locally using NVIDIA's NIM (NVIDIA Inference Microservice) container, follow these steps:
### Prerequisites
- **NVIDIA GPU** with sufficient VRAM (recommended: 24GB+)
- **Docker** with NVIDIA Container Runtime
- **NGC Account** with API key
### Step 1: Generate NGC API Key
1. Go to [NGC (NVIDIA GPU Cloud)](https://ngc.nvidia.com/)
2. Sign in or create an account
3. Navigate to **Setup → Generate API Key**
4. Copy your personal API key
### Step 2: Docker Login
```bash
# Login to NVIDIA Container Registry
docker login nvcr.io
Username: $oauthtoken
Password: <PASTE_API_KEY_HERE>
```
### Step 3: Set Up Environment
```bash
# Export your NGC API key
export NGC_API_KEY=<your_personal_NGC_key>
# Create local cache directory (recommended for model reuse)
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p $LOCAL_NIM_CACHE
chmod -R 777 $LOCAL_NIM_CACHE
```
### Step 4: Run Boltz-2 NIM Container
#### Option A: Use All Available GPUs (Default)
```bash
docker run -it \
--runtime=nvidia \
-p 8000:8000 \
-e NGC_API_KEY \
-v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
nvcr.io/nim/mit/boltz2:1.1.0
```
#### Option B: Use Specific GPU (e.g., GPU 0)
```bash
docker run -it \
--runtime=nvidia \
--gpus='"device=0"' \
-p 8000:8000 \
-e NGC_API_KEY \
-v "$LOCAL_NIM_CACHE":/opt/nim/.cache \
nvcr.io/nim/mit/boltz2:1.1.0
```
### Step 5: Verify Installation
Once the container is running, test the service:
```bash
# Health check
curl http://localhost:8000/v1/health/live
# Or using the Python client
python -c "
import asyncio
from boltz2_client import Boltz2Client
async def test():
client = Boltz2Client(base_url='http://localhost:8000')
health = await client.health_check()
print(f'Service status: {health.status}')
asyncio.run(test())
"
```
### 🚨 **Important Notes**
- **First Run**: The container will automatically download models (~several GB), which may take time
- **Cache Directory**: Using `LOCAL_NIM_CACHE` saves bandwidth and time for subsequent runs
- **GPU Memory**: Ensure sufficient GPU memory for your prediction workloads
- **Port 8000**: Make sure port 8000 is available and not blocked by firewall
- **Network**: Container needs internet access for initial model downloads
### 🔧 **Troubleshooting**
**Container fails to start:**
```bash
# Check GPU availability
nvidia-smi
# Check Docker NVIDIA runtime
docker run --rm --runtime=nvidia nvidia/cuda:11.0-base nvidia-smi
```
**Permission issues:**
```bash
# Fix cache directory permissions
sudo chown -R $USER:$USER $LOCAL_NIM_CACHE
chmod -R 755 $LOCAL_NIM_CACHE
```
**Memory issues:**
```bash
# Monitor GPU memory usage
watch -n 1 nvidia-smi
# Use specific GPU with more memory
docker run --gpus='"device=1"' ... # Use GPU 1 instead
```
## 📚 **Examples**
The `examples/` directory contains comprehensive examples:
- **01_basic_protein_folding.py** - Simple protein structure prediction
- **02_protein_structure_prediction_with_msa.py** - MSA-guided predictions with comparison
- **03_protein_ligand_complex.py** - Protein-ligand complexes
- **04_covalent_bonding.py** - Covalent bond constraints
- **05_dna_protein_complex.py** - DNA-protein interactions
- **06_yaml_configurations.py** - YAML config files
- **07_advanced_parameters.py** - Advanced API parameters
- **08_affinity_prediction.py** - Binding affinity prediction (IC50/pIC50)
## 🧪 **Supported Prediction Types**
| Type | Description | CLI Command | Python Method |
|------|-------------|-------------|---------------|
| **Protein** | Single protein folding | `protein` | `predict_protein_structure()` |
| **Ligand Complex** | Protein-ligand binding | `ligand` | `predict_protein_ligand_complex()` |
| **Covalent Complex** | Covalent bonds | `covalent` | `predict_covalent_complex()` |
| **DNA-Protein** | Nucleic acid complexes | `dna-protein` | `predict_dna_protein_complex()` |
| **Advanced** | Custom parameters | `advanced` | `predict_with_advanced_parameters()` |
| **YAML** | Configuration files | `yaml` | `predict_from_yaml_config()` |
## 🔬 **Advanced Features**
### Batch Processing
```python
from boltz2_client import Boltz2Client
import asyncio
async def batch_predictions():
client = Boltz2Client()
sequences = ["SEQ1", "SEQ2", "SEQ3"]
# Process multiple sequences concurrently
tasks = [client.predict_protein_structure(seq) for seq in sequences]
results = await asyncio.gather(*tasks)
for i, result in enumerate(results):
print(f"Sequence {i+1}: Confidence {result.confidence:.3f}")
```
### MSA-Guided Predictions
```python
# With MSA file
result = await client.predict_protein_structure(
sequence="YOUR_SEQUENCE",
msa_file="path/to/alignment.a3m"
)
```
### Custom Parameters
```python
result = await client.predict_with_advanced_parameters(
polymers=[{"id": "A", "sequence": "SEQUENCE"}],
recycling_steps=3,
sampling_steps=200,
diffusion_samples=1
)
```
### 🆕 Affinity Prediction
Predict binding affinity (IC50/pIC50) for protein-ligand complexes:
```python
from boltz2_client import Boltz2Client, Polymer, Ligand, PredictionRequest
# Create protein and ligand
protein = Polymer(id="A", molecule_type="protein", sequence="YOUR_SEQUENCE")
ligand = Ligand(id="LIG", smiles="CC(=O)OC1=CC=CC=C1C(=O)O", predict_affinity=True)
# Create request with affinity parameters
request = PredictionRequest(
polymers=[protein],
ligands=[ligand],
sampling_steps_affinity=200, # Default: 200
diffusion_samples_affinity=5, # Default: 5
affinity_mw_correction=False # Default: False
)
# Predict structure and affinity
result = await client.predict(request)
# Access affinity results
if result.affinities and "LIG" in result.affinities:
affinity = result.affinities["LIG"]
print(f"pIC50: {affinity.affinity_pic50[0]:.3f}")
print(f"Binding probability: {affinity.affinity_probability_binary[0]:.3f}")
```
#### CLI Usage
```bash
# Basic affinity prediction
boltz2 ligand "PROTEIN_SEQUENCE" --smiles "LIGAND_SMILES" --predict-affinity
# With custom parameters
boltz2 ligand "PROTEIN_SEQUENCE" --ccd Y7W \
--predict-affinity \
--sampling-steps-affinity 100 \
--diffusion-samples-affinity 3 \
--affinity-mw-correction
```
**Note:** Only ONE ligand per request can have affinity prediction enabled.
## 🛠 **Development**
### Setup Development Environment
```bash
git clone https://github.com/NVIDIA/boltz2-python-client.git
cd boltz2-python-client
pip install -e ".[dev]"
```
### Run Tests
```bash
pytest tests/
```
### Code Formatting
```bash
black boltz2_client/
isort boltz2_client/
```
### Type Checking
```bash
mypy boltz2_client/
```
## 📋 **Requirements**
- **Python**: 3.8+
- **Dependencies**:
- `httpx>=0.24.0` - HTTP client
- `pydantic>=2.0.0` - Data validation
- `rich>=13.0.0` - CLI formatting
- `aiofiles>=23.0.0` - Async file operations
- `click>=8.0.0` - CLI framework
- `PyYAML>=6.0.0` - YAML support
- `py3Dmol>=2.0.0` - 3D visualization
## 🤝 **Contributing**
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Merge Request
## 📄 **License**
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Third-party dependencies are licensed under their respective licenses - see the [licenses/](licenses/) directory for details.
## 📚 **Documentation**
### Guides
- **[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
- **[Parameters Guide](PARAMETERS.md)** - Detailed parameter documentation
## 🔗 **Links**
- **TestPyPI**: https://test.pypi.org/project/boltz2-python-client/
- **NVIDIA BioNeMo**: https://www.nvidia.com/en-us/clara/bionemo/
- **Boltz-2 Paper**: [Link to Boltz-2 paper](https://cdn.prod.website-files.com/68404fd075dba49e58331ad9/6842ee1285b9af247ac5a122_boltz2.pdf)
## 🏆 **Acknowledgments**
- NVIDIA BioNeMo Team for the Boltz-2 service
- Contributors and testers
- Open source community
---
**Made with ❤️ for the computational biology community**
Raw data
{
"_id": null,
"home_page": null,
"name": "boltz2-python-client",
"maintainer": "NVIDIA Corporation",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "protein, structure, prediction, AI, machine learning, bioinformatics, covalent, complex, boltz2",
"author": "NVIDIA Corporation",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/61/6e/a4cae04bbff44611e84262ad755e22a373ac1211df3472bd39c2f8154660/boltz2_python_client-0.2.tar.gz",
"platform": null,
"description": "# Boltz-2 NIM\n\nBoltz-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\u2014achieving strong correlations on benchmarks while being nearly 1000\u00d7 more computationally efficient.\n\nBoltz-2 NIM can be acceseed at [build.nvidia.com](https://docs.api.nvidia.com/nim/reference/mit-boltz2).\n\nExample notebooks on how to use Boltz-2 NIM endpoint: \n- [Predicting protein-liagnd covalent complex](./examples/boltz2_nim_protein_ligand_covalent_complex_molstar_visualization.ipynb)\n- [Predicting protein-DNA complex](./examples/boltz2_nim_DNA_Protein_Complex_example_py3Dmol.ipynb)\n\nHowever, there's an easier way to access Boltz-2 NIM functionalities using the Boltz-2 client:\n- [Boltz-2 client demo](./examples/boltz2_demo.ipynb)\n\nBelow is the description of the Boltz-2 client. Enjoy!\n\n\n# Boltz-2 Python Client\n\nCopyright (c) 2025, NVIDIA CORPORATION. All rights reserved.\n\n[](https://badge.fury.io/py/boltz2-python-client)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\nA comprehensive Python client for NVIDIA's Boltz-2 biomolecular structure prediction service. This package provides both synchronous and asynchronous interfaces, a rich CLI, and built-in 3D visualization capabilities.\n\n## \ud83d\ude80 **Features**\n\n- \u2705 **Full API Coverage** - Complete Boltz-2 API support\n- \u2705 **Async & Sync Clients** - Choose your preferred programming style\n- \u2705 **Rich CLI Interface** - Beautiful command-line tools with progress bars\n- \u2705 **3D Visualization** - Built-in py3Dmol integration for structure viewing\n- \u2705 **Flexible Endpoints** - Support for both local and NVIDIA hosted services\n- \u2705 **Type Safety** - Full Pydantic model validation\n- \u2705 **YAML Configuration** - Official Boltz format support\n- \u2705 **Affinity Prediction** - Predict binding affinity (IC50) for protein-ligand complexes\n- \u2705 **Virtual Screening** - High-level API for drug discovery campaigns\n- \u2705 **Comprehensive Examples** - Ready-to-use code samples\n\n## \ud83d\udce6 **Installation**\n\n### From PyPI (Recommended)\n```bash\npip install boltz2-python-client\n```\n\n### From TestPyPI (Latest Development)\n```bash\npip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ boltz2-python-client\n```\n\n### From Source\n```bash\ngit clone https://github.com/NVIDIA/boltz2-python-client.git\ncd boltz2-python-client\npip install -e .\n```\n\n## \ud83c\udfaf **Quick Start**\n\n### Python API\n\n```python\nimport asyncio\nfrom boltz2_client import Boltz2Client\n\nasync def quick_prediction():\n client = Boltz2Client(base_url=\"http://localhost:8000\")\n seq = \"MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG\"\n\n # --- BASIC (no MSA) --------------------------------------------\n basic = await client.predict_protein_structure(sequence=seq)\n print(\"basic confidence\", basic.confidence_scores[0])\n\n # --- MSA-GUIDED --------------------------------------------------\n msa_path = \"msa-kras-g12c_combined.a3m\" # any *.a3m/*.sto/*.fasta file\n msa = [(msa_path, \"a3m\")]\n\n msa_res = await client.predict_protein_structure(\n sequence=seq,\n msa_files=msa, # NEW helper will auto-convert \u279c nested-dict\n sampling_steps=50,\n recycling_steps=3,\n )\n print(\"msa confidence\", msa_res.confidence_scores[0])\n\nif __name__ == \"__main__\":\n asyncio.run(quick_prediction())\n```\n\n\n### CLI Usage\n\n```bash\n# Health check\nboltz2 health\n\n# Protein structure prediction\nboltz2 protein \"MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG\"\n\n# Protein-ligand complex\nboltz2 ligand \"PROTEIN_SEQUENCE\" --smiles \"CC(=O)OC1=CC=CC=C1C(=O)O\"\n\n# Protein-ligand with affinity prediction\nboltz2 ligand \"PROTEIN_SEQUENCE\" --smiles \"CC(=O)OC1=CC=CC=C1C(=O)O\" --predict-affinity\n\n# Covalent complex with bond constraints\nboltz2 covalent \"SEQUENCE\" --ccd U4U --bond A:11:SG:L:C22\n\n# Virtual screening campaign\nboltz2 screen \"TARGET_SEQUENCE\" compounds.csv -o screening_results/\n```\n\n### Affinity Prediction\n\n```python\nfrom boltz2_client import Boltz2Client, Polymer, Ligand, PredictionRequest\n\nclient = Boltz2Client()\n\n# Create protein and ligand with affinity prediction\nprotein = Polymer(id=\"A\", molecule_type=\"protein\", sequence=\"YOUR_SEQUENCE\")\nligand = Ligand(id=\"LIG\", smiles=\"CC(=O)OC1=CC=CC=C1C(=O)O\", predict_affinity=True)\n\nrequest = PredictionRequest(\n polymers=[protein],\n ligands=[ligand],\n sampling_steps_affinity=200, # Affinity-specific parameters\n diffusion_samples_affinity=5\n)\n\nresult = await client.predict(request)\n\n# Access affinity results\nif result.affinities and \"LIG\" in result.affinities:\n affinity = result.affinities[\"LIG\"]\n print(f\"pIC50: {affinity.affinity_pic50[0]:.2f}\")\n print(f\"IC50: {10**(-affinity.affinity_pic50[0])*1e9:.1f} nM\")\n print(f\"Binding probability: {affinity.affinity_probability_binary[0]:.1%}\")\n```\n\n### Virtual Screening\n\n```python\nfrom boltz2_client import quick_screen\n\n# Minimal virtual screening\ncompounds = [\n {\"name\": \"Aspirin\", \"smiles\": \"CC(=O)OC1=CC=CC=C1C(=O)O\"},\n {\"name\": \"Ibuprofen\", \"smiles\": \"CC(C)CC1=CC=C(C=C1)C(C)C(=O)O\"}\n]\n\nresult = quick_screen(\n target_sequence=\"YOUR_PROTEIN_SEQUENCE\",\n compounds=compounds,\n target_name=\"My Target\",\n output_dir=\"screening_results\"\n)\n\n# Show top hits\nprint(result.get_top_hits(n=5))\n```\n\n### 3D Visualization\n\n```python\nimport py3Dmol\nfrom boltz2_client import Boltz2Client\n\nclient = Boltz2Client()\nresult = await client.predict_protein_structure(sequence=\"YOUR_SEQUENCE\", recycling_steps=6, sampling_steps=50 )\n\n# Create 3D visualization\nview = py3Dmol.view(width=800, height=600)\nview.addModel(result.structures[0].structure, 'cif')\nview.setStyle({'cartoon': {'color': 'spectrum'}})\nview.zoomTo()\nview.show()\n```\n\n## \ud83d\udd27 **Configuration**\n\n### Local Endpoint (Default)\n```python\nclient = Boltz2Client(base_url=\"http://localhost:8000\")\n```\n\n### NVIDIA Hosted Endpoint\n```python\nclient = Boltz2Client(\n base_url=\"https://health.api.nvidia.com\",\n api_key=\"your_api_key\",\n endpoint_type=\"nvidia_hosted\"\n)\n```\n\n### Environment Variables\n```bash\nexport NVIDIA_API_KEY=\"your_api_key\"\nexport BOLTZ2_BASE_URL=\"http://localhost:8000\"\n```\n\n## \ud83d\udc33 **Local Deployment Setup**\n\nTo run Boltz-2 locally using NVIDIA's NIM (NVIDIA Inference Microservice) container, follow these steps:\n\n### Prerequisites\n- **NVIDIA GPU** with sufficient VRAM (recommended: 24GB+)\n- **Docker** with NVIDIA Container Runtime\n- **NGC Account** with API key\n\n### Step 1: Generate NGC API Key\n1. Go to [NGC (NVIDIA GPU Cloud)](https://ngc.nvidia.com/)\n2. Sign in or create an account\n3. Navigate to **Setup \u2192 Generate API Key**\n4. Copy your personal API key\n\n### Step 2: Docker Login\n```bash\n# Login to NVIDIA Container Registry\ndocker login nvcr.io\nUsername: $oauthtoken\nPassword: <PASTE_API_KEY_HERE>\n```\n\n### Step 3: Set Up Environment\n```bash\n# Export your NGC API key\nexport NGC_API_KEY=<your_personal_NGC_key>\n\n# Create local cache directory (recommended for model reuse)\nexport LOCAL_NIM_CACHE=~/.cache/nim\nmkdir -p $LOCAL_NIM_CACHE\nchmod -R 777 $LOCAL_NIM_CACHE\n```\n\n### Step 4: Run Boltz-2 NIM Container\n\n#### Option A: Use All Available GPUs (Default)\n```bash\ndocker run -it \\\n --runtime=nvidia \\\n -p 8000:8000 \\\n -e NGC_API_KEY \\\n -v \"$LOCAL_NIM_CACHE\":/opt/nim/.cache \\\n nvcr.io/nim/mit/boltz2:1.1.0\n```\n\n#### Option B: Use Specific GPU (e.g., GPU 0)\n```bash\ndocker run -it \\\n --runtime=nvidia \\\n --gpus='\"device=0\"' \\\n -p 8000:8000 \\\n -e NGC_API_KEY \\\n -v \"$LOCAL_NIM_CACHE\":/opt/nim/.cache \\\n nvcr.io/nim/mit/boltz2:1.1.0\n```\n\n### Step 5: Verify Installation\nOnce the container is running, test the service:\n\n```bash\n# Health check\ncurl http://localhost:8000/v1/health/live\n\n# Or using the Python client\npython -c \"\nimport asyncio\nfrom boltz2_client import Boltz2Client\n\nasync def test():\n client = Boltz2Client(base_url='http://localhost:8000')\n health = await client.health_check()\n print(f'Service status: {health.status}')\n\nasyncio.run(test())\n\"\n```\n\n### \ud83d\udea8 **Important Notes**\n\n- **First Run**: The container will automatically download models (~several GB), which may take time\n- **Cache Directory**: Using `LOCAL_NIM_CACHE` saves bandwidth and time for subsequent runs\n- **GPU Memory**: Ensure sufficient GPU memory for your prediction workloads\n- **Port 8000**: Make sure port 8000 is available and not blocked by firewall\n- **Network**: Container needs internet access for initial model downloads\n\n### \ud83d\udd27 **Troubleshooting**\n\n**Container fails to start:**\n```bash\n# Check GPU availability\nnvidia-smi\n\n# Check Docker NVIDIA runtime\ndocker run --rm --runtime=nvidia nvidia/cuda:11.0-base nvidia-smi\n```\n\n**Permission issues:**\n```bash\n# Fix cache directory permissions\nsudo chown -R $USER:$USER $LOCAL_NIM_CACHE\nchmod -R 755 $LOCAL_NIM_CACHE\n```\n\n**Memory issues:**\n```bash\n# Monitor GPU memory usage\nwatch -n 1 nvidia-smi\n\n# Use specific GPU with more memory\ndocker run --gpus='\"device=1\"' ... # Use GPU 1 instead\n```\n\n## \ud83d\udcda **Examples**\n\nThe `examples/` directory contains comprehensive examples:\n\n- **01_basic_protein_folding.py** - Simple protein structure prediction\n- **02_protein_structure_prediction_with_msa.py** - MSA-guided predictions with comparison\n- **03_protein_ligand_complex.py** - Protein-ligand complexes\n- **04_covalent_bonding.py** - Covalent bond constraints\n- **05_dna_protein_complex.py** - DNA-protein interactions\n- **06_yaml_configurations.py** - YAML config files\n- **07_advanced_parameters.py** - Advanced API parameters\n- **08_affinity_prediction.py** - Binding affinity prediction (IC50/pIC50)\n\n## \ud83e\uddea **Supported Prediction Types**\n\n| Type | Description | CLI Command | Python Method |\n|------|-------------|-------------|---------------|\n| **Protein** | Single protein folding | `protein` | `predict_protein_structure()` |\n| **Ligand Complex** | Protein-ligand binding | `ligand` | `predict_protein_ligand_complex()` |\n| **Covalent Complex** | Covalent bonds | `covalent` | `predict_covalent_complex()` |\n| **DNA-Protein** | Nucleic acid complexes | `dna-protein` | `predict_dna_protein_complex()` |\n| **Advanced** | Custom parameters | `advanced` | `predict_with_advanced_parameters()` |\n| **YAML** | Configuration files | `yaml` | `predict_from_yaml_config()` |\n\n## \ud83d\udd2c **Advanced Features**\n\n### Batch Processing\n```python\nfrom boltz2_client import Boltz2Client\nimport asyncio\n\nasync def batch_predictions():\n client = Boltz2Client()\n sequences = [\"SEQ1\", \"SEQ2\", \"SEQ3\"]\n \n # Process multiple sequences concurrently\n tasks = [client.predict_protein_structure(seq) for seq in sequences]\n results = await asyncio.gather(*tasks)\n \n for i, result in enumerate(results):\n print(f\"Sequence {i+1}: Confidence {result.confidence:.3f}\")\n```\n\n### MSA-Guided Predictions\n```python\n# With MSA file\nresult = await client.predict_protein_structure(\n sequence=\"YOUR_SEQUENCE\",\n msa_file=\"path/to/alignment.a3m\"\n)\n```\n\n### Custom Parameters\n```python\nresult = await client.predict_with_advanced_parameters(\n polymers=[{\"id\": \"A\", \"sequence\": \"SEQUENCE\"}],\n recycling_steps=3,\n sampling_steps=200,\n diffusion_samples=1\n)\n```\n\n### \ud83c\udd95 Affinity Prediction\nPredict binding affinity (IC50/pIC50) for protein-ligand complexes:\n\n```python\nfrom boltz2_client import Boltz2Client, Polymer, Ligand, PredictionRequest\n\n# Create protein and ligand\nprotein = Polymer(id=\"A\", molecule_type=\"protein\", sequence=\"YOUR_SEQUENCE\")\nligand = Ligand(id=\"LIG\", smiles=\"CC(=O)OC1=CC=CC=C1C(=O)O\", predict_affinity=True)\n\n# Create request with affinity parameters\nrequest = PredictionRequest(\n polymers=[protein],\n ligands=[ligand],\n sampling_steps_affinity=200, # Default: 200\n diffusion_samples_affinity=5, # Default: 5\n affinity_mw_correction=False # Default: False\n)\n\n# Predict structure and affinity\nresult = await client.predict(request)\n\n# Access affinity results\nif result.affinities and \"LIG\" in result.affinities:\n affinity = result.affinities[\"LIG\"]\n print(f\"pIC50: {affinity.affinity_pic50[0]:.3f}\")\n print(f\"Binding probability: {affinity.affinity_probability_binary[0]:.3f}\")\n```\n\n#### CLI Usage\n```bash\n# Basic affinity prediction\nboltz2 ligand \"PROTEIN_SEQUENCE\" --smiles \"LIGAND_SMILES\" --predict-affinity\n\n# With custom parameters\nboltz2 ligand \"PROTEIN_SEQUENCE\" --ccd Y7W \\\n --predict-affinity \\\n --sampling-steps-affinity 100 \\\n --diffusion-samples-affinity 3 \\\n --affinity-mw-correction\n```\n\n**Note:** Only ONE ligand per request can have affinity prediction enabled.\n\n## \ud83d\udee0 **Development**\n\n### Setup Development Environment\n```bash\ngit clone https://github.com/NVIDIA/boltz2-python-client.git\ncd boltz2-python-client\npip install -e \".[dev]\"\n```\n\n### Run Tests\n```bash\npytest tests/\n```\n\n### Code Formatting\n```bash\nblack boltz2_client/\nisort boltz2_client/\n```\n\n### Type Checking\n```bash\nmypy boltz2_client/\n```\n\n## \ud83d\udccb **Requirements**\n\n- **Python**: 3.8+\n- **Dependencies**:\n - `httpx>=0.24.0` - HTTP client\n - `pydantic>=2.0.0` - Data validation\n - `rich>=13.0.0` - CLI formatting\n - `aiofiles>=23.0.0` - Async file operations\n - `click>=8.0.0` - CLI framework\n - `PyYAML>=6.0.0` - YAML support\n - `py3Dmol>=2.0.0` - 3D visualization\n\n## \ud83e\udd1d **Contributing**\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Merge Request\n\n## \ud83d\udcc4 **License**\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\nThird-party dependencies are licensed under their respective licenses - see the [licenses/](licenses/) directory for details.\n\n## \ud83d\udcda **Documentation**\n\n### Guides\n- **[Affinity Prediction Guide](AFFINITY_PREDICTION_GUIDE.md)** - Comprehensive guide for binding affinity prediction\n- **[YAML Configuration Guide](YAML_GUIDE.md)** - Working with YAML configuration files\n- **[Async Programming Guide](ASYNC_GUIDE.md)** - Best practices for async operations\n- **[Covalent Complex Guide](COVALENT_COMPLEX_GUIDE.md)** - Predicting covalent bonds\n- **[Parameters Guide](PARAMETERS.md)** - Detailed parameter documentation\n\n## \ud83d\udd17 **Links**\n\n- **TestPyPI**: https://test.pypi.org/project/boltz2-python-client/\n- **NVIDIA BioNeMo**: https://www.nvidia.com/en-us/clara/bionemo/\n- **Boltz-2 Paper**: [Link to Boltz-2 paper](https://cdn.prod.website-files.com/68404fd075dba49e58331ad9/6842ee1285b9af247ac5a122_boltz2.pdf)\n\n\n## \ud83c\udfc6 **Acknowledgments**\n\n- NVIDIA BioNeMo Team for the Boltz-2 service\n- Contributors and testers\n- Open source community\n\n---\n\n**Made with \u2764\ufe0f for the computational biology community** \n",
"bugtrack_url": null,
"license": null,
"summary": "Python client for Boltz-2 protein structure prediction API with covalent complex support",
"version": "0.2",
"project_urls": {
"Homepage": "https://github.com/NVIDIA/bionemo-examples/tree/add-boltz2-python-client/examples/nims/boltz-2",
"Repository": "https://github.com/NVIDIA/bionemo-examples/tree/add-boltz2-python-client/examples/nims/boltz-2"
},
"split_keywords": [
"protein",
" structure",
" prediction",
" ai",
" machine learning",
" bioinformatics",
" covalent",
" complex",
" boltz2"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2a669b42b771318c66e45c9d19a3aeb2621aee13feeee35199a69c4f10a09cbd",
"md5": "d4ab14dceb6683ed58e99a67aeb59772",
"sha256": "09a50232fdd2a4616ea570769f17ff1c1ca3b6fc4cbd871e15ef3c1e08d52e4b"
},
"downloads": -1,
"filename": "boltz2_python_client-0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4ab14dceb6683ed58e99a67aeb59772",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43217,
"upload_time": "2025-08-04T22:06:21",
"upload_time_iso_8601": "2025-08-04T22:06:21.913470Z",
"url": "https://files.pythonhosted.org/packages/2a/66/9b42b771318c66e45c9d19a3aeb2621aee13feeee35199a69c4f10a09cbd/boltz2_python_client-0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "616ea4cae04bbff44611e84262ad755e22a373ac1211df3472bd39c2f8154660",
"md5": "632d5f81f619532c13bd06d6341bad49",
"sha256": "8d74813fd29c7186607b015119cc359a8c821edd8ef48e9d345e23cc97f8cdb1"
},
"downloads": -1,
"filename": "boltz2_python_client-0.2.tar.gz",
"has_sig": false,
"md5_digest": "632d5f81f619532c13bd06d6341bad49",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 121517,
"upload_time": "2025-08-04T22:06:23",
"upload_time_iso_8601": "2025-08-04T22:06:23.643484Z",
"url": "https://files.pythonhosted.org/packages/61/6e/a4cae04bbff44611e84262ad755e22a373ac1211df3472bd39c2f8154660/boltz2_python_client-0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 22:06:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NVIDIA",
"github_project": "bionemo-examples",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "boltz2-python-client"
}
JSON
