accentuk

The offline Python package. The Docker service (stress API, lexicon database, TTS frontend, UI) is vacuum-in/accentuk-api.

Offline Ukrainian stress marking and TTS text verbalization powered by a memory-mapped MARISA lexicon and deep neural disambiguation.

accentuk runs completely locally without network calls at inference time. It offers two first-class operational modes: Light (CTranslate2 INT8 quantized, ~150 MB RAM, ultra-low latency) and Full (PyTorch FP32 + spaCy TRF + learned Combiner, maximum ensemble coverage).

---

Operating Modes: Light vs. Full

---

Installation

pip install accentuk

Optional TTS verbalization support:

pip install "accentuk[tts]"

---

Quick Start (Python API)

1. Stress Marking (Accentor)

from accentuk import Accentor

# Light mode: fast CTranslate2 INT8 models, low memory footprint
with Accentor(mode="light") as engine:
    result = engine.stress("Старовинний замок стоїть на горі.")
    print(result.text)  # "Старови́нний за́мок стої́ть на горі́."
    for token in result.tokens:
        print(f"{token.text} -> {token.output_text} ({token.status})")

# Full mode: PyTorch FP32 models + spaCy TRF + Combiner
with Accentor(mode="full") as engine:
    result = engine.stress("Старовинний замок стоїть на горі.")
    print(result.text)

# Auto mode (default): uses Light if CT2 models exist, otherwise Full/Dictionary
with Accentor(mode="auto") as engine:
    result = engine.stress("Мої сестри.")
    print(result.text)  # "Мої́ се́стри."

2. TTS Normalization & Stress Marking (Frontend)

Normalizes dates, numbers, currencies, abbreviations, and symbols, then applies stress marks:

from accentuk import Frontend

# Light mode: span verbalization + Light stress marking
with Frontend(mode="light") as frontend:
    result = frontend.prepare("Вона купила 25 яблук за 150 грн 3 квітня 2024 року.")
    print(result.text)

# Full mode: the same verbalizer + Full stress marking
with Frontend(mode="full") as frontend:
    result = frontend.prepare("Вона купила 25 яблук за 150 грн 3 квітня 2024 року.")
    print(result.text)

---

CLI Usage

Downloading Model Assets

Download the appropriate bundle for your target environment:

# Download Light assets (~425 MB CT2 INT8 models + lexicon)
accentuk download --light

# Download Full assets (~2.2 GB PyTorch weights + spaCy TRF + lexicon)
accentuk download --full

# Download with TTS verbalizer included
accentuk download --light --tts
accentuk download --full --tts

Stress Marking from CLI

# Stress plain Ukrainian text using Light mode
accentuk stress "Він відчинив замок ключем." --mode light   # Він відчини́в замо́к ключе́м.

# Stress using Full mode
accentuk stress "Він відчинив замок ключем." --mode full

# Process text from standard input
echo "Мої сестри." | accentuk stress --mode light

TTS Normalization from CLI

accentuk prepare "О 7:45 ранку 3 квітня потяг № 12 прибув до Києва." --mode light

---

Accuracy

Measured on 2026-10-13 with the same benchmarks as the service (vacuum-in/accentuk-api), word accuracy:

The lexicon accentuk download installs (lexicon-v2, built from the public data-v2 of accentuk-api) is the service's, including the 51,298-word dictionary of stress heard in recordings; the light-mode column was measured on a clean download of it.

Full mode gives the service's answers. Light mode differs on 34 lang-uk tokens: 18 where the small spaCy tagger parses differently from the transformer one, the rest from INT8 quantization (the INT8 cross-encoder picks another reading than FP32 on 2.1% of targets; its margins track FP32 with r = 0.984, so the served threshold 0.5 is kept).

---

Benchmark Results

Evaluated on AMD EPYC / Intel Xeon CPUs with single-thread and batched execution:

Verbalizer

The default verbalizer (from 0.3) is aloudreader/marian-uk-verbalizer-spans-ct2-int8, a 52.7M-parameter Marian model that reads one span at a time: the parts of a sentence that may need reading (numbers, dates, money, units, Roman numerals, abbreviations, Latin words, symbols, footnote marks) are found from the shape of the characters (accentuk.spans), the model sees the sentence with one span marked and writes only that span, and everything outside the spans is copied from the input. Ordinary prose is never rewritten, and footnote marks ("Жид[93]") are not read. Spoken match (case and punctuation are not heard):

Known weak spots: numbers written with irregular grouping ("1111 386,40" is read as two numbers), Roman numerals in running text, and Latin words the model has not seen. The Gemma verbalizer of 0.2 still loads from an existing bundle (ct2_models/gemma-verbalizer-ct2-int8); it is no longer downloaded.

---

Disambiguation Pipeline

When a word has multiple possible accents (heteronym), accentuk resolves stress through sequential tiers:

1. Memory-Mapped Lexicon: Exact form lookup via MARISA Trie (lexicon.marisa).
2. Capitalization & Proper Noun Rules: Differentiates names and toponyms (e.g. Розді́л vs. ро́зділ).
3. Prepositional Pronoun Shift: Shifts accent to the first syllable after governing prepositions (e.g. без ньо́го, до ме́не).
4. Contextual Cross-Encoder: Evaluates sentence context against candidate senses (aloudreader/uk-stress-crossencoder).
5. Token Classifier: Direct sequence labeling trained on audiobook audio alignment (aloudreader/uk-stress-token-classifier).
6. Morphology & Agreement Rules: Grammatical tags and case/number agreements (spaCy TRF in Full mode).
7. Dictionary Defaults & Fallbacks: Trie defaults, compound splitting (пшенично-житній), and analogy-based suffix tables.

---

License

Apache-2.0. See LICENSE and NOTICE.md for third-party component licenses and dataset attributions.