# Python API
## `find_routes`
```python
renkin.find_routes(
smiles: str,
depth: int = 5,
max_routes: int = 5,
beam_width: int = 0,
building_blocks: list[str] | None = None,
) -> dict
```
Find retrosynthetic routes for a target molecule.
**Parameters:**
| `smiles` | `str` | required | Target molecule as SMILES string |
| `depth` | `int` | `5` | Maximum number of retrosynthetic steps |
| `max_routes` | `int` | `5` | Maximum number of routes to return |
| `beam_width` | `int` | `0` | A\* beam width (0 = unlimited BFS/A\*) |
| `building_blocks` | `list[str]` | `None` | Custom building block SMILES list. If `None`, uses the built-in library (509 compounds) |
**Returns:**
```python
{
"routes_found": int, # number of routes found
"routes": [
{
"depth": int, # number of steps in this route
"steps": [
{
"target": str, # SMILES of molecule being disconnected
"rule": str, # reaction rule name
"precursors": list[str], # SMILES of precursor molecules
}
]
}
]
}
```
**Example:**
```python
import renkin
result = renkin.find_routes("CC(=O)Oc1ccccc1C(=O)O", depth=5, max_routes=3)
print(f"Routes: {result['routes_found']}")
for route in result['routes']:
print(f" depth={route['depth']}: {len(route['steps'])} step(s)")
```
## `version`
```python
renkin.version() -> str
```
Returns the RENKIN version string.
```python
>>> import renkin
>>> renkin.version()
'0.2.1'
```
## Building Blocks
The default building block library includes 509 commercially available compounds:
- Simple aliphatics (C1–C6 chains, alcohols, acids)
- Aryl and heteroaryl halides (Br, Cl, I)
- Boronic acids (Suzuki coupling acceptors)
- Pyridines, pyrimidines, pyrazoles, imidazoles, furans, thiophenes
- Common pharmaceutical amines (piperidine, morpholine, piperazine, etc.)
- Aldehydes and ketones for reductive amination
- Protecting group reagents (Boc, Cbz)
- Amino acids (Gly, Ala, Asp, Glu, Ser, Phe, Tyr, Lys, Cys, Val)
To use a custom library, pass a list of SMILES strings to the `building_blocks` parameter.
## Error Handling
```python
import renkin
try:
result = renkin.find_routes("invalid_smiles")
except Exception as e:
print(f"Error: {e}")
# "Failed to parse SMILES: invalid_smiles"
```
Common errors:
- `Failed to parse SMILES: ...` — invalid SMILES string
- `Building block parse error: ...` — invalid SMILES in custom building blocks list