---
language:
  - ett
  - la
license: apache-2.0
library_name: sentence-transformers
tags:
  - sentence-transformers
  - cross-lingual
  - low-resource-nlp
  - ancient-languages
  - etruscan
  - epigraphy
  - LoRA
  - LaBSE
  - XLM-R
base_model: sentence-transformers/LaBSE
datasets:
  - Eddy1919/openetruscan-corpus
metrics:
  - precision-at-k
  - cosine-similarity
# No model-index block, deliberately. The v4 (LoRA-adapted) adapter has NOT
# yet been evaluated. The only numbers we have are the LaBSE BASELINE column
# of rosetta-eval-v1 (see the Evaluation section below), and those belong to
# LaBSE, NOT to this adapter. A model-index would let the HF UI attribute
# LaBSE's scores to etr-lora-v4, which would be false, and the Hub validator
# rejects a model-index whose results carry no metrics. The v4 result rows
# will be added after WBS tasks T2.3 (ingest v4 vectors behind a feature
# flag) and T2.4 (run the head-to-head eval) land in prod and the benchmark
# gains its v4 row.
---

# etr-lora-v4: Etruscan-side LoRA adapter for LaBSE


## TL;DR

`etr-lora-v4` is a **LoRA adapter** that fine-tunes the **Etruscan-side
vocabulary projection** of a multilingual encoder (XLM-R-base, with
LaBSE as the cross-lingual anchor on the Latin/Greek side) so that
Etruscan words land in the same 768-dim semantic space as the rest of
the multilingual vocabulary. The system is evaluated against held-out
Etruscan ↔ Latin equivalences drawn from the philological literature
(Bonfante & Bonfante 2002, Wallace 2008, Pallottino 1968), exposed
through the `rosetta-eval-v1` frozen benchmark.

The pipeline is designed for **semantic-neighbourhood retrieval over a
low-resource, undeciphered ancient language**, not lexical-equivalence
translation. See *Limitations* before you cite the numbers.

## Intended use

- **Cognate / loanword detection.** Given an Etruscan word, find
  orthographically- or semantically-similar Latin or Greek words.
  Useful for spotting Etruscan→Latin borrowings (e.g. `histrio`,
  `popa`, `subulo`, `satura`).
- **Theonym and place-name alignment.** Etruscan deity and place
  names were often Latinised by Roman authors with regular sound
  correspondences. For Latinised theonyms/place-names, orthographic
  neighbours are sometimes recovered (`menrva→minerva`,
  `hercle→hercules`, `fanu→fanum`; theonym field@10 ≈ 0.33, n=3);
  treat as suggestive, not reliable.
- **Within-language semantic-field exploration.** For an Etruscan
  query, the system returns Latin words with related meanings even
  when the exact target lemma is wrong (e.g. `papa→[papa, daddy,
  pater]`).
- **Multilingual nearest-neighbour browsing.** The storage / API
  layer is designed to accept other ancient languages (Phoenician,
  Faliscan, Oscan) in future; no non-Etruscan corpus is currently
  ingested or served.

## Out of scope

- **Mechanical Etruscan → Latin translation.** Lexical equivalence
  between *unrelated* surface forms (`clan → filius`, `puia → uxor`,
  `lautn → familia`) is **not** in the model, and no amount of
  pooling, centering, or LoRA fine-tuning recovers signal that was
  never in the training corpus.
- **Decipherment of unknown Etruscan words.** Top-k results will be
  orthographic and semantic neighbours of the source surface form,
  not authoritative semantic equivalents.
- **An Etruscan dictionary.** This is not a dictionary. We make no
  such claim. The output is a ranked shortlist for downstream
  philological judgement, not a translation.

## How to use

### From `sentence-transformers`

```python
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("Eddy1919/etr-lora-v4")
embeddings = model.encode(["fanu", "avil", "clan"])
# embeddings.shape == (3, 768)
```

## Training data

Derived from the **OpenEtruscan corpus v1** (Zenodo DOI
[10.5281/zenodo.20075836](https://doi.org/10.5281/zenodo.20075836)):

- **6,633 unified inscriptions**, drawn primarily from the *Larth
  Dataset* (Vico & Spanakis 2023; ~71% of rows)
- **~8,905 unique Etruscan tokens** on the source side after
  divider-normalisation (see *Training procedure* below).
- No primary-source-attested anchors are used in training, only the
  raw transcriptions. The Bonfante / Wallace / Pallottino
  equivalences are held out for evaluation in `rosetta-eval-v1`.

Upstream provenance chain is documented in
[`research/BIBLIOGRAPHY.md`](https://github.com/Eddy1919/openEtruscan/blob/main/research/BIBLIOGRAPHY.md).

## Training procedure

LoRA over **XLM-R-base** (768-dim hidden), trained on Vertex AI in
the `openetruscan-rosetta` GCP project.

- **Output adapter:** `gs://openetruscan-rosetta/adapters/etr-lora-v4/`
- **Re-embedded Etruscan vocabulary:**
  `gs://openetruscan-rosetta/embeddings/etr-xlmr-lora-v4.jsonl`
  (8,905 rows × 768 dim).
- **Etruscan-side preprocessing:** word-divider normalisation
  (`:` and `·` → space, per Bonfante 2002 §10), preserving `.`
  (intra-word phonological marker) and `-` (compounding marker).

Hyperparameters (matching the v3 → v4 recipe in
`scripts/training/vertex/submit_etr_lora_v4.sh`):

| Hyperparameter | Value |
|---|---|
| Base model | `xlm-roberta-base` |
| Epochs | 5 |
| Learning rate | 5e-4 |
| Batch size | 16 |
| Max length | 64 tokens |
| LoRA r | 8 |
| LoRA alpha | 16 |
| LoRA dropout | 0.1 |
| Target modules | `q_proj`, `v_proj` |
| Seed | 42 |
| Hardware | 1× NVIDIA T4 (Vertex AI `n1-standard-8`) |
| Wall time | ~30–60 min |
| Compute cost | ~$0.40 USD |

The training recipe (and divider-normalisation function) is in
[`scripts/training/vertex/train_etruscan_lora.py`](https://github.com/Eddy1919/openEtruscan/blob/main/scripts/training/vertex/train_etruscan_lora.py).
The only delta from v3 is the corpus input
(`etruscan-prod-rawtext-v3.jsonl`, the cleaner V3 corpus produced
after `normalize_inscriptions.py` removed Cyrillic / Latin-Ext-B
mirror-glyph corruption and unified sibilant variants σ/ś/š/ς → SAN).

## Evaluation

All numbers below are from the first frozen run of `rosetta-eval-v1`,
committed at
[`eval/rosetta-eval-v1-20260510T210124Z.json`](https://github.com/Eddy1919/openEtruscan/blob/main/eval/rosetta-eval-v1-20260510T210124Z.json).
**The `model` column reflects the LaBSE baseline that prod was serving
at the time of the run.** The v4 column will be added when T2.3 lands
v4 vectors in prod and T2.4 runs the head-to-head.

### Headline numbers: 22-pair test split

| Metric | random | Levenshtein | LaBSE (current prod) | v4 (after T2.3 / T2.4) |
|---|---:|---:|---:|---:|
| Strict-lexical precision@10           | 0.0002 | 0.000 | **0.0625** | _to be added_ |
| Semantic-field precision@10           | 0.0081 | 0.000 | **0.1875** | _to be added_ |
| Coverage@cos≥0.50                     | 0.000  | 0.955 | **1.000**  | _to be added_ |
| Coverage@cos≥0.70                     | 0.000  | 0.273 | **1.000**  | _to be added_ |
| Coverage@cos≥0.85                     | 0.000  | 0.091 | **0.6875** | _to be added_ |
| n evaluated (of 22)                   | 22     | 22    | 16         | _to be added_ |
| n skipped (OOV on the source side)    | 0      | 0     | 6 (27.3%)  | _to be added_ |

### Per-confidence breakdown (LaBSE column)

| Confidence | n | strict @10 | field @10 |
|---|---:|---:|---:|
| high   | 10 | 0.100 | 0.200 |
| medium | 6  | 0.000 | 0.167 |

### Per-category breakdown (LaBSE column, field@10)

| Category   | n | field @10 |
|---|---:|---:|
| kinship    | 3 | 0.333 |
| theonym    | 3 | 0.333 |
| onomastic  | 2 | 0.500 |
| religious  | 2 | 0.000 |
| time       | 2 | 0.000 |
| numeral    | 3 | 0.000 |
| verb       | 1 | 0.000 |

The strict-lexical metric measures something the system *cannot* do
without parallel-data supervision; the semantic-field metric measures
what it *can* do, and is the honest reflection of the system's actual
research utility. Both are reported side-by-side for historical
comparability.

For the full reproducibility manifest (pinned commit hashes, Latin
vocab snapshot, baseline math), see
[`research/notes/reproduce-rosetta-eval-v1.md`](https://github.com/Eddy1919/openEtruscan/blob/main/research/notes/reproduce-rosetta-eval-v1.md).

## Limitations

Honesty matters more here than marketing:

1. **Small held-out test split (n=22 pairs).** Confidence intervals
   are correspondingly wide. RG.4 in the evaluation roadmap adds
   95%-bootstrap CIs to every reported number; until that lands,
   treat single-decimal-point differences between models as noise.
2. **27% OOV rate on the source side.** 6 of the 22 test-split pairs
   are skipped by the model because the Etruscan token has no vector
   in `language_word_embeddings`. The other two baselines (random,
   Levenshtein) evaluate all 22. Comparisons are accordingly *not*
   apples-to-apples without per-pair pairing.
3. **No primary-source-attested anchors used in training.** The
   evaluation set is itself the philological consensus. Any training
   signal that pushed precision up (short of genuinely parallel data,
   which we do not have) would be reflecting that same consensus back at
   us. Work-package P4 (primary-source mining) is the route out.
4. **Philological consensus reflects a school.** The Bonfante &
   Bonfante / Wallace / Pallottino reading is one school's best
   reading. Categories like `verb` (n=1) and `time` (n=2) are
   under-represented; the per-category breakdown above is indicative,
   not authoritative.
5. **Cross-language semantic alignment for unrelated surface forms
   remains weak.** `clan → filius`, `puia → uxor`, `lautn → familia`
   are misses by design; there is no signal in the training corpus
   that these are equivalent.

## Citation

If you use this model, please cite both the software/dataset DOI and
the model directly:

```bibtex
@software{openetruscan_2026,
  author    = {Panichi, Edoardo},
  title     = {{OpenEtruscan: open-source digital corpus platform for Etruscan epigraphy}},
  year      = {2026},
  version   = {1.3.1},
  doi       = {10.5281/zenodo.20075836},
  url       = {https://doi.org/10.5281/zenodo.20075836},
  publisher = {Zenodo}
}

@misc{openetruscan_etr_lora_v4_2026,
  author       = {Panichi, Edoardo},
  title        = {{etr-lora-v4: Etruscan-side LoRA adapter for LaBSE / XLM-R}},
  year         = {2026},
  publisher    = {Hugging Face},
  howpublished = {\url{https://huggingface.co/Eddy1919/etr-lora-v4}},
  note         = {Evaluated against the rosetta-eval-v1 frozen benchmark.}
}
```

The frozen reference benchmark is `rosetta-eval-v1`; full reproduction
instructions live in
[`research/notes/reproduce-rosetta-eval-v1.md`](https://github.com/Eddy1919/openEtruscan/blob/main/research/notes/reproduce-rosetta-eval-v1.md).

## License

**Apache 2.0**, matching the model-artifact licensing scheme of the
OpenEtruscan repository (code: MIT, data: CC BY 4.0, models:
Apache 2.0).

## Acknowledgements

- Vico, A. and Spanakis, G. (2023). *Larth Dataset*: primary source
  for ~71% of the unified corpus.
- Compilers of the *Corpus Inscriptionum Etruscarum* (CIE Vol. I),
  source of the remaining ~29%.
- Bonfante, G. and Bonfante, L. (2002). *The Etruscan Language: An
  Introduction*, 2nd edition.
- Wallace, R. E. (2008). *Zikh Rasna: A Manual of the Etruscan
  Language and Inscriptions*.
- Pallottino, M. (1968). *Testimonia Linguae Etruscae*.
- Feng et al. (2020). *LaBSE: Language-agnostic BERT Sentence
  Embedding*: the cross-lingual anchor.
- The Pelagios Network, the EpiDoc community, and the Classical
  Language Toolkit.