cjk-semantic-split 0.6.0

Recursive atomic decomposition of 汉字 (Chinese characters) with 9-grid 2-digit spatial encoding, distinguishing simplified and traditional forms. 将汉字递归拆解为原子部件，并在 9 宫格 2 位数字空间编码中标记每个组件的位置。

cjk-semantic-split

---

中文简介

cjk-semantic-split 是一个 Python 库，用于将汉字 (通用规范汉字表 GF 0013-2013, 简体和繁体) 递归拆分为原子部件，并使用 9 宫格 2 位数字空间编码标记每个组件的位置。

核心特性

• 递归拆解：例如 踩 → 足 + 采 → 爪 + 木，中间非叶节点（如 采）完整保留
• 位置编码：每个组件的 2 位数字代号（00/10/20/30/40 四个基本方位 + 50/60/70/80 四个角方位 + 14/16/34/36 四分拆壁 + 90–99 包围框）
• 组合算子 ⊙：父子位置按空间几何合成（详见 docs/component-position-encoding.md）
• 多重数据源：内置四级 — Unihan kIDS / wikimedia Commons / 下一层采集 / 手工修补
• 零运行时依赖：纯 Python

主要 API

• decompose(text) → 字符串（默认 JSON 输出）
• read_structure(text) → list[DecompositionTree]，保留完整嵌套层级（包含中间非叶节点）
• python -m chinese_decompose <字符> → 命令行

from chinese_decompose import read_structure

trees = read_structure("踩")
# trees[0].atoms     == ('足', '爪', '木')
# trees[0].positions == (30, 60, 80)
# 采 作为中间节点保留在 children[1] 中

详细算法参见 docs/decomposition-logic.md；完整位置编码表参见 docs/component-position-encoding.md。

---

Recursive atomic decomposition of 汉字 (Chinese characters, simplified and traditional) with 9-grid spatial position encoding.

pip install cjk-semantic-split

from chinese_decompose import decompose

decompose("踩")
# '踩 [30]:足 [60]:爪 [80]:木'

decompose("囚")
# '囚 [90]:囗 [0]:人'

decompose("踩好", as_tree=True)
# [DecompositionTree('踩'), DecompositionTree('好')]

# Read the full structural decomposition (preserves intermediate nodes
# like 采 inside 踩; each tree node carries its 2-digit position code).
from chinese_decompose import read_structure
trees = read_structure("踩")
trees[0].atoms     # ('足', '爪', '木')
trees[0].positions # (30, 60, 80)
trees[0].children[1].char  # '采'  (intermediate node preserved!)
trees[0].children[1].position  # 40

Documentation

• Component Position Encoding — full position-code reference (00/10/20/30/40, corners, 4-cell strips, surrounds) and the composition operator.
• Decomposition Logic — algorithm walkthrough, data flow, worked example 踩 → 足 + 采 → 爪 + 木.

Position Encoding

Every component sits at a 2-digit position code: cardinals (10/20/30/40), single-cell corners (50/60/70/80), 4-cell layout strips (14/16/34/36), or surround envelopes (90–99). See the design spec for full details.

CLI

python -m chinese_decompose 好                  # JSON output (default)
python -m chinese_decompose 好 --format dsl    # DSL string
python -m chinese_decompose 好 --format tree   # repr() of nested trees
python -m chinese_decompose 好 --script zh-Hant  # traditional
python -m chinese_decompose --self-test         # coverage report

Installation

pip install cjk-semantic-split

From source:

git clone https://github.com/yueguanyu/Semantic-Character-Splitting-and-Structural-Coding-for-Chinese-Script.git
cd Semantic-Character-Splitting-and-Structural-Coding-for-Chinese-Script
pip install -e .

Requires Python ≥ 3.9. No third-party runtime dependencies.

Quick Start

from chinese_decompose import decompose

print(decompose("好"))
# '好 [30]:女 [40]:子'

print(decompose("字"))
# '字 [10]:宀 [20]:子'

For traditional forms:

from chinese_decompose import decompose
print(decompose("好", script="zh-Hant"))

For unknown chars, raise or skip:

from chinese_decompose import decompose, UnknownCharacterError

try:
    decompose("龘")  # outside GF 0013-2013
except UnknownCharacterError:
    print("not in dictionary")

decompose("龘", strict=False)  # → '?[?]:?'

API Reference

Public Symbols

Symbol	Signature	Purpose
decompose	(text, *, as_tree=False, strict=True, script=None, loader=None)	Primary API; returns DSL string or list of DecompositionTree.
read_structure	(text, *, strict=True, script=None, loader=None)	Returns a list of DecompositionTree with full nested hierarchy.
make_loader	(*, script=None, patches_path=None)	Construct (or return cached singleton) Loader.
clear_cache	()	Reset all loader singletons.
get_primitives	(*, script=None)	Active primitive set for script.
set_primitives	(iterable, *, script=None)	Process-local override; test affordance.
reset_primitives	(*, script=None)	Clear override(s); script=None clears all scripts.
is_primitive	(char, *, script=None)	Primitive membership check.
get_primitive_id	(char, *, script=None)	Char → 0-213 Kangxi ID; raises ValueError if not a Kangxi radical.
get_primitive_by_id	(id, *, script=None)	ID → char; raises ValueError if id ∉ [0, 213].
list_primitives	(*, script=None)	214 primitive chars in 康熙原序.
list_primitives_with_ids	(*, script=None)	((id, char), ...) in 康熙原序.
encode_codec	(text, *, script="zh-Hans", strict=True)	DSL → ID-based compact format.
decode_codec	(encoded, *, script="zh-Hans")	ID-based → text (round-trips).
parse_dsl	(dsl_str)	Parse a DSL string into a DecompositionTree.
serialize_tree	(tree)	Serialize a DecompositionTree to DSL.
compose	(parent, child)	Position composition operator.
DecompositionTree	dataclass	Immutable decomposition node (char, children, position, atoms, positions).

Codec Example

from chinese_decompose import encode_codec, decode_codec

encoded = encode_codec("好字")
# '好,37,30,38,40|字,39,10,38,20'
print(decode_codec(encoded))
# '好字'

Primitive-only chars encode as the bare char (no IDs):

encode_codec("木") == "木"

For non-strict mode on unknown chars:

encode_codec("好龘", strict=False)
# '好,37,30,38,40|?'

Errors

Exception	When
UnknownCharacterError	strict=True and a char has no decomposition data.
ValueError	Bad script name; ID out of range; malformed codec entry.
InvalidPositionCodeError	Data file has a position outside the 2-digit valid set.
MalformedDSLParseError	parse_dsl on a bad DSL string.
CompositionError	compose(parent, child) for a geometrically invalid pair.

Scope (v0.4.0)

The bundled data covers the 通用规范汉字表 (GF 0013-2013) — 8,105 chars mandated by the PRC Ministry of Education for general Chinese text — and nothing else. This package supports 汉字 (Chinese characters, simplified and traditional) only. Japanese (仮名, 漢字), Korean (한글, 漢字), and other CJK region scripts are not supported. The primitive (基础偏旁部首) set is the canonical 康熙字典 214 部首, identical in both Hans and Hant files.

Bundled data files (src/chinese_decompose/data/):

• decomp_zh-Hans-general.txt — simplified GF 0013-2013 (~8k chars)
• decomp_zh-Hant-general.txt — traditional GF 0013-2013 (~8k chars)
• decomp_patches.txt — manual overrides (wins over all)
• primitives_zh-Hans.txt / primitives_zh-Hant.txt — 214 Kangxi radicals each

Configuration

from chinese_decompose import set_primitives

set_primitives({"木", "火", "水", ...})  # process-local override

License

MIT — see LICENSE.