Metadata-Version: 2.5
Name: hebrew-num2words
Version: 0.1.0
Summary: Hebrew number-to-words text normalization: digits to spoken Hebrew, with gender agreement, construct forms, clock times, dates, percents and identifiers.
Project-URL: Homepage, https://huggingface.co/notmax123/RenikudPlus
Author: Max Melichov
License: Apache-2.0
License-File: LICENSE
Keywords: g2p,hebrew,nlp,number-to-words,text-normalization,tts
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: Hebrew
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# hebrew-num2words

Turn digits in Hebrew text into spoken Hebrew words. Pure Python, no dependencies.

```bash
pip install hebrew-num2words
```

```python
from hebrew_num2words import normalize_numbers

normalize_numbers("יש לי 3 ילדים")        # יש לי שלושה ילדים
normalize_numbers("יש לי 3 בנות")         # יש לי שלוש בנות
normalize_numbers("המחיר 1250 שקלים")     # המחיר אלף מאתיים וחמישים שקלים
normalize_numbers("נפגשים ב-15 במרץ")     # נפגשים בחמישה עשר במרץ
normalize_numbers("השעה 14:45")           # השעה רבע לשלוש
normalize_numbers("עלייה של 3.5%")        # עלייה של שלושה וחצי אחוז
```

Digit-free text is returned unchanged, byte for byte.

## What it handles

- **Gender agreement with the counted noun** — `8 שעות` → שמונה (feminine), `8 שקלים` → שמונה (masculine); the noun after the numeral decides, which is the part naive expanders get wrong.
- **Construct forms** — `2 ספרים` → שני, `2 מכוניות` → שתי (not שניים / שתיים).
- **Bare numerals** — a count with no noun takes the absolute (feminine) series, except 1 → אחד.
- **Clock times** — `14:45` is spoken 12-hour and feminine, with ורבע / וחצי / רבע ל־ / עשרים ל־.
- **Percents** — `12%` → masculine cardinal + אחוז.
- **Dates** — `3.5.2026` → masculine day + ב+month + feminine year.
- **Identifiers** — phone numbers, ID numbers and codes are read digit by digit.
- **Ordinals and definite forms** — `ה-2` → השני.

## API

```python
normalize_numbers(text: str) -> str          # expand every numeric expression in a sentence
expand_token(token, prev_words=(), next_words=()) -> str
cardinal(n: int, gender: str, construct: bool = False) -> str    # 0..999,999
ordinal(n: int, gender: str, definite: bool = False) -> str
```

`gender` is `MASC` or `FEM`, exported from the package.

## Where the rules come from

Every convention was mined from a 473-row Hebrew↔IPA gold set of spoken numbers, not
hand-invented. On that set the expander takes word error rate from **50.04 to 13.52**.
115 unit tests cover the cases above.

It exists because grapheme-to-phoneme models are typically trained on text that contains
no digits at all, so a digit reaching the model produces guaranteed-wrong output — and
often corrupts the word after it. Normalizing first removes the whole class.

## License

Apache-2.0.
