Add CheMeleon GNN-based Fingerprints to Mother

[thomasATbayer]

feat: Add CheMeleon GNN-based Fingerprints to Mother

Branch

ChemeleonTransformerTW

---

Summary

Introduce CheMeleon (chemprop-based Graph Neural Network) fingerprints as a
first-class fingerprint generator in Mother, alongside the existing RDKit-based
classical fingerprints.

CheMeleon produces fixed-length molecular embeddings from SMILES strings using a
pretrained GNN checkpoint, enabling richer molecular representations for downstream
ML tasks.

---

Motivation

Mother currently relies on classical RDKit fingerprints (ECFP, MACCS, RDKit FP, …)
for molecular feature generation. While these are fast and interpretable, they are
limited by the fixed radius / bit-length design and do not capture global molecular
context.

GNN-based embeddings from a pretrained model like CheMeleon offer:

• Richer representations — message-passing captures long-range structural context
• Transfer learning — embeddings are pretrained on large chemical datasets
• Drop-in compatibility — output is a fixed-length NumPy array, identical API to
  classical fingerprint generators
• Optional dependency — chemprop >= 2.0 is a soft requirement; the rest of
  Mother is unaffected if it is not installed

---

Changes Introduced

New files

File	Description
mother/feature_generation/fp_gnn_gen.py	CheMeleonFingerprintFactory and sklearn-compatible CheMeleonFingerprintTransformer
test/unit/test_fp_gnn_gen.py	Unit tests covering happy-path, missing-dependency error, and edge cases

Modified files

File	Change
pyproject.toml	Added chemprop as an optional extra ([gnn]); updated package source layout (src/mother → mother)
.github/workflows/workflow.yml	CI updated to install optional [gnn] extra and run GNN tests
sonar-project.properties	Updated source path to match new package layout
uv.lock	Lockfile regenerated after dependency changes

---

API

from mother.feature_generation.fp_gnn_gen import CheMeleonFingerprintFactory

factory = CheMeleonFingerprintFactory()
fp_gen  = factory.get_fingerprint_generator()   # downloads weights on first call

fps = fp_gen.transform(["CCO", "c1ccccc1"])     # np.ndarray  shape (2, 2048)

The transformer is fully sklearn-compatible and can be used inside a
sklearn.pipeline.Pipeline.

---

Dependency Handling

chemprop >= 2.0 is not a hard requirement. The import is deferred:

• The module imports successfully even when chemprop is absent.
• An ExtrasDependencyImportError is raised only when a factory method is called.
• Consumers can check availability with mother.feature_generation.fp_gnn_gen._check_chemprop().

Install the extra with:

pip install "mother[gnn]"

---

Testing

pytest test/unit/test_fp_gnn_gen.py -v

Tests cover:

• Transformer output shape and dtype
• Correct error raised when chemprop is not installed
• Handling of invalid SMILES
• Integration with the existing FeatureGenerationConfig

---

Checklist

• New module fp_gnn_gen.py implemented
• Unit tests added (test_fp_gnn_gen.py)
• Optional dependency declared in pyproject.toml ([gnn] extra)
• CI workflow updated to test with GNN extra
• Package layout migrated (src/mother → mother)
• Documentation page added to mkdocs
• Example notebook demonstrating CheMeleon fingerprints
• Integration test with a real chemprop checkpoint

---

Related

• CheMeleon / chemprop: https://github.com/chemprop/chemprop
• Existing fingerprint generators: mother/feature_generation/fp_gen.py