orthonym.rules.conjugate_controller#

Note

Internal API. Names and behaviour may change between releases.

Class-agnostic conjugate-fragment classifier (a phase, -03,).

A NEW standalone, class-agnostic primitive: given a molecule, a scaffold attachment atom, the linker atom (first_idx) reached through it, and the scaffold atom set, it classifies the fragment past the linker as a sulfate ester, mono-phosphate ester, or glycosyl/uronyl conjugate and returns the functional-class word/head plus the consumed-atom set. Returns None (fail-closed) for anything else.

This is the cross-class deliverable (-03 crit #2): the signature is classify_conjugate(mol, attach_idx, first_idx, scaffold_atoms) with NO steroid-specific branch, so the glycoside (a phase) and lipid (a phase) paths can call the SAME primitive later. This phase wires it into the NP subsystem (182-02); the logic here is class-agnostic.

Charge -> word is derived in place from the protonation/ionisation state of the acid centre on the ORIGINAL molecule — never neutralize-then-rename (the failure mode), never a per-molecule hardcode:

-OSO2[O-] -> “sulfate” -OSO2OH -> “hydrogen sulfate” -OPO(OH)2 -> “dihydrogen phosphate” mono-anion -> “hydrogen phosphate” di-anion -> “phosphate” (BB partial esters/salts; phosphate

ionisation; word examples / /.)

The glycoside branch caps the broken glycosidic bond at the ATOM level (Chem.FragmentOnBonds + restore the anomeric -OH + Chem.MolToSmiles) so the capped fragment canonicalizes to a URONIC_ACID_NAMES key — NO string surgery on the sugar head (RESEARCH Open Q2 RESOLVED). The uronic head form comes from the explicit data.sugar_names.uronic_glycoside_head map (BB).

Root-cause-only (the contributor guide): no postprocessor, no regex on any existing name string, no neutralize-then-rename, no per-molecule hardcode. All logic is RDKit atom/bond walks + dict lookups + set math; the function is pure (no global state, no mol mutation — the NP dispatch calls the path twice, Pitfall 5).

orthonym.rules.conjugate_controller.classify_conjugate(mol, attach_idx, first_idx, scaffold_atoms)#

Classify a conjugate fragment reached through a scaffold heteroatom linker.

Parameters:

  • mol – the RDKit Mol (read-only; not mutated).

  • attach_idx (int) – the scaffold atom the fragment attaches to.

  • first_idx (int) – the linker atom (an ester-O, NOT an -OH) past attach_idx.

  • scaffold_atoms (Set[int]) – the set of scaffold atom indices to exclude from the walk.

Returns:

{"kind", "word", "all_atoms", "linker_kind"} for a sulfate / mono-phosphate / glycosyl(uronyl) fragment, else None (fail-closed).

Return type:

Dict | None