Metadata-Version: 2.4
Name: mol-healer
Version: 0.2.1
Summary: Hit Expansion to Advanced Leads Using Enumerated Reactions
Author-email: Enes Kelestemur <enesk@email.unc.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/eneskelestemur/healer
Project-URL: Repository, https://github.com/eneskelestemur/healer
Project-URL: Documentation, https://github.com/eneskelestemur/healer/blob/main/docs/README.md
Project-URL: Issues, https://github.com/eneskelestemur/healer/issues
Keywords: chemistry,drug-discovery,hit-expansion,enumeration,retrosynthesis
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: prop-profiler>=0.2.1
Requires-Dist: numpy>=2.0
Requires-Dist: pandas>=2.0
Requires-Dist: tqdm>=4.62
Requires-Dist: rdkit>=2024.6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: joblib>=1.3
Provides-Extra: web
Requires-Dist: fastapi>=0.110; extra == "web"
Requires-Dist: uvicorn[standard]>=0.27; extra == "web"
Requires-Dist: celery[redis]>=5.3; extra == "web"
Provides-Extra: opt
Requires-Dist: pygad>=3.0; extra == "opt"
Requires-Dist: baybe[chem]>=0.10; extra == "opt"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Requires-Dist: ruff==0.16.3; extra == "dev"
Requires-Dist: nbformat>=5.9; extra == "dev"
Requires-Dist: nbconvert>=7.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="assets/healer_logo.png" alt="HEALER Logo" width="400"/>
</p>

<h1 align="center">HEALER</h1>
<h3 align="center">Hit Expansion to Advanced Leads Using Enumerated Reactions</h3>

<p align="center">
  <a href="docs/installation.md">Installation</a> •
  <a href="docs/quickstart.md">Quick Start</a> •
  <a href="docs/README.md">Documentation</a> •
  <a href="notebooks/healer_demo.ipynb">Demo</a> •
  <a href="#citation">Citation</a>
</p>

---

HEALER generates synthetically accessible molecular analogs by combining
retrosynthetic fragmentation with commercially available building blocks and
validated reaction templates. It bridges the gap between computational design and
laboratory synthesis.

## Features

- **Molecule HEALER** — retrosynthetically fragment a molecule and re-enumerate with similar building blocks
- **Fragment HEALER** — enumerate from pre-fragmented molecules
- **Site HEALER** — targeted enumeration at specific reactive sites with property filters
- **Guided enumeration** — steer the search with beam search, genetic algorithms, or Bayesian optimization
- **Synthetically accessible** — every product comes from a validated reaction template
- **Flexible** — works with any building block library in SDF format

## Installation

```bash
pip install mol-healer
```

Optional extras: `mol-healer[web]` for the browser interface, `mol-healer[opt]`
for guided enumeration. See [Installation](docs/installation.md).

## Quick Start

```python
from healer import MoleculeHEALER

healer = MoleculeHEALER(
    bb_source='test',                              # bundled 100-BB test set
    reaction_tags=['amide coupling', 'N-arylation'],
    sim_threshold=0.5,
)

healer.set_query_mol("CC1(C)SC2C(NC(=O)Cc3ccccc3)C(=O)N2C1C(=O)O", n_compositions=10)
healer.enumerate(max_evals_per_comp=500)

results = healer.get_results(calc_similarity=True, calc_properties=True)
print(f"Generated {len(results)} analogs")
```

```bash
healer molecule "CCO" --bb-source test -o results.csv
```

Production runs need a real building block library — see
[Building Blocks](docs/building-blocks.md).

## Documentation

Full documentation is in [`docs/`](docs/README.md).

| Guide | |
|-------|---|
| [Installation](docs/installation.md) | Package, extras, console scripts |
| [Building Blocks](docs/building-blocks.md) | Downloading, preprocessing, selecting libraries |
| [Quick Start](docs/quickstart.md) | A first enumeration |
| [HEALER Classes](docs/healer-classes.md) | The three modes and their parameters |
| [Guided Enumeration](docs/guided-enumeration.md) | Optimizing toward an objective |
| [Results](docs/results.md) | Output columns and properties |
| [Logging & Progress](docs/logging.md) | Log levels and progress bars |
| [Command Line](docs/cli.md) | The `healer` CLI |
| [Web Interface](docs/web-interface.md) | `healer-ui` and server mode |
| [Reactions](docs/reactions.md) | Reaction library and contributing templates |
| [Architecture](docs/architecture.md) | How the pieces fit together |

[`notebooks/healer_demo.ipynb`](notebooks/healer_demo.ipynb) walks through the
Python API with visualizations. Release notes are in
[`CHANGELOG.md`](CHANGELOG.md).

## Contributing

Reaction templates are welcome — see [Reactions](docs/reactions.md#contributing)
for the entry format, then open an
[issue](https://github.com/eneskelestemur/healer/issues).

For code contributions:

```bash
git clone https://github.com/eneskelestemur/healer.git
cd healer
pip install -e '.[dev,web,opt]'
pytest
```

## Citation

If you use HEALER in your research, please cite:

```bibtex
@article{healer2025,
  title={HEALER: Hit Expansion to Advanced Leads Using Enumerated Reactions},
  author={Kelestemur, Enes and ...},
  journal={...},
  year={2025}
}
```

## License

This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.

## Acknowledgments

- Reaction template formats mainly adapted from [datamol](https://github.com/datamol-io/datamol)
- Building block preprocessing inspired by retrosynthesis literature
- [Ketcher](https://github.com/epam/ketcher) for molecular drawing
