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.

Table of Contents

• Install
• Quick Start
• Korean Romanization
• Five Elements in Korean Naming
• CJK Stroke Count
• Utilities
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
  • Korean Romanization
  • CJK Stroke Count
  • Five Elements
  • Formatting & Slugs
• Features
• Learn More About Names
• Utility FYI Family
• License

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)

Hangul	Revised Romanization	McCune-Reischauer	Conventional
김	gim	kim	Kim
이	i	yi/i	Lee
박	bak	pak	Park
서울	seoul	soul	Seoul
부산	busan	pusan	Busan
한글	hangeul	han'gul	Hangul
대한민국	daehanminguk	taehanmin'guk	--

from namefyi import romanize_korean

# Hangul decomposition and Revised Romanization applied automatically
romanize_korean("한글")     # 'hangeul' — the Korean writing system
romanize_korean("서울")     # 'seoul'   — capital of South Korea
romanize_korean("부산")     # 'busan'   — second-largest city
romanize_korean("박지성")   # 'bakjiseong' — Korean name romanization

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.

Learn more: Korean Names · Romanization Tool · Name Search

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.

Element	Hanja	Korean	Stroke Count	Generates	Overcomes
Wood	木	목 (mok)	1--2	Fire	Earth
Fire	火	화 (hwa)	3--4	Earth	Metal
Earth	土	토 (to)	5--6	Metal	Water
Metal	金	금 (geum)	7--8	Water	Wood
Water	水	수 (su)	9--10	Wood	Fire

from namefyi import five_elements_for_strokes, check_element_compatibility, get_stroke_count

# Map stroke count to Five Elements -- the last digit determines the element
five_elements_for_strokes(1)    # '木' (Wood) — 1-2 strokes
five_elements_for_strokes(5)    # '土' (Earth) — 5-6 strokes

# Check element compatibility using the generative/overcoming cycles
check_element_compatibility("水", "木")  # 'compatible' -- Water nourishes Wood (상생)
check_element_compatibility("水", "火")  # 'incompatible' -- Water quenches Fire (상극)

# CJK stroke count lookup for Hanja characters
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.

Learn more: Five Elements (오행) · Korean Names · Glossary

CJK Stroke Count

Stroke count is fundamental to CJK (Chinese, Japanese, Korean) character systems. In Korean naming tradition, the stroke count of each Hanja character determines its Five Element, which drives compatibility analysis. The get_stroke_count function uses the Unicode CJK Unified Ideographs block (U+4E00--U+9FFF) with a built-in stroke count database covering over 20,000 characters.

Character	Meaning	Strokes	Five Element
一	one	1	Wood (木)
人	person	2	Wood (木)
大	big	3	Fire (火)
天	heaven	4	Fire (火)
民	people	5	Earth (土)
光	light	6	Earth (土)
秀	excellent	7	Metal (金)
金	gold/metal	8	Metal (金)
美	beauty	9	Water (水)
真	truth	10	Water (水)

from namefyi import get_stroke_count, five_elements_for_strokes

# Look up stroke count for any CJK character
strokes = get_stroke_count("秀")   # 7 strokes
element = five_elements_for_strokes(strokes)  # '金' (Metal)

# Stroke counts drive Five Element compatibility in Korean naming
strokes_kim = get_stroke_count("金")   # surname character
strokes_min = get_stroke_count("民")   # given name first character

Learn more: CJK Stroke Lookup · Five Elements (오행) · Character Meanings

Utilities

from namefyi import format_population, surname_slug, character_slug

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

# URL slug generation for Korean name reference pages
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)

Learn More About Names

• Tools: Name Search · Romanization Tool
• Browse: Korean Names · Cultures
• Guides: Glossary · Blog
• API: REST API Docs · OpenAPI Spec

Utility FYI Family

Part of the FYIPedia open-source developer tools ecosystem — everyday developer reference and conversion tools.

Package	PyPI	npm	Description
unitfyi	PyPI	npm	Unit conversion, 220 units -- unitfyi.com
timefyi	PyPI	npm	Timezone ops & business hours -- timefyi.com
holidayfyi	PyPI	npm	Holiday dates & Easter calculation -- holidayfyi.com
namefyi	PyPI	npm	Korean romanization & Five Elements -- namefyi.com
distancefyi	PyPI	npm	Haversine distance & travel times -- distancefyi.com

Embed Widget

Embed NameFYI widgets on any website with namefyi-embed:

<script src="https://cdn.jsdelivr.net/npm/namefyi-embed@1/dist/embed.min.js"></script>
<div data-namefyi="entity" data-slug="example"></div>

Zero dependencies · Shadow DOM · 4 themes (light/dark/sepia/auto) · Widget docs

License

MIT