---

Overview

Egyptian personal names follow an unbroken patronymic lineage system (Personal + Father + Grandfather + Ancestor + Family/Tribe) rather than the Western Given + Surname convention. This structure creates significant computational and linguistic challenges:

1. Patronymic Lineage Ambiguity: Determining the generational role of each name element in official and colloquial records.
2. Compound Names: Proper handling of prefixed and unspaced compound names (عبدالرحمن vs عبد الرحمن, نور الدين, فاطمة الزهراء).
3. Orthographic Variations: Resolving standard Arabic spelling variants (مصطفى/مصطفا, إبراهيم/ابراهيم, أحمد/احمد).
4. Concatenated Names: Segmenting unspaced text strings in legacy digital records (محمدأحمدعليحسنالشاذلي).

egy-names solves these problems deterministically without relying on language model inference, using an empirical statistical model extracted from over 13,000,000+ validated records, 56,796 canonical names, and 54,000+ orthographic correction rules.

---

Key Features

Capability	Description	Example
Patronymic Generation	Slot-weighted sampling matching national demographic distributions	حسام أحمد عبدالعليم
Concatenated Segmentation	Dynamic programming shortest-path segmenter for unspaced text	محمدأحمدعلي $\to$ [محمد, أحمد, علي]
Diacritization (Tashkeel)	Full vowel mark restoration with compound awareness	محمد عبدالرحمن $\to$ مُحَمَّد عَبْدُالرَّحْمَن
Orthographic Correction	Rule-based correction and Alif/Alif Maqsura normalization	احمد مصطفا $\to$ أحمد مصطفى
Transliteration	Bidirectional Arabic $\leftrightarrow$ English with phonetic preservation	محمد أحمد علي $\leftrightarrow$ Mohamed Ahmed Ali
Demographic Inference	Empirical gender and religious cultural classification	مريم (Female 95%), جورج (Christian 99%)
Lineage Decomposition	Six-slot generational decomposition	Personal $\to$ Father $\to$ Grandfather $\to$ Family
Etymology & Meanings	Morphological root definitions and English translations	محمد $\to$ The Praised One ( الجذر: ح م د )

---

Hugging Face Datasets

The underlying national datasets are open-source and available on Hugging Face:

1. Egyptian Names & Onomastic Intelligence Dataset

👉 https://huggingface.co/datasets/Abdullah-afify/egyptian-names

• 44,626 Canonical Names with gender, religion, generational slot distribution weights, Tashkeel, root meanings, and transliterations.
• 15,875,535+ Raw Full Name Records (phase0_raw) and 1,000,000 Segmented Chains (phase1_segmented).
• 43,333 Unique Token Frequencies and 23,457 Orthographic Correction Rules.

📊 Full Data vs. Single Names Breakdown

Metric	Count	Description
Total Raw Exam Records	~15,875,535	Total individual student & citizen exam rows across 494 dataset files
Total Full Name Occurrences	~15.88 Million	Total full patronymic name chains (e.g., "محمد أحمد علي حسن الشرقاوي")
Unique Full Name Strings	1,545,970+	Distinct full 3-to-5-part name combinations
Total Single Name Occurrences	~63,500,000	Total individual name occurrences across all slots (averaging 4 names per chain)
Raw Distinct Single Tokens	43,333	Distinct raw word tokens before typo cleaning
Typo & Spelling Corrections	23,457	Mappings for misspellings and unspaced compound names (عبدالرحمن $\to$ عبد الرحمن)
Final Canonical Master Lexicon	44,626	The complete clean dictionary of unique Egyptian names

from datasets import load_dataset

# Load default canonical dictionary (44.6K names)
names_dataset = load_dataset("Abdullah-afify/egyptian-names")

# Load raw full names
raw_names = load_dataset("Abdullah-afify/egyptian-names", "phase0_raw")

2. Egyptian High School Students Degrees Dataset (2017–2026)

👉 https://huggingface.co/datasets/Abdullah-afify/egyptian-high-school-students-grades

• 3,790,225 Total Student Records across 5 national examination cohorts (2017, 2023, 2024, 2025, and 2026).
• Includes seating numbers, full student quad/quint names, total examination scores, and pass/fail statuses.

# Load all 3.79M student records across 2017-2026
degrees_dataset = load_dataset("Abdullah-afify/egyptian-high-school-students-grades")

# Load a specific examination cohort (e.g. 2026 results)
cohort_2026 = load_dataset("Abdullah-afify/egyptian-high-school-students-grades", "year_2026")

---

Installation & Usage

Swift / iOS / macOS / visionOS

Add package via Xcode (File > Add Package Dependencies...) or in Package.swift:

dependencies: [
    .package(url: "https://github.com/AbdullahAfifyKhalil/egy-names.git", from: "0.2.1")
]

import EgyNames

let en = EgyptianNames()
print(en.translate("محمد أحمد علي"))  // Mohamed Ahmed Ali
print(en.correct("احمد مصطفا عبد الرحيم"))  // أحمد مصطفى عبدالرحيم
print(en.tashkeel("محمد عبدالرحمن"))  // مُحَمَّد عَبْدُالرَّحْمَن
print(en.split("محمدأحمدعليحسن"))  // ["محمد", "أحمد", "علي", "حسن"]

---

Python (3.9+)

pip install egy-names==0.2.1

from egy_names import EgyptianNames

en = EgyptianNames()
print(en.translate("محمد أحمد علي"))  # Mohamed Ahmed Ali
print(en.correct("احمد مصطفا عبد الرحيم"))  # أحمد مصطفى عبدالرحيم
print(en.tashkeel("محمد عبدالرحمن"))  # مُحَمَّد عَبْدُالرَّحْمَن
print(en.split("محمدأحمدعليحسن"))  # ['محمد', 'أحمد', 'علي', 'حسن']

---

TypeScript / Node.js

npm install egy-names@0.2.1

import { EgyptianNames } from 'egy-names';

const en = new EgyptianNames();
console.log(en.translate("محمد أحمد علي")); // Mohamed Ahmed Ali
console.log(en.correct("احمد مصطفا عبد الرحيم")); // أحمد مصطفى عبدالرحيم
console.log(en.tashkeel("محمد عبدالرحمن")); // مُحَمَّد عَبْدُالرَّحْمَن
console.log(en.split("محمدأحمدعليحسن")); // ['محمد', 'أحمد', 'علي', 'حسن']

---

.NET / C#

dotnet add package egy-names --version 0.2.1

using EgyNames;

var en = new EgyptianNames();
Console.WriteLine(en.Translate("محمد أحمد علي")); // Mohamed Ahmed Ali
Console.WriteLine(en.Correct("احمد مصطفا عبد الرحيم")); // أحمد مصطفى عبدالرحيم
Console.WriteLine(en.Tashkeel("محمد عبدالرحمن")); // مُحَمَّد عَبْدُالرَّحْمَن
Console.WriteLine(string.Join(", ", en.Split("محمدأحمدعليحسن"))); // محمد, أحمد, علي, حسن

---

Dart / Flutter

flutter pub add egy_names:^0.2.1

import 'package:egy_names/egy_names.dart';

void main() {
  final en = EgyptianNames();
  print(en.translate("محمد أحمد علي")); // Mohamed Ahmed Ali
  print(en.correct("احمد مصطفا عبد الرحيم")); // أحمد مصطفى عبدالرحيم
  print(en.tashkeel("محمد عبدالرحمن")); // مُحَمَّد عَبْدُالرَّحْمَن
  print(en.split("محمدأحمدعليحسن")); // [محمد, أحمد, علي, حسن]
}

---

Java / Kotlin

<dependency>
    <groupId>io.github.abdullahafifykhalil</groupId>
    <artifactId>egy-names</artifactId>
    <version>0.2.1</version>
</dependency>

import com.afify.egynames.EgyptianNames;

EgyptianNames en = new EgyptianNames();
System.out.println(en.translate("محمد أحمد علي")); // Mohamed Ahmed Ali
System.out.println(en.correct("احمد مصطفا عبد الرحيم")); // أحمد مصطفى عبدالرحيم
System.out.println(en.tashkeel("محمد عبدالرحمن")); // مُحَمَّد عَبْدُالرَّحْمَن

---

Modern C++ (C++20 / C++17)

include(FetchContent)
FetchContent_Declare(
    egy_names
    GIT_REPOSITORY https://github.com/AbdullahAfifyKhalil/egy-names.git
    GIT_TAG v0.2.1
)
FetchContent_MakeAvailable(egy_names)
target_link_libraries(your_target PRIVATE egy_names)

#include <egy_names/egy_names.hpp>
#include <iostream>

int main() {
    egy_names::EgyNames en;
    std::cout << en.translate("محمد أحمد علي") << "\n"; // Mohamed Ahmed Ali
    std::cout << en.correct("احمد مصطفا عبد الرحيم") << "\n"; // أحمد مصطفى عبدالرحيم
    std::cout << en.tashkeel("محمد عبدالرحمن") << "\n"; // مُحَمَّد عَبْدُالرَّحْمَن
}

---

Onomastic Architecture

1. Patronymic Lineage Decomposition

The position of a name within an Egyptian patronymic chain defines its legal and social role:

[ محمد ]     [ أحمد ]      [ علي ]       [ حسن ]        [ الشاذلي ]
   │            │             │             │               │
Slot 1        Slot 2        Slot 3        Slot 4          Slot 5
Person        Father     Grandfather     Ancestor      Family/Tribe
(اسم الشخص)   (اسم الأب)   (اسم الجد)      (السلف)     (اللقب والعائلة)

egy-names models the empirical probability $P(\text{Name} \mid \text{Slot}_k)$ across all six positions.

2. Concatenated Dynamic Programming Segmentation

When processing unspaced Arabic text (محمدأحمدعليحسنالشاذلي), the library executes a shortest-path dynamic programming algorithm over Unicode codepoints:

$$\text{Cost}(i) = \min_{j < i} \Big( \text{Cost}(j) + \text{BaseCost} + \text{Bonus}(\text{Freq}{j..i}) + \lambda \cdot \text{Length}{j..i} \Big)$$

---

About Afify Corporation

Afify Corporation is a technology and media enterprise innovating across software, hardware systems, and digital media, leveraging advanced engineering and artificial intelligence.

• 🌐 Website: afify.co
• 🐙 GitHub: github.com/AbdullahAfifyKhalil
• 👤 Founder: Abdullah Afify

---

Contributing

Contributions, issues, and feature requests are welcome. Feel free to open an issue on the GitHub issues page.

---

License

Distributed under the MIT License. See LICENSE for details.

---