Metadata-Version: 2.4
Name: covtl-sandhi
Version: 0.1.1
Summary: Cross-word sandhi (liaison, raddoppiamento, enlace, encadeamento, Glottalversatz, a-an + onset linking) for the COVTL pipeline languages
Author: covtl-sandhi contributors
License: GPL-3.0-or-later
Project-URL: Upstream, https://github.com/FBerthommier/covtl-pipeline
Keywords: tts,g2p,sandhi,liaison,raddoppiamento,enlace,encadeamento,glottal,sampa,vocal-tract,covtl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# covtl-sandhi — Inter-word Sandhi for the COVTL Pipeline Languages

A standalone package of **inter-word sandhi** rules (the word-boundary
phonological phenomena that a strictly word-by-word g2p cannot produce)
for the six languages of the
[covtl-pipeline](https://github.com/FBerthommier/covtl-pipeline):
**fr, en, it, es, pt, de**. Stdlib only — no pipeline imports, no
dependencies.

| language | phenomenon | example | module |
|---|---|---|---|
| fr | latent consonant (liaison) | "faut il" → `fo.til`, "mon ami" → `mO~.na.mi` | `sandhi/fr.py` |
| en | a→an + onset linking / linking-r | "a apple" → `@.na.p@l`, "far away" → `fa.R@.we` | `sandhi/en.py` |
| it | raddoppiamento sintattico + *euphonic d* | "a casa" → `a.kka.sa`, "e io" → `e.di.o` | `sandhi/it.py` |
| es | enlace + y→e / o→u alternation | "los amigos" → `lo.sa.mi.gos`, "y Ignacio" → `e.i.gna.Tjo` | `sandhi/es.py` |
| pt | encadeamento + EP voicing | "os amigos" → `o.Z@.mi.guS` | `sandhi/pt.py` |
| de | Glottalversatz (anti-liaison) | "ein Apfel" → `ajn a.pf@l` | `sandhi/de.py` |

The synthesis engine is **never** touched: the modules live in the
text/g2p layer, rewrite only the text or the SAMPA, and compose with
the pipeline's expressive prosody patch (the sandhi key is always a
consonant — never a nucleus — so the F0 tiers stay aligned; nothing is
ever inserted across a pause).

---

## Architecture: Branch A (hook) + Branch B (this package)

```
covtl-pipeline                     covtl-sandhi (Branch B)
┌──────────────────────────┐      ┌───────────────────────────┐
│ vtl_synth/utils/sandhi/  │◄─copy─┤ sandhi/  (full rules)      │
│  __init__.py  (STUB)     │  or   │  fr en it es pt de + base │
│  SANDHI_FULL = False     │  pip  │  data/*.txt (views)       │
│  → pure identity         │      └───────────────────────────┘
│  --sandhi/--sandhi-mode  │
└──────────────────────────┘
```

* **Branch A** = the git patch `patch/covtl-pipeline-sandhi-hook.patch`
  (shipped in the zip): it adds to the pipeline the folder
  `vtl_synth/utils/sandhi/` (a **stub**: `SANDHI_FULL = False`, every
  entry point is the identity) plus the `--sandhi`/`--sandhi-mode`
  options. **Without Branch B, the pipeline outputs are
  bit-identical** to those of the unpatched repository — the hook is
  invisible by default (`--sandhi off`). The hook is also **merged
  into the pipeline's `main` branch** (commit `82694bc`): on a recent
  clone the `git apply` step is unnecessary — the install scripts
  detect it ("already applied") and skip it; the patch serves older
  checkouts. It is the pipeline's **single** cross-word-sandhi
  dispatch: the historical 5-language liaison pack (v1–v3,
  `liaison_*` modules) was never merged to `main` and is superseded
  by this package (rule parity archived: 39/39 identical outputs on
  the shared battery).
* **Branch B** = this package: the rules. Two ways to activate it:
  1. **direct copy** (recommended to stay self-contained) — the stub
     folder ALREADY exists, so you copy the CONTENT (note the ``/.``:
     without it, ``cp -r sandhi/ dst/`` would nest the folder one
     level too deep):
     ```bash
     cp -r sandhi/.  <pipeline>/vtl_synth/utils/sandhi/
     ```
     the package overwrites the stub, and the hook finds
     `SANDHI_FULL = True`;
  2. **pip**: `pip install .` — the hook detects `import sandhi`
     (site-packages) if the stub has not been replaced.

The hook resolves in this order: replaced stub (copy) → pip package →
stub (identity + one warning per `run()` if `--sandhi` is requested
without the package).

## Installation

```bash
# 1) fresh pipeline + hook (Branch A)
git clone https://github.com/FBerthommier/covtl-pipeline.git
cd covtl-pipeline
git apply patch/covtl-pipeline-sandhi-hook.patch
pip install -e .                      # (same as for the bare repo)

# 2a) activate the rules: copy the package (Branch B)
#     (the stub folder already exists — copy the CONTENT, note the "/.")
cp -r sandhi/. vtl_synth/utils/sandhi/
# 2b) …or pip
pip install /path/to/covtl-sandhi-v0.1.0
```

Quick test (after 2a/2b):

```bash
vtl-synth run "faut il"   -l fr --sandhi standard --no-video -o out  # fo.til
vtl-synth run "a apple"   -l en --sandhi standard --no-video -o out  # @.na.p@l
vtl-synth run "los amigos" -l es --sandhi standard --no-video -o out # lo.sa.mi.gos
vtl-synth run "os amigos"  -l pt --sandhi standard --no-video -o out # o.Z@.mi.guS
vtl-synth run "ein Apfel"  -l de --sandhi standard --no-video -o out # ajn a.pf@l
```

## Coverage levels (`--sandhi`)

The level is a **monotone filter** over each language's table:
`minimal ⊆ standard ⊆ careful`. It **never changes the phonology** of a
rule that fires — only which pair classes are allowed to fire
(see `sandhi/base.py`).

| level | fr | en | it | es | pt | de |
|---|---|---|---|---|---|---|
| `minimal` | obligatory liaisons: determiners, pronouns, copulas/auxiliaries | a→an | euphonic *d* + monosyllabic RS triggers | y→e, o→u alternations | encadeamento after function words | Glottalversatz after article/determiner |
| `standard` (API default) | + everyday class: adverbs, prepositions, negation, preposed adjectives, modals | + onset linking / linking-r | + full RS: oxytones, come/dove/qualche | + enlace | + encadeamento everywhere (voicing included) | + before any lexical word with vowel onset |
| `careful` | + formal register: liaison after plural noun/adjective (documented -s/-x heuristic) | = standard | = standard | = standard | = standard | + before function words too (hyperarticulation) |

The "= standard" cells are **assumed and documented**: where the
language has no reliable register-dependent rule, `careful` equals
`standard` — never a silent difference.

Defaults: CLI `--sandhi off` (bit-identical), Python API
`level='standard'`. The historical `liaison_*` functions (v1–v3)
called **without** a level reproduce exactly the behavior of the
5-language patch.

## The three modes (`--sandhi-mode`) — the historical implementations, optional

| mode | principle | default |
|---|---|---|
| `g2p` | sandhi-aware gateway: per-word oracle + SAMPA fusion with corrected tokens (recommended, most faithful) | ✔ |
| `post` | pure SAMPA post-processor: the base g2p stays totally untouched | |
| `pre` | orthographic rewrite BEFORE the g2p (most decoupled, least faithful — documented no-op for de/en) | |

## Python API

```python
from sandhi import (SANDHI_LEVELS, sandhi_supported, apply_sandhi,
                    apply_sandhi_text, sandhi_rewrite_text,
                    apply_sandhi_sampa, sandhi_oracle, join_words_keys)

sandhi_supported('fr')                      # True (fr/en/it/es/pt/de)

# gateway over a text (the monotone path — the hook's entry point)
sampa = apply_sandhi_text('fr', 'faut il', g2p, level='standard',
                          mode='g2p')       # 'fo.til'

# low level: per-word keys, AFTER the per-word g2p (fusion into slots)
keys = apply_sandhi('es', ['los', 'amigos'], ['los', 'a.mi.gos'],
                    'standard')             # ['lo', 'sa.mi.gos']
phrase = join_words_keys(keys)              # 'lo.sa.mi.gos' (sep='.')

# expressive path: fusion into an already-planned SAMPA ('%' markers
# present) — never across a pause
sampa2 = apply_sandhi_sampa('fr', 'mon ami', planned_sampa, g2p,
                            level='standard', mode='g2p')

# pre mode alone: the rewritten spelling (to feed the planner)
text2 = sandhi_rewrite_text('en', 'a apple', g2p, 'minimal')  # 'an apple'
```

Each language module additionally exposes the full historical API
(`plan_pairs`, `liaison_oracle`, `apply_liaison_pre`,
`apply_liaison_post`, `liaison_g2p` — v3 signatures + optional
`level`) and the covtl-sandhi aliases (`decide_pair`, `sandhi_g2p`,
`apply_sandhi_pre`, `apply_sandhi_post`, `sandhi_oracle`).

## Editable tables (`sandhi/data/`)

Each file is an **editable view** over one table: one entry per line,
lowercase, `#` comments. If it exists and is non-empty, it replaces the
embedded table; otherwise the default value applies (the package always
stays importable — these files are **not** a dependency).

```
data/fr_h_aspire.txt        aspirated-h words blocking liaison (fr)
data/it_rs_triggers.txt     function-word triggers of raddoppiamento (it)
data/pt_function_words.txt  function words: minimal encadeamento (pt)
data/de_glottal_exempt.txt  function words exempt from the glottal boundary (de)
```

A word ADDED to `it_rs_triggers.txt` is level `standard`; the `minimal`
subclasses are embedded in the modules (see their docstrings).

## Tests

```bash
pip install pytest
python -m pytest tests/ -q
```

The suite is **standalone** (embedded g2p stubs, no pipeline needed):
monotone levels per language, the three modes, invariants (off =
identity, no modification without a pair, never across a pause),
package API, data files, `decide_pair` on all six languages.

## Known limitations (documented in each module)

* **`pre` mode**: partial coverage — fr: no correct fallback spelling
  for "est", "petit", "plus", "vieux"…; de/en: the glottal stop and
  onset linking have NO spelling (no-op with a warning, use g2p/post);
* **sinalefa** (es) / **smoothing** (en): out of scope — vowel fusion
  would delete a syllabic nucleus and misalign the F0 tiers of the
  prosody patch;
* **fr `careful`**: since the noun/verb boundary is not marked in
  writing, liaison after a plural is a closed heuristic (-s/-x,
  excluding verbal endings -es/-ent/-ez/-ons);
* the `en` module follows the pipeline's CMUdict gateway conventions
  (British r already present in the token: `far` → `faR`).

## License

GPL-3.0-or-later — see `LICENSE` (the upstream pipeline is GPL-3.0;
this package derives from it and remains compatible).
