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->OpenScreechapi->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\nbullet 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¶
- Profiles
- Dictate into Documents
- Data and Output Locations
- In-App Help Cues (? Buttons and Hover Tooltips)
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.