orthonym.routing.dispatcher#

Note

Internal API. Names and behaviour may change between releases.

a phase ClassFirstRouter — dispatch substrate at _name_impl integration site.

Architecture (158-internal notes): - dispatch — two-tier predicate evaluation (Tier-1 mol-only first;

perception ONCE between tiers; Tier-2 features-required last; GENERAL catch-all per). For a phase the perception step lives INSIDE the GENERAL handler’s caller (_name_impl body) per Task 158-02-01 design choice (a) — the dispatcher itself never invokes _perceive directly, preserving routing/ as decoupled from composer.py (boundary).

  • get_dispatch_stats / reset_dispatch_stats — per-instance histogram counter accessor. Per-instance (NOT module-global) per.

  • _invoke_audit_log — ORTHONYM_DISPATCH_AUDIT env-var-gated INFO-level log. Default-OFF preserves stdout-byte-identical canary.

Anti-pattern hygiene (internal notes-CFR.md AP-block): -: silent fallthrough -> GENERAL @ 99999 with lambda *_: True;

impossible-state raises RuntimeError in dispatch (defensive).

-: module-global counter -> counter lives on self._dispatch_stats

per internal notes.

-: routing layer modifies handler output -> dispatcher returns

ClassDispatchResult and lets the caller invoke result.handler(...); it does NOT mutate names.

-: feature-flag-controlled CFR routing path -> NO opt-out flag per

internal notes; CFR is the only routing path post-Phase-158.

Per internal notes honest-fail-on-data: dispatch raises RuntimeError if the GENERAL catch-all is unreachable (impossible by construction; defensive).

class orthonym.routing.dispatcher.ClassFirstRouter(*, _audit_log=None)#

Bases: object

: Class-first dispatcher; replaces the implicit cascade in _name_impl.

Three responsibilities (158-internal notes <domain>):

  1. dispatch — walks DISPATCH_TABLE in priority order; first-match-wins. Returns a frozen ClassDispatchResult whose handler field the caller invokes to produce the name string. The dispatcher does NOT call the handler itself per +.

  2. get_dispatch_stats — per-instance histogram counter accessor. Returns a defensive copy so callers cannot mutate internal state.

  3. reset_dispatch_stats — explicit reset for batch-run boundaries.

Construction: ClassFirstRouter with no args. Reads ORTHONYM_DISPATCH_AUDIT env var by default for the audit-log gate ; the constructor kwarg _audit_log overrides for testing.

STAT_KEYS: tuple = ('salt', 'radical', 'zwitterion', 'anion_retained', 'cation_retained', 'cation_quaternary', 'ester_anion_zwitterion', 'mixed_sign_zwitterion', 'anion_small', 'poly_anion', 'multi_component_neutral', 'multiplicative', 'carbohydrate_lookup', 'natural_product', 'peptide', 'retained_name', 'amino_acid', 'skeletal_replacement', 'cyclophane', 'decomposition_pre_general', 'general', 'inorganic_acid', 'organometallic', 'lipid', 'mononuclear_hydride', 'chalcogen_chain', 'polyazane', 'free_homonuclear_g14_hydride', 'dinuclear_hydride', 'ketene', 'ring_chalcogen_oxide', 'hydro_fused_peroxol', 'thioimide', 'nitramide_substituted', 'cyclic_polyester', 'azinic_derivative', 'heterone', 'sulfine', 'cumulative_zwitterion', 'ylide', 'pseudoketone_hetero', 'acyl_chalcogenchain_pseudoketone', 'lambda5_phosphanimine', 'heteroimine', 'lambda_sulfane_imine_oxide', 'polychalcogen_oxide', 'catenated_hydride', 'heterochalcogen_aba', 'homonuclear_pnictogen_chain', 'pnictogen_carboxylic_acid', 'mononuclear_hydride_added_carbon', 'inositol', 'nucleoside')#
dispatch(mol, smiles, canonical_smiles, features=None, **kwargs)#

: two-tier predicate evaluation; first-match-wins.

Walks DISPATCH_TABLE in priority order (sorted-by-priority). **kwargs is forwarded verbatim to predicate calls so callers can thread _skip_decomposition (option (b)) and _style (RETAINED_NAME / AMINO_ACID predicates) without bloating the ClassDispatchEntry shape.

Returns:

ClassDispatchResult; caller invokes result.handler(...).

Raises:

RuntimeError – if no entry matched (impossible by construction; GENERAL lambda *_: True always matches as the catch-all). Defensive raise per honest-fail-on-data.

Return type:

ClassDispatchResult

get_dispatch_stats()#

: defensive copy of the (StoutClass -> int) histogram.

reset_dispatch_stats()#

: explicit reset for batch-run boundaries.

orthonym.routing.dispatcher.dispatch(mol, smiles, canonical_smiles, features=None, **kwargs)#

module-level wrapper for callers that don’t carry a router instance.

Uses a lazily-initialized module-default router. Per internal notes +, per-instance counters are preferred for telemetry; this convenience wrapper is for one-off non-stat-tracking callers.

orthonym.routing.dispatcher.get_dispatch_stats()#

+: stats from the module-default router.

orthonym.routing.dispatcher.reset_dispatch_stats()#

+: reset module-default router stats.