deepretro.utils.az

AiZynthFinder integration helpers for template-based retrosynthesis.

Installation

Install the package with deepretro[az] before using this module:

uv pip install "deepretro[az]"

What This Module Does

  • Runs AiZynthFinder search for a target SMILES.

  • Returns route dictionaries with metadata/scores.

  • Provides optional image outputs for generated routes.

  • Supports optional explicit caching through CacheManager.

  • Short-circuits simple molecules to avoid unnecessary search overhead.

Caching

run_az and run_az_with_img do not cache anything unless the caller passes a cache instance explicitly:

from deepretro.utils.az import run_az
from deepretro.utils.cache import CacheManager

cache = CacheManager()
solved, routes = run_az("C1CCCCC1", az_model="USPTO", cache=cache)

Configuration

The module resolves configuration in this order:

  1. AZ_MODELS_PATH/<az_model>/config.yml (model-variant specific)

  2. AZ_MODEL_CONFIG_PATH (fallback global config)

Both are interpreted relative to project root when loaded by this module.

Basic Molecule Shortcut

run_az and run_az_with_img bypass tree search if:

  • The molecule is in BASIC_MOLECULES, or

  • is_basic_molecule(smiles) is True

In these cases, the function returns a solved status and an in-stock molecule route object immediately.

API

AiZynthFinder integration for template-based retrosynthesis.

Runs AiZynthFinder on target molecules, with optional image export. Uses ZINC stock and USPTO expansion/filter policies by default. Requires AZ_MODEL_CONFIG_PATH or AZ_MODELS_PATH environment variables. Caching is opt-in through an explicit CacheManager argument.

deepretro.utils.az.run_az(smiles, az_model='USPTO', cache=None)[source]

Run the retrosynthesis using AiZynthFinder.

Example

>>> from deepretro.utils.az import run_az
>>> status, result_dict = run_az("C1CCCCC1", "USPTO")  
>>> isinstance(status, bool) and isinstance(result_dict, list)  
True
Parameters:

  • smiles (str) – SMILES string of the target molecule.

  • az_model (str, optional) – AiZynthFinder model variant (e.g. "USPTO", "Pistachio_50"), by default "USPTO".

  • cache (CacheManager | None, optional) – Explicit cache instance used to memoize results for this call. When None, no cache is read or written.

Returns:

(solved, routes) — whether a route was found and the route data.

Return type:

tuple[bool, Sequence[Dict[str, Any]]]

Notes

Install the package with deepretro[az]. Caching is disabled unless an explicit cache=CacheManager(...) is supplied.

deepretro.utils.az.run_az_with_img(smiles, cache=None)[source]

Run the retrosynthesis using AiZynthFinder, including route images.

Example

>>> from deepretro.utils.az import run_az_with_img
>>> status, result_dict, images = run_az_with_img("C1CCCCC1")  
>>> isinstance(status, bool)  
True
Parameters:

  • smiles (str) – SMILES string of the target molecule.

  • cache (CacheManager | None, optional) – Explicit cache instance used to memoize results for this call. When None, no cache is read or written.

Returns:

(solved, routes, images) — solved status, route data, and optional route images (PNG bytes). Uses AZ_MODEL_CONFIG_PATH.

Return type:

tuple[bool, Sequence[Dict[str, Any]], Sequence[Image] | None]

Notes

Install the package with deepretro[az]. Caching is disabled unless an explicit cache=CacheManager(...) is supplied.

deepretro.utils.az.is_basic_molecule(smiles)[source]

Check if the molecule is a basic molecule (if number of C atoms is less than 5 or total atoms < 5).

Parameters:

smiles (str) – SMILES string of the target molecule

Returns:

True if the molecule is a basic molecule, False otherwise

Return type:

bool

Examples

>>> from deepretro.utils.az import is_basic_molecule
>>> is_basic_molecule("C")
True
>>> is_basic_molecule("CC")
True
>>> is_basic_molecule("C1CCCCC1")
False
>>> is_basic_molecule("CCO")
True
>>> is_basic_molecule("invalid_smiles!!")
False