Add Titulus_E8 model card

README.md

@@ -1,3 +1,202 @@
 ---
-license: apache-2.0
+language:
+  - hbo  # Ancient Hebrew
+  - grc  # Ancient Greek (Koine)
+  - la   # Latin
+library_name: peft
+base_model: Qwen/Qwen2.5-0.5B-Instruct
+tags:
+  - lora
+  - peft
+  - geometric-ai
+  - biblical-hebrew
+  - koine-greek
+  - latin-vulgate
+  - e8-lattice
+  - hallucination-reduction
+  - sovereign-engine
+license: other
+license_name: sectl-1.0
+license_link: https://github.com/JLeeV/sovereign-engine/blob/main/LICENSE
 ---
+
+# Titulus_E8 — Geometric LoRA Adapter
+
+**Titulus_E8** is a LoRA fine-tuning adapter for causal language models, trained on the trilingual Biblical corpus
+(Hebrew Tanakh · Koine Greek NT/LXX · Latin Vulgate) with a **Topological Coherence Loss** that anchors the
+model's embedding space to the [E8 lattice](https://en.wikipedia.org/wiki/E8_lattice).
+
+The adapter is part of the **Sovereign Geometric Model (SGM)** architecture from
+[Sovereign Engine](https://github.com/JLeeV/sovereign-engine), a distributed geometric AI system that uses
+discrete lattice mathematics to eliminate LLM hallucinations by construction.
+
+---
+
+## The Name
+
+The *Titulus Crucis* — the inscription nailed above the cross — was written in three languages: Hebrew, Latin,
+and Greek (John 19:20). It is one of the most historically significant trilingual documents in existence and the
+conceptual anchor for this system. The trilingual structure mirrors the three corpus languages exactly.
+
+---
+
+## Architecture
+
+```
+Base Model  (Qwen2.5-0.5B-Instruct)
+    │
+    ├── LoRA Adapter  ← Titulus_E8
+    │     rank=32, alpha=64
+    │     target: q_proj, v_proj
+    │
+    └── E8 Logit Mask  (inference-time geometric constraint)
+          - every vocabulary token → 8D IPA phonetic coordinate
+          - coordinate snapped to nearest of 240 E8 roots (Babai CVP)
+          - logits attenuated for tokens that drift beyond geodesic radius
+```
+
+### Training Objective
+
+The adapter is trained with a **dual loss**:
+
+```
+L = λ_lm · CE_loss + λ_topo · TopologicalCoherenceLoss
+
+TopologicalCoherenceLoss = mean( min_j ||h_i - e8_root_j||² )
+```
+
+Where `h_i` are the final hidden-state vectors and `e8_root_j` are the 240 roots of the E8 lattice,
+projected into the model's hidden dimension. This forces semantically related embeddings to cluster
+near valid lattice coordinates — making hallucination geometrically costly rather than just statistically
+unlikely.
+
+---
+
+## Training Data
+
+| Language | Corpus | Source |
+|---|---|---|
+| **Biblical Hebrew** | Westminster Leningrad Codex (Masoretic Text) | `christos-c/bible-corpus` |
+| **Koine Greek** | Nestle-Aland NT + Septuagint (LXX) | `christos-c/bible-corpus` |
+| **Latin** | Clementine Vulgate | `christos-c/bible-corpus` |
+
+Each training sample interleaves all three translations of a canonical verse:
+
+```
+[HE] בְּרֵאשִׁית בָּרָא אֱלֹהִים אֵת הַשָּׁמַיִם וְאֵת הָאָרֶץ
+[GR] Ἐν ἀρχῇ ἐποίησεν ὁ θεὸς τὸν οὐρανὸν καὶ τὴν γῆν
+[LA] In principio creavit Deus caelum et terram
+```
+
+The model learns to associate semantically equivalent expressions across three typologically distinct
+language families — forcing its latent space to develop representations that are stable across linguistic
+surface variation.
+
+---
+
+## Usage
+
+### As a standard PEFT adapter
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+
+base_model_id = "Qwen/Qwen2.5-0.5B-Instruct"
+adapter_id    = "JLeeV/Titulus_E8"
+
+tokenizer = AutoTokenizer.from_pretrained(base_model_id)
+model     = AutoModelForCausalLM.from_pretrained(base_model_id)
+model     = PeftModel.from_pretrained(model, adapter_id)
+
+inputs = tokenizer("In the beginning", return_tensors="pt")
+output = model.generate(**inputs, max_new_tokens=50)
+print(tokenizer.decode(output[0]))
+```
+
+### With Geometric Logit Mask (full SGM pipeline)
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM, LogitsProcessorList
+from peft import PeftModel
+from sov_heart.logit import GeometricLogitMask
+
+base_model_id = "Qwen/Qwen2.5-0.5B-Instruct"
+tokenizer = AutoTokenizer.from_pretrained(base_model_id)
+model     = PeftModel.from_pretrained(
+    AutoModelForCausalLM.from_pretrained(base_model_id),
+    "JLeeV/Titulus_E8"
+)
+
+# Build geometric constraint interceptor
+processor = GeometricLogitMask.as_logits_processor(
+    tokenizer,
+    radius=3.0,        # geodesic tolerance (tighter = stricter)
+    soft_mask=True,    # Gaussian attenuation vs hard zeroing
+    cache_path="/tmp/titulus_token_coords.npy",  # cache for fast reload
+)
+
+inputs = tokenizer("Explain the concept of logos", return_tensors="pt")
+output = model.generate(
+    **inputs,
+    max_new_tokens=200,
+    logits_processor=LogitsProcessorList([processor]),
+)
+print(tokenizer.decode(output[0]))
+```
+
+---
+
+## Installation
+
+```bash
+pip install peft transformers torch
+
+# For the full SGM geometric constraint system:
+git clone https://github.com/JLeeV/sovereign-engine
+cd sovereign-engine && pip install -e .
+```
+
+---
+
+## Geometric Coordinate Mapping
+
+Each token in the vocabulary is mapped to an **8-dimensional E8 coordinate** using IPA phonetic features:
+
+| Dimension | Feature |
+|---|---|
+| 0 | Stop consonant ratio (p, b, t, d, k, g, q) |
+| 1 | Fricative ratio (s, z, v, ʃ, ħ, θ, f, x) |
+| 2 | Nasal ratio (m, n) |
+| 3 | Vowel ratio (a, e, i, o, u, y) |
+| 4 | Liquid ratio (r, l) |
+| 5 | Mean Unicode codepoint (normalised to Hebrew range) |
+| 6 | Script class (0=Latin, 0.5=Greek, 1.0=Hebrew/Semitic) |
+| 7 | Syllable density (syllables per character) |
+
+The raw 8D vector is then snapped to the nearest of the **240 roots of the E8 lattice** using Babai's
+Closest Vector Problem (CVP) algorithm — guaranteeing all token coordinates are valid lattice points.
+
+---
+
+## License
+
+This adapter is released under the **Sovereign Engine Cooperative and Topological License (SECTL) v1.0**.
+See [LICENSE](https://github.com/JLeeV/sovereign-engine/blob/main/LICENSE) for full terms.
+
+The training corpus texts (Westminster Leningrad Codex, NA28, Clementine Vulgate) are in the public domain.
+
+---
+
+## Citation
+
+```bibtex
+@misc{titulus_e8_2026,
+  author       = {JLeeV},
+  title        = {Titulus\_E8: A Geometric LoRA Adapter Anchored to the E8 Lattice},
+  year         = {2026},
+  publisher    = {HuggingFace},
+  howpublished = {\url{https://huggingface.co/JLeeV/Titulus_E8}},
+  note         = {Part of the Sovereign Engine geometric AI architecture}
+}
+```