Skip to content

Word Replacement Libraries

What This Feature Does

Word Replacement Libraries provide deterministic text normalization rules that run before optional LLM processing.

Design Rationale

Rule-based replacement exists because not all cleanup should be delegated to a model. Deterministic rules are:

  • fast
  • explainable
  • testable
  • stable over time

This makes them ideal for terminology normalization, punctuation aliases, and workflow-specific cleanup.

Rule Fields Explained

Field Meaning Typical Use
Source Phrase to match open screech
Replacement Text to inject OpenScreech
Enabled Include/exclude rule Temporary A/B testing
Case sensitive Match exact casing only Protecting proper nouns
Remove whitespace before/after match Trim adjacent spaces near match boundary Spoken punctuation cleanup
Remove characters before/after match Remove configured contiguous character set around match Removing wrappers like quotes/brackets
Surrounding characters to remove Character list used by the char-removal toggles "'()[] style wrappers

Execution Model

  • Rules run as preprocessing before LLM.
  • Only enabled rules are applied.
  • Libraries are shared assets assigned to profiles.
  • Profiles can turn replacement on/off independently even when a library is assigned.

Transformation Examples

Example 1: Acronym and Product Name Cleanup

Input text:

open screech api key rotation plan

Rules:

  • open screech -> OpenScreech
  • api -> API

Output text:

OpenScreech API key rotation plan

Example 2: Spoken Structure Helpers

Input text:

release notes new paragraph bullet point improved startup time

Rules:

  • new paragraph -> \n\n
  • bullet point -> -

Output text:

release notes

- improved startup time

Library Strategy

Strategy Why It Works
One library per domain Keeps legal/medical/dev jargon separated
Prefer small explicit rules first Reduces unintended replacements
Promote common rules into shared baseline library Avoids repeated maintenance

Example Library Patterns

Library Focus Sample Rules
General Cleanup Common speech cleanup um removal, brand casing
Engineering Terms Technical vocabulary normalization api -> API, llm -> LLM
Publishing Output formatting helpers new paragraph -> \n\n, bullet point -> -

Import/Export and Portability

Libraries can be imported/exported as JSON. Imported IDs are normalized to avoid collisions, which supports merging libraries from multiple sources.

Managing Libraries and Rules

In Word Replacement Libraries..., you can:

  • Add library
  • Delete library (if more than one exists)
  • Import selected libraries
  • Export selected libraries
  • Add/remove rules inside each library
  • Enable/disable each rule

Beginner recommendation:

  • Keep one small baseline library first.
  • Add rules only when a real repeated problem appears.

Common Pitfalls

Pitfall Outcome Fix
Over-broad source phrase Unintended replacements inside larger words/phrases Make source more specific
Aggressive surrounding char removal Deletes punctuation you wanted to keep Narrow character list and disable one side
Putting semantic rewrites here Hard-to-maintain large rule set Move semantic transformation into LLM stage

Validation Checklist

  • High-frequency domain terms normalize correctly.
  • Rules do not over-match ordinary prose.
  • Cleanup toggles only affect intended boundaries.

In-App Help Cues For This Feature

In Word Replacement Libraries..., use the ? icons for:

  • match behavior
  • case sensitivity implications
  • surrounding cleanup semantics (including contiguous character behavior)

Quick Tips

  • Put stable names, acronyms, and punctuation aliases in word replacements before asking an LLM to format the text. The model then receives cleaner, more consistent input.
  • Surrounding-character removal consumes only configured characters next to a match. Start with a narrow character set because broader cleanup can remove punctuation you intended to keep.

See Also

Visual Notes

  • TODO: add screenshot of rule table including cleanup options.
  • TODO: add screenshot comparing before/after text for a rule set.
  • TODO: add GIF editing a rule and testing via dictation.