chore!: modernize SAFE conversion, stereochemistry and generation

[maclandrol]

Changelogs

Prepare the next major SAFE release with stricter molecular identity preservation, a maintained generation stack and a lightweight notation-only installation.

Companion PRs: datamol-io/datamol#244, datamol-io/molfeat#124 and datamol-io/medchem#37.

• Preserve the original contributor histories from Support RDKit extended ring closures for molecules with >= 100 ring bonds #71 (extended ring closures) and Fix wildcart (*) uses in SMILES #33 (wildcard handling).
• Improve encoding/decoding of E/Z, shared directional bonds, tetrahedral and supported non-tetrahedral stereo, explicit hydrogens, charges and wildcard topology. Canonical decoding is serialization, not charge neutralization or tautomer standardization.
• Verify the final dummy-aware isomeric graph. When no stereochemically safe cut exists, return the exact unfragmented molecule. Reject unsupported enhanced CXSMILES stereo groups explicitly rather than dropping their semantics.
• Support %(100)-style ring closures through conversion and tokenization. Preserve open terminal attachment points without changing lone/degree-two wildcard topology.
• Move SAFE-GPT inference/training to Transformers 5, covering logits, one-item property predictions, tokenizer serialization and deterministic generation paths. Constrained linker generation loads reviewed, commit-pinned custom generation code only when needed.
• Simplify sampling modes and expose prompt-independent max_new_tokens. Add opt-in try_hard filtering/oversampling to design workflows, with structural-constraint checks, stable deduplication and bounded output counts.
• Improve scaffold/linker/pattern generation, local random-state handling, model revision/local-directory controls, visualization validation and training CLI errors.
• Keep only conversion/splitting dependencies in the core. Model, training, visualization and experiment reporting are explicit extras.
• Refresh README Updates, changelog, migration and release documentation; mark original cluster-specific expts/ files as historical research artifacts rather than supported training examples. They are not installed in the Python package.
• Keep release publication manual using PYPI_API_TOKEN, with a non-publishing dry run, complete test gates, isolated wheel/source tests and attestations.

Breaking changes and preserved behavior

• Python 3.11+ and RDKit 2024.09+ are required. RDKit 2026.03 is excluded because of observed double-bond direction regressions; it is not silently treated as supported.
• Install safe-mol[model], [train], [viz] or [all] for those features. Core imports do not require Transformers/PyTorch.
• ignore_errors=True still returns None for invalid batch entries. Strict decoding raises SAFEDecodeError.
• motif_extension() is deprecated in favor of scaffold_decoration(..., add_dot=True); max_length is deprecated in favor of max_new_tokens.
• Contrastive/diverse-beam wrappers are removed. Maintained greedy, multinomial, beam, beam-sampling and constrained linker behavior has regression coverage.
• try_hard reduces invalid/duplicate candidates but cannot guarantee the requested count or global chemical diversity. Unsupported stereo is rejected rather than silently approximated.

Issues and contributor history

Closes #70 (Transformers 5 import/inference compatibility).
Closes #67 (attachment-point preservation and scaffold decoration).
Closes #32 (wildcard topology artifacts).
Closes #55 (obsolete import dependencies; maintained Python support is now 3.11–3.14, not 3.9/3.10).

Refs #62: local/offline checkpoint loading is now explicit, but this does not repair a user's network configuration. #69 (paper reinforcement-learning workflow) is not addressed by this maintenance PR.

Please use a merge commit so the original #71/#33 contributions remain in the main history.

Intel macOS compatibility

SAFE's notation core supports Intel macOS, including co-installation with Molfeat. SAFE-GPT model/training extras require PyTorch 2.5+ and cannot use the final official Intel macOS PyTorch 2.2 wheels. This boundary is now explicit in the README, migration guide and changelog. Local regression check: 109 non-integration tests passed after the dependency audit.

Validation

• Regression tests cover exact isomeric graph round-trips, attachment points, strict/batch errors, extended ring closures, tokenizer persistence, sampling modes, design constraints and training/model compatibility.
• Core CI covers Linux, Windows, Apple Silicon and Intel Macs with the supported Python/RDKit matrix; published SAFE-GPT, maintained extras, training CLI and executable tutorials run in separate Linux jobs.
• Local release-validator tests, Black, Ruff and workflow lint passed; the documentation builds in strict mode.
• Fresh wheel/source builds passed Twine and isolated notation round-trip checks; wheel inspection confirms only SAFE's package namespace and Apache-2.0 notice are installed. ChEMBL audit datasets/results and downloaded model weights are not added to this repository.
• The latest dev test run and PR checks must pass before merge. These checks do not constitute a rerun of the entire ChEMBL corpus in this final packaging audit.

---

Checklist:

• Add regression tests for conversion, stereo, generation and training fixes.
• Update API, migration, installation and experiment documentation.
• Write explanatory changelogs and README Updates.
• Assign the fix label.
• Resolve the SAFE-GPT weight-license discrepancy below before marking ready.

---

Release and licensing discussion

Draft pending model-license clarification. Code is Apache-2.0; the separately distributed training dataset is CC BY 4.0. The two root license files describe different materials, not alternative licenses for SAFE's Python code, so neither has been removed.

The existing README says SAFE-GPT weights are CC BY-NC 4.0, while the model card at the pinned revision declares Apache-2.0. This discrepancy is now explicit in the README and needs an owner decision; this PR does not relicense or redistribute the weights.

Merging will not publish a package or create a version. After resolving that discrepancy, finalize the changelog and run the manual release rehearsal from main. See docs/releasing.md for publication and conda-forge follow-up. No package upload was attempted during this audit.

This PR is AI-assisted.