Metadata-Version: 2.4
Name: phonodist
Version: 0.1.0
Summary: Language-aware, explainable distance metrics for IPA pronunciations.
Author: Holger Nahrstaedt
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/buchwandler/phonodist
Project-URL: Repository, https://github.com/buchwandler/phonodist
Project-URL: Documentation, https://github.com/buchwandler/phonodist/blob/main/docs/METRIC.md
Project-URL: Changelog, https://github.com/buchwandler/phonodist/blob/main/docs/changelog.md
Project-URL: Issues, https://github.com/buchwandler/phonodist/issues
Keywords: ipa,phonetics,phonology,pronunciation,distance,g2p,tts
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_LICENSES.md
Requires-Dist: panphon<0.23,>=0.22.2
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.16; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# phonodist

Language-aware, explainable distance metrics for IPA pronunciations.

`phonodist` compares IPA with IPA. It does not perform grapheme-to-phoneme
conversion or synthesize audio. The initial metric combines Unicode-safe IPA
normalization, segment tokenization, PanPhon articulatory features, weighted
alignment, and sparse language-specific equivalence rules.

## Installation

```bash
pip install phonodist
```

Development dependencies are installed with:

```bash
python -m pip install -e ".[dev]"
```

## Supported profiles

The bundled profile is:

```text
de-DE
```

`de`, `de-DE`, and `de_de` resolve to `de-DE`. Use `language=None` for
universal feature mode without language-specific profile rules.

## Quick start

```python
from phonodist import pronunciation_distance

result = pronunciation_distance(
    "ˈlʊftvafn̩ˌʃtʏt͡spʊŋkt",
    "lˈʊftvˌafənʃtˌʏt\u200dspʊŋkt",
    language="de-DE",
)

print(result.distance)
```

`pronunciation_distance` uses score-only mode by default. Request alignment
operations explicitly with `explain=True`.

## CLI

```bash
phonodist compare de-DE \
  'ˈlʊftvafn̩ˌʃtʏt͡spʊŋkt' \
  'lˈʊftvˌafənʃtˌʏtspʊŋkt' \
  --explain
```

JSON output is available with `--json`, and the package version is available
with `phonodist --version`.

## Strict IPA behavior

PanPhon validates every resulting segment. Unsupported IPA raises
`UnknownSegmentError`, including when an unsupported segment appears on only
one side or is identical on both sides. Unicode format characters such as the
zero-width joiner are ignored during normalization. Stress is intentionally
ignored by `feature-align/1`; retained-stress scoring is not implemented.

## Metric scope and provenance

The MVP score is a phonetic feature distance, not a validated model of human
perceptual similarity. It is intended for deterministic comparison, ranking,
lexicon validation, G2P evaluation, pronunciation regression tests, and
investigation of suspicious pronunciation pairs.

Each result records the metric and metric version, profile and profile version,
and PanPhon backend version and feature set. Consumers such as Lexphon
should define their own thresholds. See [docs/METRIC.md](https://github.com/buchwandler/phonodist/blob/main/docs/METRIC.md) and
[docs/PROFILES.md](https://github.com/buchwandler/phonodist/blob/main/docs/PROFILES.md).

Metric and profile details may evolve during the 0.x series. Changes to metric
semantics require a metric version bump. Language-specific rule or cost changes
require a profile version bump. Documentation and performance fixes that
preserve scores only require a package version change.

## Development

```bash
pytest
ruff check .
mypy phonodist
pre-commit run --all-files
python -m build
```

## Benchmarking

Run the representative throughput benchmark with a small count during development:

```bash
python benchmarks/benchmark_distance.py --count 1000
```

The benchmark compares score-only and explained calls and reports profile load time. Its values are engineering baselines, not calibrated human-perceptual examples. Profile costs remain explicitly tunable parameters until a later calibration study.

## Release publishing

Before pushing a `v0.1.0` tag, configure and verify the PyPI Trusted Publisher for the `pypi` GitHub environment. The publisher must use GitHub Actions OIDC and does not require an API token. See [docs/RELEASING.md](https://github.com/buchwandler/phonodist/blob/main/docs/RELEASING.md).

## License

Apache-2.0. PanPhon is an external MIT-licensed dependency and is not vendored
here. PHOIBLE data is not bundled or copied into this package.
