Polish Whisper Normalizer

Polish port of OpenAI Whisper normalizers — keeps ąćęłńóśźż, normalizes numbers/time/currency/dates with Morfeusz2 declensions.

🇬🇧 English | 🇵🇱 Polski

English

Features

Pipeline: lower → brackets/parens → time → decimal ,→.→remove_symbols(keep=".:/%$€£¢+-")→numbers→months (conditional)→dates→ cleanup. Configurable viaPolishTextNormalizer(date_format=...)`.

Installation

uv sync                 # dev + morfeusz2
uv pip install -e .     # editable
# or from PyPI (once published)
uv pip install polish-whisper-normalizer

Requires Python ≥3.10, regex, more-itertools, morfeusz2.

Usage

from polish_whisper_normalizer import PolishTextNormalizer, BasicTextNormalizer

n = PolishTextNormalizer()
n("Było piętnaście po piątej, minus dziesięć stopni.")
# → "było 5:15 -10 stopni"

n("Spotkanie dwudziestego pierwszego maja o piętnastej trzydzieści.")
# → "spotkanie 21.05 o 15:30"   # was "21. 5" before 05.05 fix

n("piątego maja roku dwa tysiące dwudziestego szóstego")
# → "05.05.2026"   # uniform, no trailing "r"

n("5 maja")  # digit day works too
# → "05.05"

n("pięć złotówek, pięć procentów, pół litra, jedna trzecia")
# → "5 zł 5% 0.5 litra 1/3"

# custom date format
PolishTextNormalizer(date_format="%Y-%m-%d")("piątego maja 2026")
# → "2026-05-05"
PolishTextNormalizer(date_format="{day}/{month}/{year}")("piątego maja 2026")
# → "5/5/2026"

# diacritics
BasicTextNormalizer()("Żółć!")  # → "żółć"
BasicTextNormalizer(remove_diacritics=True)("Żółć!")  # → "zolc"

# jiwer WER (words→digits, dates, time normalized before WER)
# pip install polish-whisper-normalizer[jiwer]
import jiwer
from polish_whisper_normalizer.jiwer import wer, PolishTransform, polish_transform
wer("piątego maja 2026", "05.05.2026")  # → 0.0  (raw jiwer.wer → 1.0)
jiwer.wer("piątego maja 2026", "05.05.2026",
          reference_transform=polish_transform,
          hypothesis_transform=polish_transform)  # → 0.0
# custom date_format
wer("piątego maja 2026", "2026-05-05", date_format="%Y-%m-%d")  # → 0.0

Jiwer — WER with Polish normalization

uv pip install "polish-whisper-normalizer[jiwer]"
# or
uv sync --extra jiwer

Without normalization jiwer.wer penalizes piątego maja 2026 vs 05.05.2026 as 100 % error. With PolishTransform they match:

import jiwer
from polish_whisper_normalizer.jiwer import wer, PolishTransform, polish_transform

# helper (recommended) — normalizes both sides with PolishTextNormalizer
wer("piątego maja 2026", "05.05.2026")  # → 0.0
wer("o piątej", "o 5:00")  # → 0.0
wer("pięć złotówek", "5 zł")  # → 0.0

# raw jiwer would be 1.0
jiwer.wer("piątego maja 2026", "05.05.2026")  # → 1.0

# via jiwer transforms (for pipelines)
jiwer.wer("piątego maja 2026", "05.05.2026",
          reference_transform=polish_transform,
          hypothesis_transform=polish_transform)  # → 0.0

# custom date_format is forwarded
wer("piątego maja 2026", "2026-05-05", date_format="%Y-%m-%d")  # → 0.0

# manual Compose
tr = jiwer.Compose([PolishTransform(date_format="%Y-%m-%d"), jiwer.RemoveMultipleSpaces(), jiwer.Strip(), jiwer.ReduceToListOfListOfWords()])
jiwer.wer("piątego maja 2026", "2026-05-05",
          reference_transform=tr, hypothesis_transform=tr)  # → 0.0

PolishTransform wraps PolishTextNormalizer (date_format kwarg supported) and returns str; polish_transform is the ready Compose ending with ReduceToListOfListOfWords required by jiwer.wer.

from polish_whisper_normalizer import PolishNumberNormalizer, PolishTimeNormalizer, PolishLemmatizer

PolishNumberNormalizer()("dwudziestu pięciu złotych")  # → "25 zł"
PolishTimeNormalizer()("wpół do ósmej")  # → "7:30"
PolishLemmatizer().analyse("dwudziestu")  # → [("dwadzieścia","num")]

API Docs

Full API: neonfeline.github.io/polish-whisper-normalizer (mkdocs serve locally).

Development

uv sync --group dev
uv run pytest -q          # 486 tests
uv run mypy src           # strict, py.typed
uv run ruff check src tests && uv run ruff format --check src tests
uv build
mkdocs serve

• py.typed + mypy --strict (warn_unused_ignores=false)
• ruff + pre-commit + GitHub Actions (ci.yml: lint → mypy → pytest --cov → build)
• Validated on BIGOS v2 + PELCRA (2397 samples, ~5 % number words)

License

MIT — see LICENSE (inherits Whisper MIT for basic.py).

Polski

Funkcje

Potok: lower → czas → liczby → miesiące (warunkowo) → daty.

Instalacja i użycie (PL)

uv sync

from polish_whisper_normalizer import PolishTextNormalizer
n = PolishTextNormalizer()  # date_format="{day:02d}.{month:02d}.{year}" domyślnie

n("piątego maja roku dwa tysiące dwudziestego szóstego")
# → "05.05.2026"  # jednolicie, bez "r"

n("5 maja")  # też działa
# → "05.05"

# własny format daty
PolishTextNormalizer(date_format="%Y-%m-%d")("piątego maja 2026")
# → "2026-05-05"

maja jako imię Maja zostaje maja (nie 5), na północ nie staje się 0:00.

Jiwer — WER po polsku

uv pip install "polish-whisper-normalizer[jiwer]"

from polish_whisper_normalizer.jiwer import wer
wer("piątego maja 2026", "05.05.2026")  # → 0.0  (bez normalizacji 1.0)
wer("o piątej", "o 5:00")  # → 0.0

Rozwój / testy

Jak wyżej — uv run pytest, mypy, ruff, mkdocs serve.

_{Made for BIGOS / Whisper WER — PRs welcome!}