TransformEngine

Normalize a formula into the canonical form selected by a profile.

The engine runs a multi-phase pipeline (LowerAttributes, a fixed-point Rewrite loop, FinalizeAst, FlattenGroups). A profile picks rule levels; TransformConfig is nested by phase and controls per-run switches without changing the selected rule set. The engine also bundles a parser, so it exposes parse and shares its immutable knowledge_base().

Since 0.4.0 the bundled parser defaults to ParseConfig LENIENT, and TransformConfig is the nested four-phase object (not flat rewrite_enabled / max_iterations keys). Per-call config must be a complete TransformConfig (or ParseConfig on parse); a dict passed as config raises ConfigError. Other keywords are overlays (normalize(src, rewrite={"enabled": False})). Nested overlay values must be dicts, not phase-config class instances. Construct a full object with TransformConfig(...) (all four phases required) or the profile classmethods authoring() / faithful() / corpus() / equiv().

Normalization is gated on a complete tree: an incomplete parse raises ParseError, since normalizing a tree with holes is meaningless. For the conceptual model — profiles, the pipeline, and the eliminated-form contract — see the Transforms guide.

Knowledge-base lookups#

knowledge_base() -> KnowledgeBase

Complete transform configuration, nested by pipeline phase.

Since 0.4.0 this is the only accepted config= type for transform / normalize. A dict passed as config raises ConfigError; use keyword overlays (normalize(src, rewrite={"enabled": False})) or construct this class. The constructor requires all four phase configs; the classmethods authoring() / faithful() / corpus() / equiv() return the defaults a profile actually uses.

The four attributes are shared references: cfg.rewrite.enabled = False is visible through cfg.rewrite.enabled and takes effect when the object is passed as config. Nested overlay values must be dicts, not these phase-config instances.

Complete Rewrite phase configuration.

Nested under TransformConfig.rewrite. Disabling this phase leaves legacy syntax such as \over untouched; it does not change which rule levels the profile selected. Overlay with rewrite={"enabled": False}; do not pass this class as a nested overlay value.

Complete LowerAttributes phase configuration.

This is a nested field of TransformConfig, not a dict overlay. Pass the parent TransformConfig as config; to overlay only this phase use lower_attributes={"enabled": False}. A dict passed as config on transform / normalize raises ConfigError.

Complete FinalizeAst phase configuration.

Nested under TransformConfig.finalize_ast. The phase performs local AST cleanup such as merging adjacent Prime nodes and normalizing text sequences. Overlay with finalize_ast={"enabled": False}.

Complete FlattenGroups phase configuration.

Nested under TransformConfig.flatten_groups. enabled governs whether the phase runs. preserve_rendered_spacing keeps groups whose only public-facing effect is rendered math spacing; it does not control serializer source whitespace (see SerializeOptions). Structural guards stay on even when preserve_rendered_spacing is False. Constructor defaults match the authoring / faithful strict pair (both True); the corpus and equiv profiles leave preserve_rendered_spacing off. Overlay with flatten_groups={"enabled": False}; a dict passed as config still raises ConfigError.

Flat parse+transform overlays for normalize.

Combines ParseOverrides keys with nested phase overlays from TransformOverrides. A dict passed as config still raises ConfigError; these keys are keywords only (normalize(src, rewrite={"enabled": False}, reject_unknown=True)).

Keyword overlays for transform.

Each nested value must be a dict of that phase's overlay keys, not a complete phase-config class instance.

Keyword overlays for the Rewrite phase.

Nested under transform / normalize as rewrite={...}. The nested value must be a dict, not a RewriteConfig instance.

Keyword overlays for the LowerAttributes phase.

Nested under transform / normalize as lower_attributes={...}. The nested value must be a dict, not a LowerAttributesConfig instance.

Keyword overlays for the FinalizeAst phase.

Nested under transform / normalize as finalize_ast={...}. The nested value must be a dict, not a FinalizeAstConfig instance.

Keyword overlays for the FlattenGroups phase.

Nested under transform / normalize as flatten_groups={...}. The nested value must be a dict, not a FlattenGroupsConfig instance.

Text plus the diagnostic report from one explicit normalize report call.

Plain normalize returns the string directly and does not build this object.

Diagnostic report for one explicit report call.

Output text and errors follow the ordinary transform contract. Report fields, phase divisions, and these counters are diagnostic: they are not part of the stable compatibility promise. A disabled phase stays present as zeros or an empty list. The Python report uses snake_case; JavaScript exposes the same data in camelCase.

An unknown input name whose arguments or scope cannot be guaranteed.

The LowerAttributes phase report.

Activity for one (attr, value) pair in LowerAttributes.

Counts of one attribute form, split by carrier.

The Rewrite phase report.

One rewrite rule's outcome for a single call.

The FinalizeAst phase report.

The FlattenGroups phase report.

Flatten actions that changed the tree.

Preserve-guard hits for one FlattenGroups run.

A hit is the first guard branch reached for a group, plus the scripted-base sub-count. command_contact_via_scripted_base is also included in command_contact. These counters are not a partition of preserved groups.

Normalization profile name: "authoring", "faithful", "corpus", or "equiv".