Metadata-Version: 2.5
Name: khmer-g2p
Version: 0.1.0
Summary: Khmer grapheme-to-phoneme: convert Khmer words to their NCKL Khmer-script respelling
Project-URL: Homepage, https://github.com/PhonSobon/Khmer-pronunciation
Project-URL: Model, https://huggingface.co/phonsobon/khmer-g2p
Author: PhonSobon
License-Expression: MIT
License-File: LICENSE
Keywords: cambodia,g2p,khmer,nlp,pronunciation
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: safetensors>=0.4
Requires-Dist: torch>=2.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# Khmer Pronunciation (G2P)

A small Transformer (7.5M parameters) that converts Khmer words to their NCKL Khmer-script
respelling, with `-` between syllables:

    ក្របី → ក្រ-បី

Training data: [phonsobon/khmer-G2P](https://huggingface.co/datasets/phonsobon/khmer-G2P).
Trained model: [phonsobon/khmer-g2p](https://huggingface.co/phonsobon/khmer-g2p)
(83.2% word accuracy, 4.2% character error rate on the test split).

## Install

```bash
pip install khmer-g2p
```

```bash
khmer-g2p ក្របី កម្ពុជា          # ក្របី  ក្រ-បី / កម្ពុជា  កាំ-ពុ-ជា
```

```python
from khmer_g2p import KhmerG2P
g2p = KhmerG2P()                 # downloads the model from the Hub on first use
g2p("ក្របី")                     # 'ក្រ-បី'
g2p(["សម្ដេច", "កម្ពុជា"])        # list in, list out
```

## Train on Google Colab

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PhonSobon/Khmer-pronunciation/blob/main/colab_train.ipynb)

Choose **Runtime → Change runtime type → GPU**, then run the cells in order.

## Train locally

```bash
pip install -r requirements.txt
python g2p/prepare_data.py               # writes g2p/data/{train,validation,test}.tsv
python g2p/train.py --epochs 100         # best model -> g2p/checkpoints/best.pt
```

Options: `--batch 256`, `--lr 5e-4`, `--eval-every 5`, `--patience 4` (stop after this many
validation checks without improvement).

## Use the training checkpoint directly

```bash
python g2p/predict.py ក្របី កម្ពុជា
```

```python
from predict import KhmerG2P   # run from inside g2p/
g2p = KhmerG2P()
g2p("ក្របី")                  # 'ក្រ-បី'
g2p(["សម្ដេច", "កម្ពុជា"])     # list in, list out
```

## Release

```bash
pip install -e ".[dev]"
python scripts/push_to_hub.py            # g2p/model/best.pt -> safetensors -> phonsobon/khmer-g2p
python -m pytest tests                   # tests the model on the Hub
python scripts/evaluate.py               # word accuracy on the test split
python -m build && twine upload dist/*   # publish to PyPI (bump __version__ first)
```
