Proto-Language Reconstruction Engine

CL Hackathon — Computational Linguistics Proto-Language Reconstruction

A computational pipeline that reconstructs a proto-language from 7 sister conlangs using the Comparative Method and Optimality Theory (OT). The engine uses Aaruma as its most conservative anchor language, aligns parallel texts across all daughters, builds phoneme correspondence matrices, and synthesises reconstructed proto-forms for two target documents.

---

Quick Start

# 1. Clone the repository
git clone https://github.com/dwinzg/cl-hackathon/
cd cl-hackathon

# 2. Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run the full pipeline
python3 proto_engine.py

Output files are written to the output/ directory.

Reminder: a languages/ folder has to be created and populated with the data

---

Repository Structure

cl-hackathon/
├── proto_engine.py                 # Main pipeline — runs all 3 phases
├── parse_dictionary.py             # Aaruma dictionary parser module
│
├── langauges/                      # Source data (NOT pushed to repo)
│   ├── Aaruma-corpus.txt           #   Full Aaruma corpus (~187KB)
│   ├── dictionary.txt              #   579-entry Aaruma↔English dictionary
│   ├── Nideni Tára.txt             #   Target text 1 (Aaruma)
│   ├── Pózabóza, *.txt             #   Target text 2 (Aaruma)
│   ├── lang{2-7}-corpus.txt        #   Sister language corpora
│   ├── lang{2-7}-doc1.txt          #   Parallel translations of Target 1
│   └── lang{2-7}-doc2.txt          #   Parallel translations of Target 2
│
├── output/                         # Generated output
│   ├── proto_nideni_tara.txt       #   Reconstructed proto-language: Doc 1
│   ├── proto_pozaboza.txt          #   Reconstructed proto-language: Doc 2
│   ├── ot_analysis_nideni_tara.md  #   OT constraint tableaux: Doc 1
│   └── ot_analysis_pozaboza.md     #   OT constraint tableaux: Doc 2
│
├── linguistic_methodology.md       # Plain-language explanation of the method
├── optimality_theory_framework.md  # OT constraint definitions & tableaux
├── ot_constraints_log.md           # Full constraint inventory per language
│
├── requirements.txt                # Requirements
├── .gitignore                      # Excludes venv/, data, and scratch notes
└── README.md                       # This file

What Is Not Tracked by Git

Path	Reason
venv/	Python virtual environment — recreate locally
langauges/	Source language data — provided separately to participants
notes.md	Personal scratch notes
__pycache__/	Python bytecode cache

---

Pipeline Overview

The engine runs in three sequential phases:

Phase 1 — Phonological Parsing & Alignment

• Loads the 579-entry Aaruma dictionary via parse_dictionary.py
• Reads the two Aaruma target texts and their parallel translations in all 6 sister languages
• Tokenises words into phoneme-level units, respecting digraphs (sh, zh, dz, bv, ng, etc.)
• Aligns words positionally across parallel documents (~116 word pairs per language)

Phase 2 — Correspondence Matrix

• For each sister language, builds a phoneme-by-phoneme correspondence matrix (Aaruma rows × sister phonemes columns)
• Identifies systematic sound correspondences via frequency analysis:

Aaruma	Lang2	Lang4	Lang5	Lang7	Proto
/z/	ng	dz	dng	ng	*dz
/v/	bb/gg	bv	bv	vv	*bv
/b/	þ	ð	ngb	ngb	*mb

Phase 3 — Synthesis & Translation

• Applies three reverse sound laws to convert Aaruma → Proto:
  • Aaruma /z/ → Proto *dz (intervocalic and word-initial)
  • Aaruma /v/ → Proto *bv (word-initial before vowels)
  • Aaruma /b/ → Proto *mb (word-initial before vowels)
• Generates proto-language translations of both target texts
• Produces per-word OT analysis documents with constraint tableaux and daughter-language reflexes

---

Output Files

After running python3 proto_engine.py, the output/ directory contains:

File	Description
proto_nideni_tara.txt	Proto-language reconstruction of Nideni Tára (10 lines)
proto_pozaboza.txt	Proto-language reconstruction of Pózabóza (14 lines)
ot_analysis_nideni_tara.md	Full OT tableaux for every word transformation in Doc 1
ot_analysis_pozaboza.md	Full OT tableaux for every word transformation in Doc 2

Sample Output

Aaruma (source):

Vúlunudonu nideni Tára, lízirede vúlunudonu izamimi.

Proto-Language (reconstructed):

Bvúlunudonu nideni Tára, lízirede bvúlunudonu idzamimi.

---

Documentation

Document	Audience	Contents
linguistic_methodology.md	Non-technical	Plain-language walkthrough of the Comparative Method and results
optimality_theory_framework.md	Technical	Formal OT constraint definitions, initial tableaux for Lang2
ot_constraints_log.md	Technical	Complete constraint inventory and rankings for all 7 languages

---

Running Individual Components

# Parse and inspect the Aaruma dictionary
python3 parse_dictionary.py

# Run the full reconstruction pipeline
python3 proto_engine.py

The dictionary parser can also be imported as a module:

from parse_dictionary import parse_dictionary, build_aaruma_to_english

entries = parse_dictionary('langauges/dictionary.txt')
lookup = build_aaruma_to_english(entries)
print(lookup['vúlunu'])  # → [{'english': 'heaven', 'pos': 'NN', ...}]