Utterwise 🗣️

Utterwise is a lightweight, deterministic semantic text normalizer for Python voice assistants, TTS apps, tutoring tools, and small voice-agent pipelines.

It exists because compact TTS models often read useful assistant text badly: dates, money, temperatures, URLs, versions, equations, and ambiguous numbers can sound awkward unless the text is normalized before it reaches the speech model.

from utterwise import normalize

normalize("Call 911 if it reaches 25°C on 03/04/2026.")
# "Call nine one one if it reaches twenty five degrees Celsius on third of April twenty twenty six"

📚 Contents

• 📦 Install
• ✨ Why Use Utterwise?
• 🤔 Why Not Regex?
• ✅ Supported Features
• 📖 Usage and Examples
• 🖥️ CLI
• ⚠️ Limitations
• 🛠️ Development

📦 Install

pip install utterwise

Math and LaTeX parser support is optional:

pip install "utterwise[math]"

For local development (with uv):

uv sync --all-extras

✨ Why Use Utterwise?

• Deterministic by design → The same input produces the same output every time.
• Lightweight by default → No heavy NLP dependency is required for the core path.
• Fast detection gate → Processors only run when the text needs them.
• Semantic before speech → Tokens are classified before they are verbalized.
• Context-aware ambiguity handling → 911 can be emergency, flight number, or cardinal.
• Explainable output → Every token can report its rule, confidence, candidates, and span.
• Practical for voice assistants → Covers dates, currency, temperature, URLs, email, math, and more.

🤔 Why Not Regex?

Regex is useful for finding patterns, but speech normalization also needs meaning. The same characters can have different spoken forms depending on context:

Call 911 immediately      -> nine one one
Flight 911 departs at 6   -> nine eleven
911 divided by 3 is 303   -> nine hundred eleven

Utterwise keeps scored candidates, checks nearby words, resolves ambiguity, and then verbalizes the winning interpretation. That is the core difference between a cleanup script and a speech-focused normalizer.

✅ Supported Features

See USAGE.md for API examples, runtime configuration, and CLI output.

🖥️ CLI

utterwise "Call 911 immediately"
utterwise --ssml "hello@example.com"
utterwise --pretty "Python 3.12 costs $12.50"

⚠️ Limitations

• Utterwise is rule-based; confidence scores are rule confidence, not statistical probabilities.
• Slash dates default to day/month/year unless configured as month/day/year.
• SSML output is currently intentionally minimal.
• Policy names are accepted, but style-specific policy output is not implemented yet.
• Locale-specific speech styles, rich SSML policies, and chemistry normalization are planned later.

🛠️ Development

Run tests:

uv run --extra dev pytest
.venv\Scripts\python.exe -m pytest

Run the interactive development menu:

.venv\Scripts\python.exe tests\menu.py