Polish Whisper Normalizer

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

English | Polski

English

Features

Pipeline (text.py): lower → brackets/parens/ignore → r.→roku → sentence periods/ellipsis → time (Morfeusz) → decimal ,→. → numeral boundaries → remove_symbols(keep=".:/%$€£¢+-") → numbers (Morfeusz) → months (conditional, Morfeusz) → dates → ordinal-dot cleanup. Configurable via PolishTextNormalizer(date_format=...). Diacritic-less ASR (czterdziesci, piec, wpol) handled via utils + Morfeusz.generate.

Installation

uv sync                 # dev + morfeusz2
uv pip install -e .     # editable
# or from PyPI
uv pip install polish-whisper-normalizer
# with jiwer extra
uv pip install "polish-whisper-normalizer[jiwer]"

Requires Python >=3.10, regex, morfeusz2.

Quickstart

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"

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"
# diacritic-less numbers also work
PolishTextNormalizer()("trzysta czterdziesci osiem")  # → "348"

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.

Architecture

src/polish_whisper_normalizer/
  basic.py        # Whisper basic normalizer, diacritics-aware
  lemmatizer.py   # PolishLemmatizer – thin Morfeusz2 wrapper (analyse/generate)
  utils.py        # strip_diacritics, with_ascii_variants – single place for ASCII fallback
  numbers.py      # PolishNumberNormalizer – cardinals/ordinals/currency/percent
  time.py         # PolishTimeNormalizer – HH:MM, wpół/za/po, geographic guard
  text.py         # PolishTextNormalizer – full pipeline: time → numbers → months → dates
  polish.py       # compatibility re-export shim
  jiwer.py        # PolishTransform / wer helper

Declension is never re-implemented: base nominative lexicons are stored, all declined forms are resolved via PolishLemmatizer.analyse and generate (Morfeusz2). ASCII-folded variants are derived once via utils and Morfeusz.generate, so diacritic-less ASR needs no duplicated dictionaries.

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          # 600+ 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              # strict

• 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                 # dev + morfeusz2
uv pip install polish-whisper-normalizer  # z PyPI
uv pip install "polish-whisper-normalizer[jiwer]"  # z jiwer

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"

# bez znaków diakrytycznych też działa
n("trzysta czterdziesci osiem")
# → "348"

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!}