---

name: contrib-utilities description: "Use optional RDKit Contrib utilities safely: SA Score, NP Score, NIBR substructure filters, Fraggle, MMPA, FreeWilson, and MolVS-derived recipes, while distinguishing them from core RDKit APIs." disable-model-invocation: true metadata: disco-role: operating license: BSD 3-Clause

RDKit Contrib Utilities

Use this sub-skill when a task asks about community-contributed or optional RDKit utilities under the Contrib umbrella, especially SA Score, NP Score, NIBR substructure filters, Fraggle similarity, MMPA scripts, Free-Wilson decomposition/enumeration, or legacy MolVS-derived command-line recipes.

Route Here

• Estimate synthetic accessibility with the contributed SA Score implementation when its scorer module and fragment-score data are available.
• Estimate natural-product likeness with the contributed NP Score implementation when its scorer module and model data are available.
• Apply or explain NIBR hit-triage substructure filters, including their pandas/numpy dependency and CSV input/output shape.
• Explain Fraggle’s three-stage workflow: fragment query molecules, run Tversky search, and post-process atom contributions.
• Explain MMPA’s fragmentation, indexing, canonical SMIRKS, transform application, and optional SQLite/SMARTS database search workflows.
• Use or adapt FreeWilson when the optional module and scientific Python dependencies are installed for scaffold decomposition and activity prediction.
• Recognize MolVS-derived contributed utilities as historical/convenience wrappers; prefer core MolStandardize for standardization work.

Route Elsewhere

• Use ../descriptors-fingerprints/ for core RDKit descriptors, QED, Lipinski, Crippen, MolSurf, Morgan fingerprints, bit-vector similarity, clustering, and feature tables.
• Use ../reactions-standardization/ for core rdMolStandardize, reaction SMARTS/RXN workflows, R-group decomposition, tautomer handling, and stereochemistry-preserving transformations.
• Use ../molecule-io-core/ for SMILES/SDF parsing, molecule validation, canonicalization, salts/mixtures, and sanitization before optional contrib tools.
• Use ../conformers-drawing/ for 2D/3D depictions, conformers, shape alignment, RMSD, and drawing similarity maps.

Start With These References

• references/scoring-and-filters.md for SA Score, NP Score, NIBR filters, MolVS-derived utility routing, data files, dependencies, and safe fallback patterns.
• references/mmpa-fraggle-freewilson.md for MMPA, Fraggle, FreeWilson, command shapes, input hygiene, output expectations, and optional dependency notes.
• references/troubleshooting.md for missing modules/data, binary-package differences, path assumptions, optional pandas/numpy/scipy/sklearn dependencies, and route decisions.
• scripts/contrib_scores_smoke.py for a safe availability check that imports RDKit, parses small SMILES, and reports whether contributed SA/NP scorer modules and model data are importable.

Contrib Safety Principles

1. Treat Contrib utilities as optional examples unless the active environment proves the specific script/module and data file are importable.
2. Do not assume binary RDKit packages install every Contrib script as a Python module; core RDKit imports can succeed while Contrib utilities are absent.
3. Keep model/data files explicit: SA Score needs fragment-score data such as fpscores.pkl.gz; NP Score needs model data such as publicnp.model.gz; NIBR filters need their CSV filter table.
4. Prefer installed package APIs for core cheminformatics and use Contrib recipes only for the specialized methods they implement.
5. For public agent guidance, report availability and alternatives instead of silently adding source checkout paths to sys.path.

Quick Smoke

Run this from the sub-skill directory or pass it by full path in an environment where RDKit is importable:

python scripts/contrib_scores_smoke.py --smiles "CCO" "c1ccccc1O"

Expected behavior is a compact report: RDKit import status, molecule parse status, and whether SA Score or NP Score contributed modules/data are available. Missing Contrib modules or data are reported as unavailable, not as a fatal failure unless core RDKit cannot import or a provided SMILES is invalid.