Metadata-Version: 2.4
Name: cjk-semantic-split
Version: 0.6.0
Summary: Recursive atomic decomposition of 汉字 (Chinese characters) with 9-grid 2-digit spatial encoding, distinguishing simplified and traditional forms. 将汉字递归拆解为原子部件，并在 9 宫格 2 位数字空间编码中标记每个组件的位置。
Project-URL: Source, https://github.com/yueguanyu/Semantic-Character-Splitting-and-Structural-Coding-for-Chinese-Script.git
Project-URL: Bug Tracker, https://github.com/yueguanyu/Semantic-Character-Splitting-and-Structural-Coding-for-Chinese-Script/issues
Author-email: Guanyu Yue <yue.guanyu@hotmail.com>
License: MIT License
        
        Copyright (c) 2026
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: chinese,decomposition,hanzi,ideograph
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: hatch>=1.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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`](docs/component-position-encoding.md)）
- **多重数据源**：内置四级 — Unihan kIDS / wikimedia Commons / 下一层采集 / 手工修补
- **零运行时依赖**：纯 Python

**主要 API**

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

```python
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/decomposition-logic.md)；完整位置编码表参见 [`docs/component-position-encoding.md`](docs/component-position-encoding.md)。

---

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

```bash
pip install cjk-semantic-split
```

```python
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](docs/component-position-encoding.md) — full position-code reference (00/10/20/30/40, corners, 4-cell strips, surrounds) and the composition operator.
- [Decomposition Logic](docs/decomposition-logic.md) — 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](docs/superpowers/specs/2026-07-16-cjk-semantic-split-design.md) for full details.

## CLI

```bash
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

```bash
pip install cjk-semantic-split
```

From source:

```bash
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

```python
from chinese_decompose import decompose

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

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

For traditional forms:

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

For unknown chars, raise or skip:

```python
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

```python
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):

```python
encode_codec("木") == "木"
```

For non-strict mode on unknown chars:

```python
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

```python
from chinese_decompose import set_primitives

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

## License

MIT — see `LICENSE`.
