Metadata-Version: 2.4
Name: wolof-numbers
Version: 0.2.1
Summary: Wolof numeral and currency phrase parser (range 1 to 1,000,000,000)
Project-URL: Homepage, https://github.com/kuma-labs/wolof-numbers
Project-URL: Repository, https://github.com/kuma-labs/wolof-numbers
Project-URL: Changelog, https://github.com/kuma-labs/wolof-numbers/blob/main/CHANGELOG.md
Author: Kuma Labs
License: MIT
License-File: LICENSE
Keywords: nlp,numerals,parser,senegal,west-africa,wolof
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.9
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# wolof-numbers

Wolof numeral and currency phrase parser. Parse Wolof cardinal numbers from 1 to 1,000,000,000
and currency phrases in XOF/FCFA/CFA. MIT-licensed, PyPI-published as v0.1.0.

## Install

```bash
pip install wolof-numbers
```

## Quick Start

```python
from wolof_numbers import parse_number, parse_currency_amount, parse_strict

# Cardinal number
result = parse_number("ñaar junni")
print(result.value)       # 2000
print(result.confidence)  # 1.0

# Strict parsing (returns int, raises on ambiguity)
value = parse_strict("ñaar junni")
print(value)  # 2000

# Currency phrase
amt = parse_currency_amount("ñaar junni franc CFA")
print(amt.amount)    # 2000
print(amt.currency)  # "XOF"
```

## Supported Range

| Range | Status |
|-------|--------|
| 1 – 9 (ones) | Supported |
| 10 – 99 (tens) | Supported |
| 100 – 999 (hundreds) | Supported |
| 1,000 – 99,999 (thousands) | Supported |
| 100,000 – 999,999 | Supported |
| 1,000,000 – 1,000,000,000 | Supported |

## Supported Forms

- **Cardinals only** in v0.1.0 — `benn` (1), `ñaar` (2), … `juróom-ñaar` (7), `fukk` (10), `téeméer` (100), `junni` (1000)
- **Wolof↔French code-switching** — `ñaar mille francs` is parsed as 2000 XOF
- **Diacritic-insensitive input** — `naar`, `NAAR`, `ñaar` all resolve to canonical `ñaar`
- **~100 orthographic aliases** covering regional variants (Lebu, Saloum-Saloum, Northern cluster) and common ASR transcript variants

## Known Limitations (v0.2 targets)

| Form | Example | v0.1.0 Behavior |
|------|---------|-----------------|
| Ordinals | `ñaaréél` (second) | Raises `UnsupportedNumeralForm(kind="ordinal")` |
| Fractions | `genn ci ñaar` (one-half) | Raises `UnsupportedNumeralForm(kind="fraction")` |
| Arabic loanwords | `alfu` (1000) | Raises `UnsupportedNumeralForm(kind="loanword")` |

## Stability

`v0.x.y`: public API is committed-to; internals are not. Breaking changes to the public API
will bump to `0.(x+1).0` with a migration note in CHANGELOG.

The public API surface consists of: `parse`, `parse_strict`, `parse_number`,
`parse_currency_amount`, `normalize`, `ParseResult`, `AmountResult`, `Interpretation`,
`AmbiguityError`, `UnsupportedNumeralForm`.

## Linguistic Source

The cardinal numeral system is based on **Guérin 2021** (Constance Guérin's linguistic
research on Wolof numerals) and supplemented by [jangawolof.org](https://www.jangawolof.org).

## Contributing

Non-developers can extend the alias table by editing
`wolof_numbers/data/aliases.yaml` — no Python knowledge required. Each entry maps a
canonical Wolof orthography to a list of accepted variants. Open a PR with new variants
and a usage example.

## License

MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Kuma Labs.
