cjk-semantic-split 0.2.0

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

cjk-semantic-split

---

中文简介

cjk-semantic-split 是一个 Python 库，用于将任意 CJK 统一表意文字递归拆分为原子部件，并使用 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 CJK characters 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 --self-test         # coverage report

Data Sources

Decomposition data is bundled for offline use. Coverage extends across four tiers:

• Tier 1 (Unihan kIDS): ~21k chars
• Tier 2 (wikimedia Commons): ~22k chars
• Tier 3 (next-layer harvest): ~80k chars
• Tier 4 (manual patches): dispute-case overrides

Last-wins resolution: patches > l3 > l2 > l1.

Configuration

from chinese_decompose import set_primitives

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

License

MIT — see LICENSE.