Mova0.5 pre-release⌕
☰
home / docs / languages / Ancient Hebrew / 13. Biblical Hebrew in Mova: the tools

13. Biblical Hebrew in Mova: the tools

This chapter gathers in one place what the other chapters say piece by piece: which of Mova's tools read Ancient Hebrew, what they produce, how they render each construction of the grammar, how well they do it (measured, with dates), and where they stop. Everything here can be run from the repository; the data lives under $MOVA_DATA, never in git.

Contents

  1. The pipeline at a glance
  2. The source: MACULA Hebrew
  3. The trees: macula and its CoNLL-U
  4. Tokens: what a "word" is
  5. FEATS and MISC
  6. The relations: head rules and the UD conventions for Hebrew
  7. Measured against UD Ancient Hebrew PTNK
  8. The pragmatics: macula prag
  9. The dictionary: macula dict
  10. The Torah course and the parse database
  11. The yetzirah crate
  12. A construction-by-construction map
  13. Known defects of the data
  14. Gaps and next steps
  15. Sources

1. The pipeline at a glance

MACULA Hebrew lowfat XML (CC BY 4.0)
   │  macula <lowfat-dir> <out-dir> GEN,EXO,LEV,NUM,DEU
   ▼
torah-wlc-macula/{GEN,EXO,LEV,NUM,DEU}.conllu + verses.tsv          ← trees (hbo)
   │                    │                         │
   │ macula prag        │ macula dict             │ macula compare (PTNK, NC, a measure only)
   ▼                    ▼                         ▼
hbo-prag.tsv         dict/torah-en.tsv(.examples)  UAS/LAS on test and dev
   │
   ▼
parsedb-hbo/ (seed trees + prag for the cycle)   world/data/school/torah/*.lesson (the Torah course)

Three things are worth stating at the start, because they decide how far any claim in this manual about "what Mova knows" can go:

Every step is deterministic: two runs give the same files byte for byte (tools/macula/README.md, measured 2026-10-17).

2. The source: MACULA Hebrew

MACULA Hebrew (Clear Bible / Biblica, with the J. Alan Groves Center's Westminster Hebrew Syntax and the OSHB morphology; github.com/Clear-Bible/macula-hebrew) is released under CC BY 4.0, which is why it can be the base of what Mova builds (licence/DATA.md). It gives the Westminster Leningrad Codex (WLC), sentence by sentence, as nested word groups:

The fields from the Semantic Dictionary of Biblical Hebrew (SDBH: sdbh, lexdomain, coredomain, contextualdomain) are deliberately left out of what Mova carries (tools/macula/README.md).

Mova's English side of the same text is the JPS 1917 translation (public domain, from eBible.org) at torah-jps1917, split into sentences by school-sents usfm with the same verse addresses, so Hebrew and English line up verse by verse.

3. The trees: macula and its CoNLL-U

cargo run --release -p macula -- <lowfat-dir> $MOVA_DATA/corpora/judaism/text/torah-wlc-macula GEN,EXO,LEV,NUM,DEU

Output, one file per book, one CoNLL-U block per MACULA sentence:

# sent_id = wlc:GEN:2
# verse = GEN.1.3
# text = וַיֹּ֥אמֶר אֱלֹהִ֖ים יְהִ֣י א֑וֹר וַֽיְהִי־אֽוֹר׃
1  וַ      וְ      CCONJ _ _                                          2 cc    _ Gloss=and|…|Strong=2050b|SpaceAfter=No
2  יֹּ֥אמֶר אָמַר   VERB  _ Gender=Masc|HebBinyan=QAL|Number=Sing|Person=3 0 root  _ Gloss=he.said|…|Strong=0559|Frame=A0:010010030021;|Type=wayyiqtol
3  אֱלֹהִ֖ים אֱלֹהִים NOUN _ Gender=Masc|Number=Plur                  2 nsubj _ Gloss=God|…|Strong=0430
4  יְהִ֣י   הָיָה   VERB  _ Gender=Masc|HebBinyan=QAL|Number=Sing|Person=3 2 ccomp _ Gloss=let.it.be|…|Type=jussive
5  א֑וֹר    אוֹר    NOUN  _ Number=Sing                                4 nsubj _ Gloss=light|…|Strong=0216
6  וַֽ      וְ      CCONJ _ _                                          7 cc    _ Gloss=and|…
7  יְהִי־   הָיָה   VERB  _ Gender=Masc|HebBinyan=QAL|Number=Sing|Person=3 2 conj  _ Gloss=it.was|…|Type=wayyiqtol
8  אֽוֹר    אוֹר    NOUN  _ Number=Sing                                7 nsubj _ Gloss=light|…

The ids: wlc:<BOOK>:<n> counts sentences from 0 within each book; # verse gives the verse in the OSIS-like form GEN.1.3; verses.tsv maps every id to its verses. In the Torah as converted on 2026-10-17 no MACULA sentence spans two verses, so every id maps to exactly one verse; long verses can be split over several sentences.

Size of the Torah (2026-10-17).

booksentenceswords (tokens)
GEN1 53332 365
EXO1 21326 102
LEV85918 912
NUM1 28925 253
DEU95923 175
all5 853125 807

0 trees fail the check (one head per word, one root, no cycle); a negative control in the crate's tests (check_shows_red) shows that the check can fail. 598 word groups had no head rule and took their first child. The conversion takes about 5 s.

UPOS distribution (2026-10-17): NOUN 29 610, ADP 21 085, VERB 17 922, CCONJ 14 236, PRON 13 768, DET 9 110, PROPN 8 004, SCONJ 3 420, ADV 2 868, NUM 2 422, ADJ 2 273, X 565, INTJ 394, PART 130.

The X tokens are MACULA's paragogic and directional letters split off as words of their own: lemma ה 460 (directional he 392 plus paragogic he 73, minus overlap) and lemma נ 105 (paragogic nun). UD has no part of speech for them.

4. Tokens: what a "word" is

MACULA segments the text more finely than the space-separated orthographic word, and Mova keeps its segmentation (the UD guidelines for Ancient Hebrew do the same: prefixed prepositions, the conjunction ו, the article and the pronominal suffixes are tokens of their own; UD hbo docs, _hbo/index.md, CC BY-SA, paraphrased):

orthographic wordtokensexample
ו + verbוַ + יֹּאמֶרGEN.1.3, wlc:GEN:2
preposition + nounבְּ + רֵאשִׁיתGEN.1.1, wlc:GEN:0
article + nounהַ + שָּׁמַיִםGEN.1.1
preposition + hidden article + nounלָ + (empty) + רָקִיעַGEN.1.7, wlc:GEN:6
noun + suffixאָבִ + יוEXO.21.15
verb + object suffixstem + ךָDEU.5.12

Two consequences follow for anyone reading the files:

  1. Empty FORMs. When the article is absorbed into the vowel of a prefixed preposition (לָרָקִיעַ = lə + ha + rāqîaʿ), MACULA still gives the article as a word, and its pointed form is empty. In the Torah 1 679 tokens have an empty FORM, all of them the article הַ (2026-10-17). Their LEMMA is הַ and their UPOS DET, so they still count for definiteness.
  2. Split points inside a syllable. A suffix token's FORM can begin with the vowel point that belongs to the preceding consonant (the FORM of the suffix in DEU.5.12 begins with a shewa: ְךָ). The FORM column therefore does not always hold a pronounceable string; rebuild the surface word by joining the tokens marked SpaceAfter=No.

The # text line is the full pointed and accented verse text as in the WLC, with maqqef and sof pasuq, and is the safe source for display.

5. FEATS and MISC

FEATS carries only what MACULA marks on the word and the UD Hebrew documentation names (UD hbo feature index, _hbo/feat-index.md):

featurevalues in our filessource attribute
GenderMasc, Fem, Comgender
NumberSing, Plur, Dual (779 dual tokens)number
Person1, 2, 3person
HebBinyanQAL 12 757, HIPHIL 2 069, PIEL 1 859, NIPHAL 883, HITHPAEL 179, HOPHAL 149, PUAL 92, POEL 13, POLEL 7, HITHPOLEL 7, PILPEL 5, HITHPALPEL 3, NITHPAEL 1, PALEL 1, UNKNOWN 30stem, upper-cased

Not carried (yet): State (absolute/construct), Definite, VerbForm, Aspect, Mood, Tense, Voice, PronType, NumType. PTNK carries several of these (README changelog: VerbForm and PronType from v2.11, Case from v2.17). In our files the construct state is visible only in the tree (compound:smixut, section 6), and the verb form only in MISC Type.

MISC carries, in this order: Gloss (MACULA's English, with dots for multiword glosses: he.created), Ref (MACULA's word reference, GEN_1:1!2), MId (MACULA's word id, used to align with PTNK), Strong (Strong's number, four digits, with MACULA's letter extensions), Frame (argument frame), Type, and SpaceAfter=No inside a written word.

MISC Type counts in the Torah (2026-10-17).

TypecountTypecount
pronominal (suffix)12 172negative1 576
definite_article9 114participle_active1 472
wayyiqtol4 187personal (pronoun)1 400
direct_object_marker4 153demonstrative1 197
yiqtol3 776imperative782
qatal2 694gentilic436
weqatal2 434participle_passive395
cardinal_number2 253directional_he392
relative1 911interrogative342
infinitive_construct1 739affirmation269
adjective1 503infinitive_absolute255
ordinal_number235jussive192
cohortative129paragogic_nun105
exhortation (נָא)95paragogic_he73
interjection37

Frame. Frame=A0:010010010031;A1:010010010052;010010010072; names, by MACULA word id, the fillers of the verb's roles: A0 the agent-like argument, A1 the patient-like one, A2 a third; several ids after one role are a coordination (GEN.1.1: A1 = "the heavens" and "the earth"). 17 087 tokens carry a frame (GEN 4 847, EXO 3 540, DEU 3 376, NUM 2 950, LEV 2 374; 2026-10-17). Frames reach across clauses (a zero subject's frame points to the noun of an earlier clause), so they are the data's own participant tracking; chapter 9 uses them.

6. The relations: head rules and the UD conventions for Hebrew

The rules (tools/macula/README.md, head_child() and relation() in src/main.rs):

On top of these, the UD conventions for Hebrew (introduced in commit ed0701a37, 2026-10-17):

constructionrelationexample
construct chain, second membercompound:smixut (7 421)פְּנֵי תְהוֹם "the face of the deep", GEN.1.2
pronoun suffix on a nounnmod:poss (6 596)אָבִיו "his father", EXO.21.15
subordinators כִּי אִם לְמַעַן פֶּן טֶרֶם יַעַן עֵקֶב לְבִלְתִּיmark, UPOS SCONJכִּי טוֹב GEN.1.4
relative אֲשֶׁרmark of the relative clause, which is acl:relcl (1 475)GEN.1.7
demonstrative after a noun (הַזֶּה)det (but 286 still amod, section 13)
infinitive after a prepositionadvcl (1 744 advcl in all)
parts of a compound numberflat (450)שִׁבְעִים וְשִׁבְעָה GEN.4.24
clause right after a verb of saying (אמר דבר צוה ענה שאל קרא), no conjunction betweenccomp (1 051)יְהִי אוֹר GEN.1.3
ו at the head of a clausecc on the clause's head; a conjunction never hangs on another

Relation counts in the Torah (2026-10-17): case 20 761, cc 14 183, conj 13 460, obl 11 666, det 9 242, nsubj 7 982, obj 7 561, compound:smixut 7 421, nmod:poss 6 596, root 5 853, nmod 5 105, advmod 3 731, mark 3 395, appos 1 966, advcl 1 744, acl:relcl 1 475, amod 1 369, ccomp 1 051, nummod 572, flat 450, acl 160, dep 59, discourse 5.

A worked tree, GEN.1.7 (wlc:GEN:6), "And God made the firmament, and divided the waters which were under the firmament from the waters which were above the firmament; and it was so" (JPS 1917):

וַ   cc ──────────────┐
יַּעַשׂ  root (wayyiqtol, QAL) ◄─────────────────────────────┐
אֱלֹהִים nsubj → יַּעַשׂ                                       │
אֶת־ case → רָקִיעַ ; הָ det → רָקִיעַ ; רָקִיעַ obj → יַּעַשׂ    │
וַ cc → יַּבְדֵּל ; יַּבְדֵּל conj → יַּעַשׂ (wayyiqtol, HIPHIL)   │
בֵּין case → מַּיִם ; הַ det ; מַּיִם obl → יַּבְדֵּל              │
   אֲשֶׁר mark → רָקִיעַ ; מִ case ; תַּחַת case ; לָ case ; (הַ) det
   רָקִיעַ acl:relcl → מַּיִם        ← the verbless relative clause is headed by its predicate's noun
וּ cc ; בֵין case ; הַ det ; מַּיִם conj → מַּיִם
   אֲשֶׁר mark ; מֵ case ; עַל case ; לָ case ; (הַ) det ; רָקִיעַ acl:relcl → מַּיִם
וַ cc ; יְהִי conj → יַּעַשׂ ; כֵן advmod → יְהִי

The verbless relative clause "which (were) under the firmament" has no verb, so the rules make the noun of its predicate phrase its head, and the stacked prepositions מִן + תַּחַת + לְ all become case of that noun. This is the generic reading the README warns about: special constructions get the general rules.

7. Measured against UD Ancient Hebrew PTNK

UD Ancient Hebrew PTNK (Swanson & Tyers 2022; UD 2.18 at UD_Ancient_Hebrew-PTNK) is the hand-verified UD treebank of the same text. Its README declares CC BY-NC 4.0 (its LICENSE.txt names CC BY-SA 4.0; we follow the stricter reading), so it is only a measure: nothing of it is copied, trained on, or shipped. Its morphology comes from the ETCBC BHSA (CC BY-NC) and its syntax was produced by a rule-based parser of about 300 rules over the MACULA trees and then checked by hand (Swanson & Tyers 2022, abstract). Its splits cover GEN 1–18 (dev), 19–30 (test), 31–50 (train); EXO, LEV, NUM (train); DEU 1–6 (dev), 7–12 (test), 13–34 (train); and Ruth (train).

Because PTNK's words carry MACULA ids, macula compare lines the two up word for word. LAS is counted on the relation without its subtype. The rules are decided on train and dev; test is read once per change of the rules.

2026-10-17test UAStest LASdev UASdev LAS
first head rules86.2473.7984.5970.87
first rules, construct read as nmod78.31
UD conventions for Hebrew88.3882.2386.6179.98

Where the two still part (train, right head, other relation; tools/macula/README.md): parataxis → our conj 788, conj → nmod 385, obl → advmod 278, det → amod 263, mark → det 250, advcl → conj 247. PTNK also reads הָיָה as a copula where we keep it the head. Each of these is a choice of analysis, discussed with the construction in chapters 8 and 9:

8. The pragmatics: macula prag

cargo run --release -p macula -- prag $MOVA_DATA/corpora/judaism/text/torah-wlc-macula $MOVA_DATA/corpora/judaism/hbo-prag.tsv

For every sentence it writes the same six fields the English pragmatics uses (prag/): form, act, indirect, hedge, polarity, voice, plus teacher=rules. The rules (hebrew_prag() in tools/macula/src/main.rs) look only at the root and the words that hang on it directly:

Distribution over the Torah (2026-10-17, 5 853 sentences):

fieldvalues
formdecl 5 591, imp 211, wh 34, q 17
actassert 2 869, narrate 2 010, request 927, ask 47
hedge1 in 17
polarityneg 427
voicenarrator 4 149, character 1 704

Agreement with the English reading of the same verses (macula prag-compare, JPS 1917 read by Mova's English pragmatics; commit ed0701a37, 2026-10-17): form 89%, voice 66–74%, polarity 75–82%, act about 50%. This is a first baseline. The low act score is largely a matter of categories: the English side does not have "narrate", and the Torah's laws in the 2nd person yiqtol are "request" in Hebrew but often "assert" in the English reading.

9. The dictionary: macula dict

cargo run --release -p macula -- dict <trees-dir> BDB_Dictionary.jsonl LexicalIndex.xml torah-en.tsv [en-pool.tsv] [--lang arc] [--jastrow Jastrow_Dictionary.jsonl]

torah-en.tsv has one row per word of the Torah with the columns key, lemma, count, glosses, oshb_def, bdb_headword, bdb_short, bdb_full, why; tanakh-en.tsv has the same for the Hebrew words of the whole Bible, and aramaic-en.tsv for the Aramaic chapters (keyed by lemma, with Jastrow 1903 in three more columns). How they are made: macula, «The dictionaries»:

torah-en.tsv.examples has, per word, its two shortest one-verse sentences in layers: verse, hebrew, literal (MACULA's glosses word for word), literary (JPS 1917), and an empty idea column for a commentary to come.

Figures (2026-10-18): 3 486 keys; 3 471 with a BDB entry; 3 477 with an OSHB definition; 5 816 examples. The whole Tanakh: 8 377 keys; Biblical Aramaic: 698 lemmas.

10. The Torah course and the parse database

The course. world/data/school/torah/*.lesson holds 54 lessons, one per weekly portion (parashah, from Sefaria's index), written by a teacher model from the portion's JPS 1917 text; three key verses of each are given as facts in layers taken from the texts — Hebrew (MACULA), word for word, JPS 1917 and the tradition's reading (commit 3dfca471a). The student (the SLM) answers from the world it reads, never from the teacher. Measured scores and the breakdown of its failures are in Watching the SLM think: the diagnosis of its answers (Torah ★ 236 → 252 and exam 96 → 99 after references like "(Genesis 12:1)" are taken off when a lesson is read).

The parse database. parsedb-hbo is a tree store of the kind tools/cycle keeps (current.conllu, history.conllu, log.tsv, prag.tsv, verses.tsv), seeded on 2026-10-17 with all 5 853 MACULA trees (5 853 seed added rows in log.tsv) and their rule-based pragmatics. It can be given to the cycle as one of CYCLE_TRAIN_DBS, so that the one model's training sees Hebrew trees beside the English ones. In the vote over versions of a tree the seed has weight 1, below any teacher model (tools/cycle/src/db.rs, weight()).

11. The yetzirah crate

yetzirah/ reads the letter tables of Sefer Yetzirah from two Hebrew recensions in docs/sefer-yetzirah/text/ (standard and Gra, Warsaw 1884) and offers a third reading (elamur) that holds both where they differ. It knows the 22 letters in the book's three classes (3 mothers אמ"ש, 7 doubles בגד כפרת, 12 simple), the five places of articulation of 2:3, the six seals, the 231 gates and the "houses" (n! orderings). Measured 2026-10-17: 101 letter entries per recension, all quoted from the text; the recensions differ in 54 places; 52 readings firm, 49 conjectures (yetzirah/README.md).

cargo run --release -p yetzirah -- letter ב
cargo run --release -p yetzirah -- word אדם

For the grammar, its relevance is the letter: the "doubles" are exactly the six begadkefat letters plus resh, the consonants which the Tiberian tradition read in two ways (chapter 1 and chapter 3). The crate knows no grammar beyond letters: it does not read words, roots or vowels.

12. A construction-by-construction map

construction (chapter)where it shows in our fileshandled?
begadkefat, dagesh, vowels (1, 3)FORM only (pointed)no rule reads them
cantillation accents (2)FORM and # text onlynot read; comparisons strip points (consonants())
gender, number (4)FEATSyes, from MACULA
construct state (4, 8)relation compound:smixut; no State featurepartly
article (4)token DET, Type=definite_article; empty FORM when absorbedyes
pronominal suffix (4, 5)token PRON, Type=pronominal, nmod:poss / objyes; FORM may start with a point
object marker אֵת (5, 8)ADP case, Type=direct_object_markeryes
binyan (6, 7)FEATS HebBinyanyes, from MACULA
verb form (6)MISC Type (qatal, wayyiqtol …)yes, but not in FEATS
weak roots (7)LEMMA = dictionary form of the rootlemma only; no analyser of ours
verbless clause (8)head = predicategeneric rule
relative clause (8)mark + acl:relclyes
infinitive after a preposition (8)advclyes
infinitive absolute (6, 8)Type=infinitive_absolute; generic relationgeneric rule
casus pendens, oaths (8)generic rulesno special reading
direct speech (9)ccomp after a verb of saying; לֵאמֹר as an infinitivepartly
wayyiqtol chains (9)conj chains under the first verb; prag act narrateyes
questions, volitives, negation, נָא (5, 9)macula pragyes, rule-based
argument roles (9)MISC Framecarried, not yet used by a tool
lexicon (10)torah-en.tsvyes
Mishnaic Hebrew (11)nothingno trees, no tools

13. Known defects of the data

Found while writing this manual (2026-10-17), none fixed yet:

Found by the chapter authors (details in the chapters named):

14. Gaps and next steps

Marked as not done; each would need the operator's word before an expensive run.

  1. A Rust morphological analyser for Biblical Hebrew (root + binyan + form from the pointed word), measured against MACULA on the Torah, so that Mova can read texts MACULA does not cover (Sefer Yetzirah, Mishnah, the rest of the Bible beyond what MACULA gives).
  2. VerbForm, State, Definite and PronType in FEATS, from MACULA type and the tree, to come nearer to PTNK.
  3. A reading of the accents (chapter 2): the atnach and silluq divide every verse; a test of how often a disjunctive accent falls on the last word of a subtree would turn the Masoretes' phrasing into a check on the trees.
  4. Special readings for oaths, the infinitive absolute, casus pendens and the copular הָיָה.
  5. macula prag: a "narrate" category on the English side, or a mapping, before the act agreement is read as a measure.
  6. Using Frame for participant tracking in the world of the text.
  7. Mishnaic Hebrew: an open, licence-clean text with morphology (chapter 11, "wanted").
  8. The paseq and multiword names (section 13).

15. Sources

This page in Markdown → https://md.mova.elamur.ai/free/en/docs/languages/hbo/13-mova-tools/