orthonym.assembly.general_engine

Note

Internal API. Names and behaviour may change between releases.

: general substitutive chain namer with atom->token bindings.

NEW code (design: internal notes G1). Unlike the legacy composer path, every emission carries a TokenBinding partition over ALL heavy atoms, so the E1 certificate (validation/e1_certificate.py) can verify no atom was silently dropped – Java-free. Output is OPT-IN (namer general_fallback flag); it re-enters the existing moat (>15-HA gate, P10 vetoes, OPSIN-RT) downstream.

G1 scope: neutral, single-fragment, chain-parented molecules with an all-carbon parent chain of length >= 2 and a suffix from the supported set (or none). Ring parents -> G2 (general ring fallback). Charged -> G3. Anything outside scope REFUSES (returns None): fail-closed, never partial.

class orthonym.assembly.general_engine.TokenBinding(atom_ids, token, role, charge_atom_ids=())

Bases: object

Atoms expressed by one emitted name token.

atom_ids: Tuple[int, ...]

token: str

role: str

charge_atom_ids: Tuple[int, ...] = ()

class orthonym.assembly.general_engine.GeneralEngineResult(name: 'str', bindings: 'Tuple[TokenBinding, ...]', stereo_atom_to_locant: 'Dict[int, int]'=<factory>)

Bases: object

name: str

bindings: Tuple[TokenBinding, ...]

stereo_atom_to_locant: Dict[int, int]

orthonym.assembly.general_engine.name_general_chain(mol, features, allow_charged=False, allow_mancude=False)

Name a chain-parented molecule with a full atom->token partition.

Returns None on ANY condition outside the verified G1 scope.

: allow_charged (only under complete) lifts the net-charge refusal and emits a -ide/-ylium/-ium/-uide suffix on the numbered chain parent when the charge sits on a chain skeletal atom (fail-closed otherwise).

: allow_mancude (complete/best-effort tier only) lets a multi-ring cage SUBSTITUENT on the chain be named via the universal von-Baeyer engine (parent<->substituent symmetry). Default False -> PIN path byte-identical.

orthonym.assembly.general_engine.name_general_ring(mol, features, allow_aromatic_general=False, allow_charged=False)

: universal von-Baeyer ring-parent path (opt-in engine only).

: allow_aromatic_general is threaded to analyze_cage_universal(..., allow_mancude=...) (plumbing only; the mancude refusal there still fires unconditionally until P2).

: allow_charged (only under complete) lifts the net-charge refusal and emits a charge suffix on a von-Baeyer cage skeletal atom (...pentaen-4-ium); fail-closed otherwise.

orthonym.assembly.general_engine.name_general_monocycle(mol, features, allow_aromatic_general=False, allow_charged=False)

: general LONE-monocycle ring-parent path (opt-in engine only).

Names a molecule whose SENIOR ring system is a single (non-fused) ring – benzene, pyridine, thiophene, imidazole,… – with its substituents coming from the never-None universal recursion (substituent_enumerator.name_substituent) instead of the default composer’s finite per-class vocabulary. That is the root-cause fix for “bare ring names, substituted form abstains.”

The parent ring name + numbering come from the EXISTING lowest-locant machinery (name_heterocycle + orient_heterocycle_with_substituents for heterocycles; benzene/cycloalkane for all-carbon). Fail-closed (returns None) on anything outside this scope; the E1 atom-partition and

OPSIN round-trip are the downstream authorities.

Gated behind allow_aromatic_general – inert (returns None) when the flag is False, so the PIN/default path stays byte-identical.

orthonym.assembly.general_engine.name_general_spiro(mol, features, allow_aromatic_general=False, allow_charged=False)

: general SPIRO ring-parent path (opt-in engine only).

The von-Baeyer cage engine refuses spiro (<2 bridgeheads), so a spiro ring system that the default per-class handlers abstain on (functionalized / mancude / suffix-form PIN) dies at name_general_ring’s cage refusal. This sibling routes the senior spiro ring system through analyze_spiro_universal (audited) and reuses the SAME _emit_ring_from_analysis tail as the cage path. Fail-closed (None) on any non-spiro / unaudited system; the round-trip is the downstream gate.

orthonym.assembly.general_engine.TERMINAL_RING_PARENT_SITE = 'general_engine._name_terminal_ring_parent'

Ledger site id for the parent-hydride tier below. Exported so a test can prove the tier EXECUTED rather than infer it from the emitted string – the emitted string cannot distinguish “this tier built it” from “an existing producer happened to build the same words”.

orthonym.assembly.general_engine.TERMINAL_RING_ASSEMBLY_SITE = 'general_engine._name_terminal_ring_assembly'

Ledger site id for the assembly tier below.

orthonym.assembly.general_engine.name_general(mol, features, allow_aromatic_general=False, allow_suffix_free=False)

engine dispatcher: chain parent -> G1 path, ring parent -> G2 path.

/P1: allow_aromatic_general widens the ring producer – it is threaded to name_general_ring -> analyze_cage_universal (aromatic cages) and enables the general lone-monocycle path (name_general_monocycle). Default False -> byte-identical to pre-P0.

: net charge is lifted ONLY under complete (allow_charged == allow_aromatic_general); the charge becomes a -ylium/-ide/ -uide/-ium suffix on the numbered parent (fail-closed). Under valid / the PIN default (allow_aromatic_general False) charge is still refused -> byte-identical to pre-P5.