namefyi 0.1.0

Pure Python naming engine — Korean romanization, Five Elements compatibility, CJK stroke count. Zero dependencies.

namefyi

Pure Python naming engine for developers. Korean romanization using the Revised Romanization system, Five Elements (오행) compatibility analysis from stroke counts, CJK stroke lookup, population formatting, and URL slug generation -- all with zero dependencies.

Explore Korean names and meanings at namefyi.com -- surname histories, character meanings, naming traditions, and romanization tools.

Install

pip install namefyi              # Core engine (zero deps)
pip install "namefyi[cli]"       # + Command-line interface
pip install "namefyi[mcp]"       # + MCP server for AI assistants
pip install "namefyi[api]"       # + HTTP client for namefyi.com API
pip install "namefyi[all]"       # Everything

Quick Start

from namefyi import romanize_korean, five_elements_for_strokes, check_element_compatibility

# Korean romanization (Revised Romanization)
romanize_korean("김민준")                    # 'gimminjun'
romanize_korean("이서연")                    # 'iseoyeon'

# Five Elements (오행) from stroke count
five_elements_for_strokes(3)                 # '火' (Fire)
five_elements_for_strokes(7)                 # '金' (Metal)

# Element compatibility
check_element_compatibility("木", "火")      # 'compatible' (상생)
check_element_compatibility("木", "土")      # 'incompatible' (상극)
check_element_compatibility("木", "木")      # 'neutral'

Korean Romanization

The Revised Romanization of Korean (국어의 로마자 표기법) was adopted by the South Korean government in 2000, replacing the older McCune-Reischauer system. It is the official standard for road signs, textbooks, and government documents.

Korean Hangul is a featural alphabet where each syllable block is composed of up to three parts: an initial consonant (초성), a medial vowel (중성), and an optional final consonant (종성). The Unicode Hangul Syllables block (U+AC00-U+D7A3) encodes all 11,172 possible syllable combinations. Decomposition follows a mathematical formula:

syllable_index = code_point - 0xAC00
initial  = syllable_index // (21 * 28)    # 19 possible initials
medial   = (syllable_index // 28) % 21    # 21 possible medials
final    = syllable_index % 28            # 28 possible finals (0 = none)

from namefyi import romanize_korean

# Decomposition and romanization happen automatically
romanize_korean("한글")     # 'hangeul'
romanize_korean("서울")     # 'seoul'
romanize_korean("부산")     # 'busan'
romanize_korean("박지성")   # 'bakjiseong'

In practice, Korean surnames have well-established conventional romanizations (Kim, Lee, Park) that differ from the strict Revised Romanization rules (Gim, I, Bak). The namefyi engine applies the standard algorithmic rules; conventional surname spellings are handled at the application level.

Five Elements (오행) in Korean Naming

Traditional Korean naming practice uses the Five Elements cycle (오행, 五行) based on the stroke count of each Hanja character. The five elements -- Wood (木), Fire (火), Earth (土), Metal (金), Water (水) -- follow two fundamental cycles:

Sangseang (상생, 相生) -- the generative cycle: Wood feeds Fire, Fire creates Earth (ash), Earth bears Metal, Metal collects Water (condensation), Water nourishes Wood.

Sanggeuk (상극, 相剋) -- the overcoming cycle: Wood parts Earth, Earth absorbs Water, Water quenches Fire, Fire melts Metal, Metal chops Wood.

from namefyi import five_elements_for_strokes, check_element_compatibility, get_stroke_count

# Stroke count determines element (1-2: Wood, 3-4: Fire, 5-6: Earth, 7-8: Metal, 9-10: Water)
five_elements_for_strokes(1)    # '木' (Wood)
five_elements_for_strokes(5)    # '土' (Earth)

# Check compatibility between elements
check_element_compatibility("水", "木")  # 'compatible' -- Water nourishes Wood (상생)
check_element_compatibility("水", "火")  # 'incompatible' -- Water quenches Fire (상극)

# CJK character stroke count
get_stroke_count("金")   # stroke count for the character

In a well-formed Korean name, the elements of the three characters (surname + given name) should follow the generative cycle (상생), creating a harmonious flow of energy. This practice remains culturally significant and is still consulted by many Korean families when naming children.

Utilities

from namefyi import format_population, surname_slug, character_slug

# Population formatting
format_population(10_345_678)    # '10.3M'
format_population(856_000)       # '856K'

# URL slug generation
surname_slug("김")    # URL-safe slug for surname pages
character_slug("秀")  # URL-safe slug for character pages

Command-Line Interface

pip install "namefyi[cli]"

namefyi romanize 김민준
namefyi elements 3
namefyi compatibility 木 火

MCP Server (Claude, Cursor, Windsurf)

Add naming tools to any AI assistant that supports Model Context Protocol.

pip install "namefyi[mcp]"

Add to your claude_desktop_config.json:

{
    "mcpServers": {
        "namefyi": {
            "command": "python",
            "args": ["-m", "namefyi.mcp_server"]
        }
    }
}

Available tools: romanize_korean, five_elements, element_compatibility, format_population

REST API Client

pip install "namefyi[api]"

from namefyi.api import NameFYI

with NameFYI() as client:
    results = client.search("Kim")
    character = client.character_lookup("金秀")
    name = client.random_name(gender="male")

Full API documentation at namefyi.com.

API Reference

Korean Romanization

Function	Description
romanize_korean(text) -> str	Revised Romanization of Hangul syllables

CJK Stroke Count

Function	Description
get_stroke_count(char) -> int	Unicode-based stroke count for CJK characters

Five Elements (오행)

Function	Description
five_elements_for_strokes(count) -> str	Map stroke count to element (木火土金水)
check_element_compatibility(e1, e2) -> str	Check 상생/상극 between element pairs

Formatting & Slugs

Function	Description
format_population(n) -> str	Human-readable population (e.g., "10.3M")
surname_slug(surname) -> str	URL-safe slug for a Korean surname
character_slug(char) -> str	URL-safe slug for a CJK character

Features

• Korean romanization -- Revised Romanization of Hangul syllables
• Five Elements (오행) -- stroke count to element mapping (木火土金水)
• Element compatibility -- check 상생/상극 between element pairs
• CJK stroke count -- Unicode-based stroke lookup
• Population formatting -- human-readable numbers (10.3M, 850K)
• Slug generation -- URL-safe slugs for surnames and characters
• CLI -- Rich terminal output with romanization and element tables
• MCP server -- 4 tools for AI assistants (Claude, Cursor, Windsurf)
• REST API client -- httpx-based client for namefyi.com API
• Zero dependencies -- pure Python standard library only
• Type-safe -- full type annotations, py.typed marker (PEP 561)

FYIPedia Developer Tools

Part of the FYIPedia open-source developer tools ecosystem:

Package	Description
colorfyi	Color conversion, WCAG contrast, harmonies, shades -- colorfyi.com
emojifyi	Emoji lookup, search, encoding -- emojifyi.com
symbolfyi	Symbol encoding, Unicode properties -- symbolfyi.com
unicodefyi	Unicode character info, 17 encodings -- unicodefyi.com
fontfyi	Google Fonts metadata, CSS, pairings -- fontfyi.com
distancefyi	Haversine distance, bearing, travel times -- distancefyi.com
timefyi	Timezone ops, time differences, business hours -- timefyi.com
namefyi	Korean romanization, Five Elements -- namefyi.com
unitfyi	Unit conversion, 200 units, 20 categories -- unitfyi.com
holidayfyi	Holiday dates, Easter calculation -- holidayfyi.com

Links

• Korean Names Explorer -- Surnames, characters, meanings
• REST API Documentation -- Free API
• npm Package -- TypeScript version
• Source Code -- MIT licensed

License

MIT