boltz2-python-client 0.5.1__tar.gz → 0.6.0__tar.gz

boltz2_python_client-0.6.0/CHANGELOG.md

@@ -0,0 +1,233 @@
+# 0.6.0 — 2026-09-11
+
+- Target NIM 1.9.0: diffusion concurrency and affinity embeddings.
+- Correct PAE/PDE documentation to server-side NPZ artifacts.
+- Reject unknown/malformed request fields; accept protein X residues.
+- Fix YAML affinity conversion and missing-MSA handling.
+- Bound hosted polling, preserve HTTP errors, choose hosted URL automatically.
+- Save complete responses, all scores, and affinity embeddings.
+- Refresh notebooks, deployment instructions, examples and release validation.
+- Consolidate seven notebooks into five numbered workflows, fold A3M pairing
+  into protein complexes, and move the SageMaker connection example into docs.
+  Show actual NIM/client versions, restore the mature barstar sequence, correct
+  DNA strand complementarity, and validate supplied MSA query sequences.
+- Require Python 3.10+; make visualization an optional notebook extra.
+- Forward NIM parameters through async/sync multi-endpoint methods.
+- Return a nonzero CLI status when compound screening fails; report unsupported hosted readiness/metadata calls explicitly.
+- Consolidate duplicate examples and guides; validate actual notebook kernels, viewers, Python methods and Bash CLI workflows.
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.5.2.post1] - 2026-02-24
+
+PEP 440 post-release patch on top of `0.5.2`. **No public API changes**;
+fixes a long-standing packaging defect that has been present since
+`0.5.0` (and was carried into `0.5.2` unchanged). Users on a clean
+environment should upgrade to `0.5.2.post1`; users who already have
+`pandas` installed will see no behavior difference.
+
+### Fixed — packaging
+- **`import boltz2_client` now works on a clean install.** Previously
+  `boltz2_client/virtual_screening.py` did `import pandas as pd` at
+  module top, but `pandas` is only declared in the `[dev]` extra (not a
+  runtime dependency), so any clean `pip install boltz2-python-client`
+  followed by `import boltz2_client` raised
+  `ModuleNotFoundError: No module named 'pandas'`. The pandas import is
+  now deferred into the four methods that actually need it
+  (`CompoundLibrary.from_csv`, `VirtualScreeningResult.to_dataframe`,
+  `VirtualScreeningResult.get_top_hits`,
+  `VirtualScreeningResult.get_statistics_by_group`); calling any of those
+  methods still requires pandas, but importing the package, the CLI,
+  and every other code path no longer does. Callers who use the virtual
+  screening DataFrame helpers should install with
+  `pip install "boltz2-python-client[dev]"` or add `pandas` to their
+  own environment.
+- A `from __future__ import annotations` was added to
+  `virtual_screening.py` so the `pd.DataFrame` return-type annotations
+  on those methods are evaluated lazily and do not require `pandas` at
+  import time. Static type checkers and IDEs continue to resolve the
+  annotations via a `TYPE_CHECKING` block.
+
+## [0.5.2] - 2026-02-24
+
+### Fixed — `MultiEndpointClient` reliability
+- **No longer cascades into "All endpoints failed" after a single endpoint glitch.**
+  `failed_requests` is now reset on every successful call across all
+  `predict_*` methods (`predict`, `predict_sync`, `predict_protein_structure`,
+  `predict_protein_ligand_complex`, `predict_covalent_complex`,
+  `predict_dna_protein_complex`, `predict_with_advanced_parameters`,
+  `predict_from_yaml_config`, `predict_from_yaml_file`, and the
+  corresponding `*_sync` variants). Previously a recovered endpoint could
+  remain marked unhealthy indefinitely after three transient failures.
+- **`_select_endpoint()` now honours the per-request `attempted_endpoints`
+  set.** The `LEAST_LOADED` and `RANDOM` strategies could otherwise re-pick
+  the same dead endpoint repeatedly inside a single dispatch loop, wasting
+  retries and (on `LEAST_LOADED`) starving healthy endpoints. Round-robin
+  also now skips already-attempted endpoints fairly without resetting the
+  global rotation counter.
+- **`health_check_sync()` now normalises `HealthStatus` to a boolean.**
+  Previously it stored the entire `HealthStatus` object on
+  `EndpointStatus.is_healthy`, which is always truthy and broke the sync
+  recovery + status-table paths.
+- **Background health-check loop runs an immediate probe at startup.**
+  Initial unreachability is now detected without waiting a full
+  `health_check_interval` (default 60 s).
+- **Synchronous `__exit__` no longer crashes when no event loop is running.**
+  `with MultiEndpointClient(...)` is now safe in plain synchronous code.
+
+### Fixed — CLI
+- `boltz2 msa-search`, `boltz2 msa-predict`, and `boltz2 msa-ligand` now
+  exit with a non-zero status when the underlying call fails (previously
+  they printed the error and exited cleanly, masking failures in pipelines).
+- `boltz2 screen` now reports a clear error if client initialization fails
+  or if `--pocket-residues` is malformed, instead of crashing with a stack
+  trace before the progress UI starts.
+- Removed a redundant local `import json` inside
+  `boltz2 multimer-msa --save-all`; the module-level import is used.
+
+### Fixed — virtual screening
+- `VirtualScreening` no longer raises `IndexError` when a prediction
+  response comes back with empty `structures`, `confidence_scores`, or
+  affinity score lists; missing fields are reported as `None` and the
+  campaign continues.
+
+### Fixed — async client
+- `Boltz2Client._sagemaker_predict` now uses `asyncio.get_running_loop()`
+  instead of the deprecated `asyncio.get_event_loop()` (silences the
+  Python 3.10+ `DeprecationWarning` and avoids a future-version hard
+  error).
+
+### Added
+- **`boltz2 --version` / `boltz2 -V`** prints the installed package
+  version (previously the CLI had no version flag).
+
+### Removed
+- Dead `_HAS_VISUALIZATION` / `_HAS_ANALYSIS` optional-import scaffolding
+  in `boltz2_client/__init__.py` referencing modules that have never
+  shipped. The package public surface is unchanged: no name was ever
+  successfully exported from those blocks.
+
+### Docs
+- Updated the README tagline to accurately describe what ships in the
+  package (multi-endpoint load balancing + notebook examples that
+  visualize structures with `py3Dmol` and Molstar) instead of claiming a
+  non-existent "built-in 3D visualization" module.
+
+### Tests
+- Added `tests/test_multi_endpoint_reliability.py` with 11 regression
+  tests pinning each of the fixes above. Each test fails on 0.5.1 and
+  passes on 0.5.2; the full suite (excluding live-endpoint tests) is now
+  134 passing.
+
+## [0.5.1] - 2026-04-07
+
+### Fixed
+- CLI `metadata` command now shows a clear error for SageMaker endpoints instead of a cryptic `NoneType` error
+- SageMaker endpoint exception handling cleanup in CLI
+
+## [0.5.0] - 2026-04-07
+
+### Added
+- AWS SageMaker endpoint support (`EndpointType.SAGEMAKER`, CLI `--endpoint-type sagemaker`, `--sagemaker-endpoint-name`, `--sagemaker-region`)
+
+### Changed
+- **PocketConstraint API** now uses `Contact` objects (binder + contacts)
+- **Parameter ranges:** `recycling_steps` 1–10, `diffusion_samples` 1–25
+- **`write_full_pde`** support for full predicted distance error matrix output
+- **`Ligand.id`** is optional
+- Compatibility updates for **Boltz-2 NIM v1.6.0**
+
+### Fixed
+- Comprehensive test suite fixes and live endpoint tests
+
+## [0.4.0] - 2025-11-01
+
+### Added
+- A3M to multimer MSA conversion utilities, `multimer-msa` and `convert-msa` CLI commands
+- Example script `13_a3m_to_multimer_csv.py` and guides (`docs/a3m_to_multimer_msa.md`)
+- Multimer notebooks (`01_multimer_prediction.ipynb`, `03_colabfold_a3m_to_multimer.ipynb`) and related example scripts
+- `08_affinity_prediction_simple.py` as the maintained affinity example (with `kinase_y7w_affinity.json`)
+
+### Changed
+- Multi-endpoint client default load-balancing strategy documented as **least-loaded**; expanded multi-endpoint coverage across prediction APIs
+- README and guides updated for v1.5 NIM parameter limits (recycling/diffusion), PAE/PDE output, and PDB export
+
+### Documentation
+- Multi-endpoint virtual screening guide and examples (`comprehensive_multi_endpoint_demo.py`, `multi_endpoint_screening.py`)
+
+## [0.3.0] - 2025-09-11
+
+### Added
+- **GPU-accelerated MSA Search NIM Integration**:
+  - New `MSASearchClient` for direct MSA Search NIM interaction
+  - `MSAFormatConverter` for A3M, FASTA, and Stockholm format support
+  - `MSASearchIntegration` for Boltz-2 workflow integration
+- **New Client Methods**:
+  - `configure_msa_search()` - Configure MSA Search NIM endpoint
+  - `search_msa()` - Standalone MSA search
+  - `predict_with_msa_search()` - Integrated MSA + structure prediction
+  - `predict_ligand_with_msa_search()` - MSA + ligand + affinity prediction
+  - `batch_msa_search()` - Batch processing for multiple sequences
+- **CLI Commands**:
+  - `boltz2 msa-search` - Search and save MSA alignments
+  - `boltz2 msa-predict` - Combined MSA search + structure prediction
+  - `boltz2 msa-ligand` - MSA-guided ligand affinity prediction
+  - `--msa-file` option for existing MSA files
+- **Examples**:
+  - `10_msa_search_integration.py` - Comprehensive MSA integration demo
+  - `11_msa_search_large_protein.py` - Large protein optimization
+  - `12_msa_affinity_prediction.py` - MSA-guided affinity prediction
+- **Documentation**:
+  - New MSA Search Guide with complete usage examples
+  - Updated Affinity Prediction Guide with MSA-guided section
+  - Enhanced README with MSA integration examples
+
+### Fixed
+- Parameter naming consistency: `max_hits` → `max_msa_sequences`, `e_value_threshold` → `e_value`
+- MSA file handling in `predict_protein_structure()` method
+- Documentation inconsistencies and outdated examples
+
+### Improved
+- Better error handling for MSA Search API responses
+- Retry logic for MSA Search requests
+- More comprehensive test coverage
+
+## [0.2.1] - 2025-08-14
+
+### Added
+- Complete multi-endpoint support for ALL Boltz2 NIM functionalities:
+  - `predict_protein_structure()` with MSA support
+  - `predict_protein_ligand_complex()` with affinity prediction
+  - `predict_covalent_complex()`
+  - `predict_dna_protein_complex()`
+  - `predict_with_advanced_parameters()`
+  - `predict_from_yaml_config()` and `predict_from_yaml_file()`
+- New `msa` parameter in `predict_protein_structure()` for direct MSA input
+- Comprehensive demo notebook (`examples/boltz2_comprehensive_demo.ipynb`) with:
+  - Single and multi-endpoint examples
+  - Both Python API and CLI demonstrations
+  - Advanced features and visualization
+- `AlignmentFormat` export in `__init__.py`
+
+### Fixed
+- MSA support now correctly uses nested dictionary format `{database: {format: AlignmentFileRecord}}`
+- CLI multi-endpoint initialization (removed incorrect `is_async` parameter)
+- Multi-endpoint client MSA parameter passing
+- YAML configuration MSA format handling
+
+### Changed
+- Updated README.md examples (removed `is_async=True` from MultiEndpointClient)
+- Improved error handling in multi-endpoint operations
+- Better organization of test scripts into `test_scripts/` directory
+
+### Documentation
+- New comprehensive demo notebook with complete examples
+- Updated all guides for consistency
+- Added troubleshooting tips for multi-endpoint usage
+
+## [0.2.0] - Previous release
+- Initial multi-endpoint support for virtual screening
+- Basic affinity prediction features
+- Virtual screening capabilities

{boltz2_python_client-0.5.1 → boltz2_python_client-0.6.0}/MANIFEST.in

@@ -5,7 +5,9 @@ recursive-include docs *.md
 recursive-include licenses *.md *.txt LICENSE* *-LICENSE
 recursive-include boltz2_client *.py
 recursive-include examples *.py *.yaml *.a3m *.ipynb *.md *.json *.txt *.sh
-recursive-include tests *.py
+recursive-include tests *.py *.json *.a3m *.fasta
+recursive-include scripts *.py *.sh
+include pytest.ini
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]
 recursive-exclude * .DS_Store

boltz2_python_client-0.6.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.2
+Name: boltz2-python-client
+Version: 0.6.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: MIT
+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
+Project-URL: Documentation, https://github.com/NVIDIA/digital-biology-examples/tree/main/examples/nims/boltz-2/docs
+Project-URL: Changelog, https://github.com/NVIDIA/digital-biology-examples/blob/main/examples/nims/boltz-2/CHANGELOG.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
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: PyYAML>=6.0.0
+Requires-Dist: aiohttp>=3.8.0
+Provides-Extra: screening
+Requires-Dist: pandas>=1.5; extra == "screening"
+Provides-Extra: notebooks
+Requires-Dist: jupyterlab>=4; extra == "notebooks"
+Requires-Dist: ipykernel>=6; extra == "notebooks"
+Requires-Dist: py3Dmol>=2.0; extra == "notebooks"
+Requires-Dist: matplotlib>=3.6; extra == "notebooks"
+Requires-Dist: numpy>=1.23; extra == "notebooks"
+Provides-Extra: analysis
+Requires-Dist: numpy>=1.23; extra == "analysis"
+Requires-Dist: biopython>=1.80; extra == "analysis"
+Provides-Extra: sagemaker
+Requires-Dist: boto3>=1.26.0; extra == "sagemaker"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pandas>=1.5.0; extra == "dev"
+Requires-Dist: biopython>=1.80; extra == "dev"
+Requires-Dist: nbformat>=5.7; extra == "dev"
+Requires-Dist: jsonschema>=4.17; extra == "dev"
+Requires-Dist: py3Dmol>=2.0; extra == "dev"
+Requires-Dist: nbclient>=0.7; extra == "dev"
+Requires-Dist: ipykernel>=6; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+
+# Boltz-2 Python Client
+
+Copyright (c) 2025-2026, NVIDIA CORPORATION. All rights reserved.
+
+[![PyPI](https://img.shields.io/pypi/v/boltz2-python-client)](https://pypi.org/project/boltz2-python-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python and command-line interfaces for NVIDIA Boltz-2 NIM: protein, DNA/RNA,
+ligand and covalent complexes, binding affinity, MSA integration, templates,
+and multi-endpoint screening.
+
+Version **0.6.0** targets **NIM 1.9.0**. Releases are validated on
+[TestPyPI](https://test.pypi.org/project/boltz2-python-client/0.6.0/)
+before production publication. Select the matching index when installing.
+See [migration and compatibility](docs/migration-0.6.md).
+
+The source archive (`.tar.gz`) under the release page's **Download files** includes
+the current guides, scripts and notebooks. Relative links in this README refer
+to files in that extracted archive or a matching repository checkout.
+
+## Install
+
+Python 3.10 or newer:
+
+```bash
+# PyPI, after production publication
+python -m pip install boltz2-python-client==0.6.0
+
+# TestPyPI release and dependencies from PyPI
+python -m pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ boltz2-python-client==0.6.0
+
+# From this checkout or the extracted source archive
+python -m pip install -e '.[dev,notebooks]'
+```
+
+Optional extras: `notebooks` (Jupyter and visualization), `sagemaker` (boto3),
+`analysis` (NumPy and structure conversion), and `screening` (pandas for CSV and
+DataFrame helpers). The Python client itself needs no GPU;
+a running NIM server performs inference.
+
+## Quick start
+
+Run against a ready local server. This sequence is an input-format example;
+confidence scores do not establish a biological interaction.
+
+```python
+from pathlib import Path
+from boltz2_client import Boltz2SyncClient
+
+client = Boltz2SyncClient(base_url="http://localhost:8000", timeout=600)
+result = client.predict_protein_structure(
+    sequence="MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
+    output_dir=Path("results/protein"),
+)
+print(result.confidence_scores)
+```
+
+For notebooks and asynchronous programs, use `Boltz2Client` and `await`:
+
+```python
+from boltz2_client import Boltz2Client, Ligand, Polymer, PredictionRequest
+
+client = Boltz2Client(timeout=600)
+request = PredictionRequest(
+    polymers=[Polymer(id="A", molecule_type="protein", sequence="MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT")],
+    ligands=[Ligand(id="L1", smiles="CC(=O)Oc1ccccc1C(=O)O",
+                    predict_affinity=True, output_affinity_embedding=True)],
+    diffusion_samples=2,
+    max_parallel_samples=1,  # NIM 1.9+: lower peak GPU memory
+)
+result = await client.predict(request, output_dir="results/complex")
+print(result.affinities["L1"].affinity_pic50)
+print(result.affinities["L1"].affinity_embedding)
+```
+
+The second example demonstrates request syntax using a short protein fragment
+and aspirin; it is not a validated binding pair. Use full, appropriate target
+sequences and assess predictions against experimental evidence.
+
+## Endpoints
+
+| Deployment | Configuration | Prediction path |
+|---|---|---|
+| Local/self-hosted | `Boltz2Client(base_url="http://localhost:8000")` | `/biology/mit/boltz2/predict` |
+| NVIDIA hosted | `Boltz2Client(endpoint_type="nvidia_hosted")` | `/v1/biology/mit/boltz2/predict` |
+| SageMaker | `Boltz2Client(endpoint_type="sagemaker", sagemaker_endpoint_name="my-endpoint")` | boto3 `invoke_endpoint` |
+
+For hosted inference, supply the key through `NVIDIA_API_KEY` or `NGC_API_KEY`
+in the process environment (or `api_key` in Python). The default hosted base
+URL is `https://health.api.nvidia.com`. Local inference sends no authorization
+header. Hosted deployments may lag the container release; enable version-specific
+options only when that endpoint supports them.
+
+SageMaker requires the `sagemaker` extra and configured AWS credentials/region.
+See the [SageMaker connection example](docs/deployment.md#existing-sagemaker-endpoint).
+Use asynchronous clients in Jupyter; the synchronous wrapper uses `asyncio.run()`.
+
+## CLI
+
+```bash
+boltz2 health
+boltz2 protein ACDEFGHIKLMNPQRSTVWY --output-dir results/protein
+boltz2 protein ACDEFGHIKLMNPQRSTVWY --diffusion-samples 2 --max-parallel-samples 1
+boltz2 ligand ACDEFGHIKLMNPQRSTVWY --smiles CC --predict-affinity --output-affinity-embedding
+boltz2 advanced --config-file examples/data/nim_1_9_request.json --output-dir results/advanced
+boltz2 --endpoint-type nvidia_hosted protein ACDEFGHIKLMNPQRSTVWY
+boltz2 --multi-endpoint --base-url http://gpu1:8000,http://gpu2:8000 protein ACDEFGHIKLMNPQRSTVWY
+```
+
+These short sequences/ligands illustrate syntax. `boltz2 --help` lists all
+commands, including covalent constraints, YAML, MSA conversion and screening.
+
+## Results and matrices
+
+`predict()` saves every structure as `structure_0.cif`, `structure_1.cif`, etc.,
+plus `prediction_response.json` (complete response), `prediction_metadata.json`
+(scores, affinities, embeddings and runtime metrics), and `affinities.json` when
+present. Use `save_structures=False` or CLI `--no-save` to suppress client output.
+Use separate output directories for separate predictions to avoid overwriting files.
+
+**NIM 1.9 does not return full PAE/PDE matrices in JSON.** `write_full_pae=True`
+and `write_full_pde=True` create NPZ files on the server under
+`$NIM_OUTPUT_PATH/prediction_*/pae/` and `.../pde/`. `result.pae` and `result.pde`
+remain `None`. Mount the server output directory to retrieve these artifacts.
+Aggregate `complex_pde_scores` and `complex_ipde_scores` remain in the response.
+See [outputs](docs/outputs.md) for loading matrices and retaining results.
+
+## Deploy a local server
+
+Follow [local deployment](docs/deployment.md), including GPU/driver prerequisites,
+NGC login, cache and output mounts. The pinned image is
+`nvcr.io/nim/mit/boltz2:1.9.0`. The deployment script checks GPU access before
+starting a container:
+
+```bash
+# Set NGC_API_KEY (or NVIDIA_API_KEY) in the environment first.
+export LOCAL_NIM_CACHE="$HOME/.cache/nim"
+export LOCAL_NIM_OUTPUT="$HOME/boltz2-output"
+bash scripts/start_local_nim.sh
+```
+
+## Guides and examples
+
+Start with the [protein prediction notebook](examples/notebooks/01_protein_prediction.ipynb)
+and [example index](examples/README.md). Guides:
+
+- [Parameters](docs/parameters.md), [migration](docs/migration-0.6.md), [outputs](docs/outputs.md)
+- [Affinity](docs/affinity_prediction.md), [covalent complexes](docs/covalent_complex.md)
+- [MSA search](docs/msa_search.md), [A3M multimer pairing](docs/a3m_to_multimer_msa.md)
+- [YAML subset](docs/yaml.md), [async usage](docs/async.md)
+- [Multiple endpoints](docs/multi_endpoint.md), [virtual screening](docs/virtual_screening.md)
+- [Validation and release procedure](docs/development.md), [changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE). Third-party assets retain their [licenses](licenses/README.md).
+NVIDIA NIM container and model terms are separate from the Python client license.

boltz2_python_client-0.6.0/README.md

@@ -0,0 +1,158 @@
+# Boltz-2 Python Client
+
+Copyright (c) 2025-2026, NVIDIA CORPORATION. All rights reserved.
+
+[![PyPI](https://img.shields.io/pypi/v/boltz2-python-client)](https://pypi.org/project/boltz2-python-client/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Python and command-line interfaces for NVIDIA Boltz-2 NIM: protein, DNA/RNA,
+ligand and covalent complexes, binding affinity, MSA integration, templates,
+and multi-endpoint screening.
+
+Version **0.6.0** targets **NIM 1.9.0**. Releases are validated on
+[TestPyPI](https://test.pypi.org/project/boltz2-python-client/0.6.0/)
+before production publication. Select the matching index when installing.
+See [migration and compatibility](docs/migration-0.6.md).
+
+The source archive (`.tar.gz`) under the release page's **Download files** includes
+the current guides, scripts and notebooks. Relative links in this README refer
+to files in that extracted archive or a matching repository checkout.
+
+## Install
+
+Python 3.10 or newer:
+
+```bash
+# PyPI, after production publication
+python -m pip install boltz2-python-client==0.6.0
+
+# TestPyPI release and dependencies from PyPI
+python -m pip install --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ boltz2-python-client==0.6.0
+
+# From this checkout or the extracted source archive
+python -m pip install -e '.[dev,notebooks]'
+```
+
+Optional extras: `notebooks` (Jupyter and visualization), `sagemaker` (boto3),
+`analysis` (NumPy and structure conversion), and `screening` (pandas for CSV and
+DataFrame helpers). The Python client itself needs no GPU;
+a running NIM server performs inference.
+
+## Quick start
+
+Run against a ready local server. This sequence is an input-format example;
+confidence scores do not establish a biological interaction.
+
+```python
+from pathlib import Path
+from boltz2_client import Boltz2SyncClient
+
+client = Boltz2SyncClient(base_url="http://localhost:8000", timeout=600)
+result = client.predict_protein_structure(
+    sequence="MKTVRQERLKSIVRILERSKEPVSGAQLAEELSVSRQVIVQDIAYLRSLGYNIVATPRGYVLAGG",
+    output_dir=Path("results/protein"),
+)
+print(result.confidence_scores)
+```
+
+For notebooks and asynchronous programs, use `Boltz2Client` and `await`:
+
+```python
+from boltz2_client import Boltz2Client, Ligand, Polymer, PredictionRequest
+
+client = Boltz2Client(timeout=600)
+request = PredictionRequest(
+    polymers=[Polymer(id="A", molecule_type="protein", sequence="MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT")],
+    ligands=[Ligand(id="L1", smiles="CC(=O)Oc1ccccc1C(=O)O",
+                    predict_affinity=True, output_affinity_embedding=True)],
+    diffusion_samples=2,
+    max_parallel_samples=1,  # NIM 1.9+: lower peak GPU memory
+)
+result = await client.predict(request, output_dir="results/complex")
+print(result.affinities["L1"].affinity_pic50)
+print(result.affinities["L1"].affinity_embedding)
+```
+
+The second example demonstrates request syntax using a short protein fragment
+and aspirin; it is not a validated binding pair. Use full, appropriate target
+sequences and assess predictions against experimental evidence.
+
+## Endpoints
+
+| Deployment | Configuration | Prediction path |
+|---|---|---|
+| Local/self-hosted | `Boltz2Client(base_url="http://localhost:8000")` | `/biology/mit/boltz2/predict` |
+| NVIDIA hosted | `Boltz2Client(endpoint_type="nvidia_hosted")` | `/v1/biology/mit/boltz2/predict` |
+| SageMaker | `Boltz2Client(endpoint_type="sagemaker", sagemaker_endpoint_name="my-endpoint")` | boto3 `invoke_endpoint` |
+
+For hosted inference, supply the key through `NVIDIA_API_KEY` or `NGC_API_KEY`
+in the process environment (or `api_key` in Python). The default hosted base
+URL is `https://health.api.nvidia.com`. Local inference sends no authorization
+header. Hosted deployments may lag the container release; enable version-specific
+options only when that endpoint supports them.
+
+SageMaker requires the `sagemaker` extra and configured AWS credentials/region.
+See the [SageMaker connection example](docs/deployment.md#existing-sagemaker-endpoint).
+Use asynchronous clients in Jupyter; the synchronous wrapper uses `asyncio.run()`.
+
+## CLI
+
+```bash
+boltz2 health
+boltz2 protein ACDEFGHIKLMNPQRSTVWY --output-dir results/protein
+boltz2 protein ACDEFGHIKLMNPQRSTVWY --diffusion-samples 2 --max-parallel-samples 1
+boltz2 ligand ACDEFGHIKLMNPQRSTVWY --smiles CC --predict-affinity --output-affinity-embedding
+boltz2 advanced --config-file examples/data/nim_1_9_request.json --output-dir results/advanced
+boltz2 --endpoint-type nvidia_hosted protein ACDEFGHIKLMNPQRSTVWY
+boltz2 --multi-endpoint --base-url http://gpu1:8000,http://gpu2:8000 protein ACDEFGHIKLMNPQRSTVWY
+```
+
+These short sequences/ligands illustrate syntax. `boltz2 --help` lists all
+commands, including covalent constraints, YAML, MSA conversion and screening.
+
+## Results and matrices
+
+`predict()` saves every structure as `structure_0.cif`, `structure_1.cif`, etc.,
+plus `prediction_response.json` (complete response), `prediction_metadata.json`
+(scores, affinities, embeddings and runtime metrics), and `affinities.json` when
+present. Use `save_structures=False` or CLI `--no-save` to suppress client output.
+Use separate output directories for separate predictions to avoid overwriting files.
+
+**NIM 1.9 does not return full PAE/PDE matrices in JSON.** `write_full_pae=True`
+and `write_full_pde=True` create NPZ files on the server under
+`$NIM_OUTPUT_PATH/prediction_*/pae/` and `.../pde/`. `result.pae` and `result.pde`
+remain `None`. Mount the server output directory to retrieve these artifacts.
+Aggregate `complex_pde_scores` and `complex_ipde_scores` remain in the response.
+See [outputs](docs/outputs.md) for loading matrices and retaining results.
+
+## Deploy a local server
+
+Follow [local deployment](docs/deployment.md), including GPU/driver prerequisites,
+NGC login, cache and output mounts. The pinned image is
+`nvcr.io/nim/mit/boltz2:1.9.0`. The deployment script checks GPU access before
+starting a container:
+
+```bash
+# Set NGC_API_KEY (or NVIDIA_API_KEY) in the environment first.
+export LOCAL_NIM_CACHE="$HOME/.cache/nim"
+export LOCAL_NIM_OUTPUT="$HOME/boltz2-output"
+bash scripts/start_local_nim.sh
+```
+
+## Guides and examples
+
+Start with the [protein prediction notebook](examples/notebooks/01_protein_prediction.ipynb)
+and [example index](examples/README.md). Guides:
+
+- [Parameters](docs/parameters.md), [migration](docs/migration-0.6.md), [outputs](docs/outputs.md)
+- [Affinity](docs/affinity_prediction.md), [covalent complexes](docs/covalent_complex.md)
+- [MSA search](docs/msa_search.md), [A3M multimer pairing](docs/a3m_to_multimer_msa.md)
+- [YAML subset](docs/yaml.md), [async usage](docs/async.md)
+- [Multiple endpoints](docs/multi_endpoint.md), [virtual screening](docs/virtual_screening.md)
+- [Validation and release procedure](docs/development.md), [changelog](CHANGELOG.md)
+
+## License
+
+[MIT](LICENSE). Third-party assets retain their [licenses](licenses/README.md).
+NVIDIA NIM container and model terms are separate from the Python client license.

{boltz2_python_client-0.5.1 → boltz2_python_client-0.6.0}/boltz2_client/__init__.py

@@ -26,7 +26,7 @@ Example:
     >>> print(f"Confidence: {result.confidence_scores[0]:.3f}")
 """
 
-__version__ = "0.5.1"
+__version__ = "0.6.0"
 __author__ = "NVIDIA Corporation"
 __email__ = "bionemo-support@nvidia.com"
 
@@ -103,28 +103,6 @@ from .utils import (
     convert_pdb_to_cif,
 )
 
-# Optional imports for visualization
-try:
-    from .visualization import (
-        StructureVisualizer,
-        visualize_structure,
-        create_multi_view,
-    )
-    _HAS_VISUALIZATION = True
-except ImportError:
-    _HAS_VISUALIZATION = False
-
-# Optional imports for analysis
-try:
-    from .analysis import (
-        StructureAnalyzer,
-        calculate_rmsd,
-        analyze_contacts,
-    )
-    _HAS_ANALYSIS = True
-except ImportError:
-    _HAS_ANALYSIS = False
-
 __all__ = [
     # Core client classes
     "Boltz2Client",
@@ -201,21 +179,6 @@ __all__ = [
     "SPECIES_TO_TAXID",
 ]
 
-# Add visualization exports if available
-if _HAS_VISUALIZATION:
-    __all__.extend([
-        "StructureVisualizer",
-        "visualize_structure", 
-        "create_multi_view",
-    ])
-
-# Add analysis exports if available
-if _HAS_ANALYSIS:
-    __all__.extend([
-        "StructureAnalyzer",
-        "calculate_rmsd",
-        "analyze_contacts",
-    ])
 
 def get_version() -> str:
     """Get the current version of the package."""