cjk-semantic-split 0.1.0__py3-none-any.whl

chinese_decompose/__init__.py

@@ -0,0 +1,2 @@
+"""chinese_decompose: recursive atomic decomposition of CJK characters."""
+__version__ = "0.1.0"

chinese_decompose/__main__.py

@@ -0,0 +1,134 @@
+"""CLI entry point: python -m chinese_decompose."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from chinese_decompose import __version__
+from chinese_decompose.api import decompose
+from chinese_decompose.errors import ChineseDecomposeError, UnknownCharacterError
+from chinese_decompose.loader import make_loader
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="chinese_decompose",
+        description="Decompose CJK characters into atomic primitives with spatial positions.",
+    )
+    parser.add_argument(
+        "chars",
+        nargs="*",
+        help="One or more CJK characters to decompose. If empty, read from stdin.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["dsl", "json", "tree"],
+        default="json",
+        help="Output format (default: json).",
+    )
+    parser.add_argument(
+        "--no-strict",
+        action="store_true",
+        help="Emit ? markers for unknown characters instead of raising.",
+    )
+    parser.add_argument(
+        "--primitives",
+        type=Path,
+        help="Path to a JSON file overriding the primitive set.",
+    )
+    parser.add_argument(
+        "--self-test",
+        action="store_true",
+        help="Run a self-test reporting tier coverage.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"chinese_decompose {__version__}",
+    )
+    return parser
+
+
+def _read_stdin() -> str:
+    return sys.stdin.read().strip()
+
+
+def _format_dsl(text: str, strict: bool) -> str:
+    return decompose(text, strict=strict)
+
+
+def _format_json(text: str, strict: bool) -> str:
+    trees = decompose(text, as_tree=True, strict=strict)
+    out = []
+    for tree in trees:
+        out.append({
+            "char": tree.char,
+            "atoms": list(tree.atoms),
+            "positions": list(tree.positions),
+            "dsl": tree.to_dsl(),
+        })
+    return json.dumps(out, ensure_ascii=False, indent=2)
+
+
+def _format_tree(text: str, strict: bool) -> str:
+    trees = decompose(text, as_tree=True, strict=strict)
+    return "\n".join(repr(t) for t in trees)
+
+
+def _self_test() -> str:
+    loader = make_loader()
+    total = len(loader)
+    return (
+        f"chinese_decompose self-test\n"
+        f"  version: {__version__}\n"
+        f"  characters indexed: {total}\n"
+        f"  tiers: 4 (l1, l2, l3, patches)\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.primitives is not None:
+        data = json.loads(args.primitives.read_text(encoding="utf-8"))
+        from chinese_decompose.primitives import set_primitives
+        if isinstance(data, list):
+            set_primitives(data)
+        elif isinstance(data, dict) and "primitives" in data:
+            set_primitives(data["primitives"])
+
+    if args.self_test:
+        sys.stdout.write(_self_test())
+        return 0
+
+    text = "".join(args.chars) if args.chars else _read_stdin()
+    if not text:
+        parser.print_help()
+        return 1
+
+    strict = not args.no_strict
+    try:
+        if args.format == "dsl":
+            output = _format_dsl(text, strict)
+        elif args.format == "json":
+            output = _format_json(text, strict)
+        elif args.format == "tree":
+            output = _format_tree(text, strict)
+        else:
+            output = ""
+    except UnknownCharacterError as e:
+        sys.stderr.write(f"Error: UnknownCharacterError: {e}\n")
+        return 2
+    except ChineseDecomposeError as e:
+        sys.stderr.write(f"Error: {type(e).__name__}: {e}\n")
+        return 1
+
+    sys.stdout.write(output + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

chinese_decompose/api.py

@@ -0,0 +1,135 @@
+"""Decomposition tree and DSL serialization helpers."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Union
+
+from chinese_decompose.errors import UnknownCharacterError
+from chinese_decompose.loader import make_loader as _make_loader
+from chinese_decompose.split import split_one
+
+
+@dataclass(frozen=True)
+class DecompositionTree:
+    """Immutable decomposition result for a single character.
+
+    Attributes:
+        char: The original character (str of length 1).
+        children: Tuple of sub-trees at the next level.
+        position: The character's own 2-digit position code (set by parent).
+
+    Derived properties:
+        atoms: Flat list of leaf characters (primitives) in DFS order.
+        positions: Flat list of leaf positions corresponding to atoms.
+    """
+
+    char: str
+    children: tuple["DecompositionTree", ...] = ()
+    position: int | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.char, str) or len(self.char) != 1:
+            raise ValueError(
+                f"char must be a single-character string, got {self.char!r}"
+            )
+
+    @property
+    def atoms(self) -> tuple[str, ...]:
+        """Leaf (primitive) characters in DFS decomposition order."""
+        if not self.children:
+            return (self.char,)
+        out: list[str] = []
+        for child in self.children:
+            out.extend(child.atoms)
+        return tuple(out)
+
+    @property
+    def positions(self) -> tuple[int, ...]:
+        """Leaf positions corresponding to atoms, in DFS order."""
+        if not self.children:
+            return (self.position,) if self.position is not None else ()
+        out: list[int] = []
+        for child in self.children:
+            out.extend(child.positions)
+        return tuple(out)
+
+    def to_dsl(self) -> str:
+        """Serialize to DSL format per spec §5.1.
+
+        Staggered format: each segment's bracket carries the NEXT leaf's
+        position; the final leaf is bare. A single space is inserted between
+        every character (root or leaf) and its following bracketed position,
+        e.g. `踩 [30]:足 [60]:爪 [80]:木`. Primitives emit just the char.
+        """
+        if not self.children:
+            return self.char
+
+        leaves = self.atoms
+        leaf_positions = self.positions
+
+        if not leaf_positions:
+            return self.char + ":" + ":".join(leaves)
+
+        parts: list[str] = [f"{self.char} [{leaf_positions[0]}]"]
+        for i in range(len(leaves) - 1):
+            parts.append(f"{leaves[i]} [{leaf_positions[i + 1]}]")
+        parts.append(leaves[-1])
+        return ":".join(parts)
+
+
+def decompose(
+    text: str,
+    as_tree: bool = False,
+    strict: bool = True,
+    loader=None,
+) -> Union[str, list[DecompositionTree]]:
+    """Decompose each character in `text` and return DSL string or list of trees.
+
+    Args:
+        text: String of one or more CJK characters.
+        as_tree: If True, return list of DecompositionTree (one per char).
+                 If False (default), return the flat DSL string.
+        strict: If True (default), raise UnknownCharacterError on missing data.
+                If False, emit `?[?]:?` markers.
+        loader: Optional Loader instance. Defaults to singleton via make_loader().
+
+    Returns:
+        If as_tree=False: a DSL string. Multi-char input joined by `|`.
+        If as_tree=True: a list of DecompositionTree (one per char, in input order).
+    """
+    if loader is None:
+        loader = _make_loader()
+
+    trees: list[DecompositionTree] = []
+    for char in text:
+        flat = split_one(char, loader)
+        if flat is None:
+            if strict:
+                raise UnknownCharacterError(char)
+            trees.append(_marker_tree())
+            continue
+
+        if not flat:
+            # Primitive leaf
+            trees.append(DecompositionTree(char=char, children=()))
+        else:
+            children = tuple(
+                DecompositionTree(char=atom, children=(), position=pos)
+                for atom, pos in flat
+            )
+            trees.append(DecompositionTree(char=char, children=children))
+
+    if as_tree:
+        return trees
+    return "|".join(t.to_dsl() for t in trees)
+
+
+def _marker_tree() -> DecompositionTree:
+    """Marker tree for unknown characters in non-strict mode."""
+    return DecompositionTree(
+        char="?",
+        children=(DecompositionTree(char="?", children=(), position=0),),
+    )
+
+
+__all__ = ["DecompositionTree", "decompose"]

chinese_decompose/data/decomp_l1.json

@@ -0,0 +1,12 @@
+{
+  "_meta": {"tier": 1, "source": "manual-fixture"},
+  "好": [["女", 30], ["子", 40]],
+  "森": [["木", 10], ["木", 20], ["木", 40]],
+  "囚": [["囗", 90], ["人", 0]],
+  "回": [["囗", 90], ["口", 0]],
+  "男": [["田", 10], ["力", 20]],
+  "休": [["亻", 30], ["木", 40]],
+  "明": [["日", 30], ["月", 40]],
+  "晶": [["日", 10], ["日", 20], ["日", 40]],
+  "品": [["口", 10], ["口", 20], ["口", 40]]
+}

chinese_decompose/data/decomp_l2.json

@@ -0,0 +1 @@
+{"_meta": {"tier": 2, "source": "manual-fixture"}}

chinese_decompose/data/decomp_l3.json

@@ -0,0 +1,5 @@
+{
+  "_meta": {"tier": 3, "source": "manual-fixture"},
+  "踩": [["足", 30], ["采", 40]],
+  "采": [["爪", 10], ["木", 20]]
+}

chinese_decompose/data/decomp_patches.json

@@ -0,0 +1 @@
+{"_meta": {"tier": 4, "source": "manual-fixture"}}

chinese_decompose/data/primitives.json

@@ -0,0 +1,21 @@
+{
+  "primitives": [
+    "木","火","土","金","水","人","口","手","心","日","月","目","耳","鼻","舌","身",
+    "爪","戈","矢","石","一","乙","二","三","四","五","六","七","八","九","十","丁",
+    "卜","厂","寸","干","弓","牛","犬","玉","王","中","山","川","田","禾","竹","米",
+    "糸","网","羊","马","鸟","鱼","虫","贝","车","舟","门","阝","亻","刂","冫","氵",
+    "犭","忄","宀","艹","辶","阝","饣","亠","匚","凵","冂","卩","廴","彳","攴","疒",
+    "癶","衤","礻","纟","讠","钅","页","风","云","雨","雪","雷","女","子","父","母",
+    "兄","弟","姐","妹","己","已","巳","工","土","才","寸","巾","干","幺","广","廴",
+    "彐","彡","扌","支","攴","文","斗","斤","方","无","日","曰","月","木","欠","止",
+    "歹","殳","毋","比","毛","氏","气","水","火","爪","父","爻","爿","片","牙","牛",
+    "犬","玄","玉","瓜","瓦","甘","生","用","田","疋","疒","癶","白","皮","皿","目",
+    "矛","矢","石","示","禸","禾","穴","立","竹","米","糸","缶","网","羊","羽","老",
+    "而","耒","耳","聿","肉","臣","自","至","臼","舌","舛","舟","艮","色","艸","虍",
+    "虫","血","行","衣","襾","覀","角","言","谷","豆","豕","豸","貝","赤","走","足",
+    "身","車","辛","辰","辵","邑","酉","釆","里","金","長","門","阜","隶","隹","雨",
+    "靑","非","面","革","韋","音","頁","風","飛","食","首","香","馬","骨","高","髟",
+    "鬥","鬯","鬲","鬼","魚","鳥","鹵","鹿","麥","麻","黃","黍","黑","黹","黽","鼎",
+    "鼓","鼠","鼻","齊","亀","龍","龜","龠","囗"
+  ]
+}

chinese_decompose/dsl.py

@@ -0,0 +1,102 @@
+"""DSL serializer and parser per spec §5."""
+from __future__ import annotations
+
+import re
+from typing import Iterable, Union
+
+from chinese_decompose.api import DecompositionTree
+from chinese_decompose.errors import MalformedDSLParseError
+from chinese_decompose.structures import VALID_POSITIONS
+
+# Match a single char (CJK Unified + ASCII fallback) with optional [pos].
+# Allows an optional space between char and [pos] (user-facing format).
+_SEGMENT_PATTERN = re.compile(r"^([一-鿿　-〿?])\s*(?:\[(-?\d+)\])?$")
+
+
+def serialize_tree(tree: DecompositionTree) -> str:
+    """Serialize a single DecompositionTree to DSL.
+
+    Delegates to DecompositionTree.to_dsl() — same staggered format
+    (each segment's bracket is the NEXT leaf's position; last leaf is bare)
+    with spaces between chars and brackets.
+    """
+    return tree.to_dsl()
+
+
+def serialize_many(trees: Iterable[DecompositionTree]) -> str:
+    """Serialize multiple trees joined by `|` (per spec §5.3)."""
+    return "|".join(serialize_tree(t) for t in trees)
+
+
+def _parse_position(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    try:
+        code = int(raw)
+    except ValueError as e:
+        raise MalformedDSLParseError(f"Position code not an integer: {raw!r}") from e
+    if code not in VALID_POSITIONS:
+        raise MalformedDSLParseError(f"Position code {code!r} not in valid set")
+    return code
+
+
+def parse_dsl(dsl_str: str) -> DecompositionTree:
+    """Parse a DSL string into a DecompositionTree.
+
+    Format: `<root>[<pos>]:<segment>:<segment>:...:<lastLeaf>`.
+
+    The last leaf is bare (no brackets). Earlier segments may also lack
+    brackets (treated as position=None). Parser is 1-level — produces a flat
+    tree where children are leaves (intermediate non-leaf nodes are not
+    reconstructed; full round-trip would need richer nesting logic, deferred
+    to a future task).
+
+    Raises:
+        MalformedDSLParseError: on empty input, missing/invalid chars,
+        non-numeric or out-of-set position codes, or empty segments.
+    """
+    if not dsl_str:
+        raise MalformedDSLParseError("Empty DSL string")
+
+    raw_segments = dsl_str.split(":")
+    if not raw_segments or not raw_segments[0]:
+        raise MalformedDSLParseError("Missing root segment")
+
+    root_match = _SEGMENT_PATTERN.match(raw_segments[0])
+    if not root_match:
+        raise MalformedDSLParseError(f"Invalid root segment: {raw_segments[0]!r}")
+    root_char = root_match.group(1)
+    root_position = _parse_position(root_match.group(2))
+
+    # Detect malformed (missing/extra colons). Bare segments are allowed only
+    # for the very last one.
+    children: list[DecompositionTree] = []
+    for idx, seg in enumerate(raw_segments[1:], start=1):
+        last = idx == len(raw_segments) - 1
+        if not seg:
+            if last and idx == 1:
+                # Just `好[30]:` — trailing colon, treat as 1-leaf tree
+                break
+            raise MalformedDSLParseError(f"Empty segment at index {idx}")
+        m = _SEGMENT_PATTERN.match(seg)
+        if not m:
+            raise MalformedDSLParseError(f"Invalid segment: {seg!r}")
+        child_char = m.group(1)
+        child_pos_raw = m.group(2)
+        if child_pos_raw is None and not last:
+            raise MalformedDSLParseError(f"Non-final segment missing position: {seg!r}")
+        child_position = _parse_position(child_pos_raw)
+        children.append(
+            DecompositionTree(char=child_char, children=(), position=child_position)
+        )
+
+    return DecompositionTree(
+        char=root_char,
+        children=tuple(children),
+        position=root_position,
+    )
+
+
+def parse_dsl_multi(dsl_str: str) -> list[DecompositionTree]:
+    """Parse a multi-character DSL (joined by `|`)."""
+    return [parse_dsl(part) for part in dsl_str.split("|") if part]

chinese_decompose/errors.py

@@ -0,0 +1,26 @@
+"""Exception hierarchy for chinese_decompose."""
+from __future__ import annotations
+
+
+class ChineseDecomposeError(Exception):
+    """Base class for all chinese_decompose errors."""
+
+
+class UnknownCharacterError(ChineseDecomposeError):
+    """Raised when a character has no entry across all data tiers."""
+
+    def __init__(self, char: str):
+        self.char = char
+        super().__init__(f"No decomposition data for character: {char!r}")
+
+
+class MalformedDSLParseError(ChineseDecomposeError):
+    """Raised when DSL parsing fails (bad position, malformed segment)."""
+
+
+class InvalidPositionCodeError(ChineseDecomposeError):
+    """Raised when a data file or input contains a code outside the valid 2-digit set."""
+
+
+class CompositionError(ChineseDecomposeError):
+    """Raised by compose(parent, child) when the combination is geometrically invalid."""

chinese_decompose/loader.py

@@ -0,0 +1,132 @@
+"""Multi-tier decomposition data loader with last-wins resolution."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from chinese_decompose.errors import InvalidPositionCodeError
+from chinese_decompose.structures import VALID_POSITIONS
+
+_TIER_FILES: dict[str, Path | None] = {}
+
+
+def _resolve_default_paths() -> tuple[Path, Path, Path, Path]:
+    data = Path(__file__).parent / "data"
+    return (
+        data / "decomp_l1.json",
+        data / "decomp_l2.json",
+        data / "decomp_l3.json",
+        data / "decomp_patches.json",
+    )
+
+
+def _validate_entry(char: str, entries: Any) -> list[tuple[str, int]]:
+    if not isinstance(entries, list):
+        raise InvalidPositionCodeError(
+            f"Entry for {char!r} must be a list of [char, code] pairs"
+        )
+    result = []
+    for entry in entries:
+        if not isinstance(entry, list) or len(entry) != 2:
+            raise InvalidPositionCodeError(
+                f"Entry for {char!r} malformed: {entry!r}"
+            )
+        sub_char, code = entry
+        if not isinstance(sub_char, str) or len(sub_char) != 1:
+            raise InvalidPositionCodeError(
+                f"Sub-component for {char!r} must be a single char, got {sub_char!r}"
+            )
+        if not isinstance(code, int) or code not in VALID_POSITIONS:
+            raise InvalidPositionCodeError(
+                f"Position code for {char!r}: {code!r} not in valid set"
+            )
+        result.append((sub_char, code))
+    return result
+
+
+def _load_json(path: Path) -> dict[str, list[tuple[str, int]]]:
+    if not path.exists():
+        return {}
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    # Strip metadata
+    raw.pop("_meta", None)
+    out: dict[str, list[tuple[str, int]]] = {}
+    for char, entries in raw.items():
+        out[char] = _validate_entry(char, entries)
+    return out
+
+
+class Loader:
+    """Multi-tier decomposition loader.
+
+    Resolution order: patches > l3 > l2 > l1 (last-wins).
+    Caches results in-process; call clear_cache() to reset.
+    """
+
+    _instance: "Loader | None" = None
+
+    def __init__(
+        self,
+        l1_path: Path,
+        l2_path: Path,
+        l3_path: Path,
+        patches_path: Path,
+    ):
+        self._paths = (l1_path, l2_path, l3_path, patches_path)
+        self._cache: dict[str, list[tuple[str, int]] | None] = {}
+        # Pre-load all data; raise on invalid codes
+        l1 = _load_json(l1_path)
+        l2 = _load_json(l2_path)
+        l3 = _load_json(l3_path)
+        patches = _load_json(patches_path)
+        self._merged = {}
+        for char in l1:
+            self._merged[char] = l1[char]
+        for char in l2:
+            self._merged[char] = l2[char]
+        for char in l3:
+            self._merged[char] = l3[char]
+        for char in patches:
+            self._merged[char] = patches[char]
+
+    def get(self, char: str) -> list[tuple[str, int]] | None:
+        """Return one-level decomposition for `char`, or None if unknown."""
+        if char in self._cache:
+            return self._cache[char]
+        result = self._merged.get(char)
+        self._cache[char] = result
+        return result
+
+    def __len__(self) -> int:
+        return len(self._merged)
+
+
+def make_loader(
+    l1_path: Path | None = None,
+    l2_path: Path | None = None,
+    l3_path: Path | None = None,
+    patches_path: Path | None = None,
+) -> Loader:
+    """Construct (or return cached singleton) Loader instance."""
+    if (
+        l1_path is None
+        and l2_path is None
+        and l3_path is None
+        and patches_path is None
+    ):
+        p1, p2, p3, pp = _resolve_default_paths()
+    else:
+        d1, d2, d3, dp = _resolve_default_paths()
+        p1 = l1_path or d1
+        p2 = l2_path or d2
+        p3 = l3_path or d3
+        pp = patches_path or dp
+    Loader._instance = Loader(p1, p2, p3, pp)
+    return Loader._instance
+
+
+def clear_cache() -> None:
+    """Reset loader cache; next get() rebuilds from JSON."""
+    if Loader._instance is not None:
+        Loader._instance._cache.clear()

chinese_decompose/primitives.py

@@ -0,0 +1,41 @@
+"""Primitive set: lookup and process-local override."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+_DATA_PATH = Path(__file__).parent / "data" / "primitives.json"
+_DEFAULT: frozenset[str] = frozenset(
+    json.loads(_DATA_PATH.read_text(encoding="utf-8"))["primitives"]
+)
+_OVERRIDE: frozenset[str] | None = None
+
+
+def get_primitives() -> frozenset[str]:
+    """Return the currently-active primitive set (override or default)."""
+    return _OVERRIDE if _OVERRIDE is not None else _DEFAULT
+
+
+def set_primitives(iterable: Iterable[str]) -> None:
+    """Replace the primitive set for the current process.
+
+    Pass-through: useful for testing with custom primitive subsets.
+    Reset by passing None or by re-importing the module. Does NOT persist.
+    """
+    global _OVERRIDE
+    items = list(iterable)
+    if not all(isinstance(s, str) and len(s) == 1 for s in items):
+        raise ValueError("primitives must be single-character strings")
+    _OVERRIDE = frozenset(items)
+
+
+def is_primitive(char: str) -> bool:
+    """Return True if `char` is in the active primitive set."""
+    return char in get_primitives()
+
+
+def reset_primitives() -> None:
+    """Clear any process-local override, restoring bundled defaults."""
+    global _OVERRIDE
+    _OVERRIDE = None

chinese_decompose/split.py

@@ -0,0 +1,52 @@
+"""Recursive decomposition walker with position composition."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from chinese_decompose.primitives import is_primitive
+from chinese_decompose.structures import compose
+
+if TYPE_CHECKING:
+    from chinese_decompose.loader import Loader
+
+
+def split_one(char: str, loader: "Loader") -> list[tuple[str, int]] | None:
+    """Recursively decompose `char` into (atom_char, final_position) pairs.
+
+    Returns:
+        - [] if `char` is a primitive (no further decomposition).
+        - list of (atom_char, position) pairs after full recursive expansion.
+        - None if `char` has no entry in the loader.
+
+    The recursion chains position composition: for each sub-character at its
+    declared local position, compose with the parent's position to derive the
+    final 9-grid position.
+    """
+    return _split_recursive(char, parent_position=0, loader=loader)
+
+
+def _split_recursive(
+    char: str, parent_position: int, loader: "Loader"
+) -> list[tuple[str, int]] | None:
+    """Recursively walk the decomposition tree, composing positions."""
+    if is_primitive(char):
+        # Primitives terminate; no expansion. Empty list signals leaf.
+        return []
+
+    decomp = loader.get(char)
+    if decomp is None:
+        return None  # unknown
+
+    out: list[tuple[str, int]] = []
+    for sub_char, local_pos in decomp:
+        final_pos = compose(parent_position, local_pos)
+        sub_result = _split_recursive(sub_char, parent_position=final_pos, loader=loader)
+        if sub_result is None:
+            # Sub-char unknown at this level; bubble up
+            return None
+        if sub_result:
+            out.extend(sub_result)
+        else:
+            # Primitive sub-character: emit just the char with final position
+            out.append((sub_char, final_pos))
+    return out

chinese_decompose/structures.py

@@ -0,0 +1,127 @@
+"""Position code constants for the 9-grid spatial encoding.
+
+Codes are 2-digit numbers (spec §2.1): digit A is the spatial zone, digit B
+is the sub-zone within the parent zone (0 means atomic slot, non-zero for
+specific sub-strips or surround variants).
+"""
+from __future__ import annotations
+
+from chinese_decompose.errors import CompositionError
+
+# Atomic single-slot positions
+P_CENTER = 0
+P_TOP = 10
+P_BOTTOM = 20
+P_LEFT = 30
+P_RIGHT = 40
+P_TOP_LEFT = 50
+P_TOP_RIGHT = 60
+P_BOTTOM_LEFT = 70
+P_BOTTOM_RIGHT = 80
+
+# 4-cell layout strip positions
+P_STRIP_VERT_RIGHT = 14   # inner-right-edge of upper zone (e.g. 目's right strip)
+P_STRIP_VERT_LEFT = 16    # inner-left-edge of lower zone
+P_STRIP_HORIZ_RIGHT = 34  # inner-right-edge of left zone (e.g. 罒's right strip)
+P_STRIP_HORIZ_LEFT = 36   # inner-left-edge of right zone
+
+# Surround envelopes (90-99)
+P_SURROUND_FULL = 90
+P_SURROUND_BELOW = 91
+P_SURROUND_LEFT = 92
+P_SURROUND_ABOVE = 93
+P_SURROUND_RIGHT = 94
+P_SURROUND_UL = 95
+P_SURROUND_LR = 96
+P_SURROUND_UR = 97
+P_SURROUND_LL_LO = 98     # lower-bottom extension (semantics TBD per spec)
+P_SURROUND_LL = 99
+
+VALID_POSITIONS: frozenset[int] = frozenset({
+    P_CENTER, P_TOP, P_BOTTOM, P_LEFT, P_RIGHT,
+    P_TOP_LEFT, P_TOP_RIGHT, P_BOTTOM_LEFT, P_BOTTOM_RIGHT,
+    P_STRIP_VERT_RIGHT, P_STRIP_VERT_LEFT,
+    P_STRIP_HORIZ_RIGHT, P_STRIP_HORIZ_LEFT,
+    P_SURROUND_FULL, P_SURROUND_BELOW, P_SURROUND_LEFT,
+    P_SURROUND_ABOVE, P_SURROUND_RIGHT, P_SURROUND_UL,
+    P_SURROUND_LR, P_SURROUND_UR, P_SURROUND_LL,
+    # NOTE: P_SURROUND_LL_LO (98) intentionally excluded — semantics TBD per spec §2.1
+})
+
+
+# Composition table (spec §2.3): (parent, child) -> composed position.
+# Missing keys are geometrically invalid and raise CompositionError at runtime.
+COMPOSE_TABLE: dict[tuple[int, int], int] = {
+    # 00 (center) row — center passes any valid position through unchanged.
+    (0, 0): 0, (0, 10): 10, (0, 20): 20, (0, 30): 30, (0, 40): 40,
+    (0, 50): 50, (0, 60): 60, (0, 70): 70, (0, 80): 80,
+    (0, 14): 14, (0, 16): 16, (0, 34): 34, (0, 36): 36,
+    (0, 90): 90, (0, 91): 91, (0, 92): 92, (0, 93): 93, (0, 94): 94,
+    (0, 95): 95, (0, 96): 96, (0, 97): 97, (0, 99): 99,
+
+    # 10 (top) row
+    (10, 0): 10, (10, 10): 10, (10, 30): 50, (10, 40): 60,
+    (10, 50): 50, (10, 60): 60,
+
+    # 20 (bottom) row
+    (20, 0): 20, (20, 20): 20, (20, 30): 70, (20, 40): 80,
+    (20, 70): 70, (20, 80): 80,
+
+    # 30 (left) row
+    (30, 0): 30, (30, 10): 50, (30, 20): 70, (30, 30): 30, (30, 40): 30,
+    (30, 50): 50, (30, 60): 50, (30, 70): 70, (30, 80): 70,
+
+    # 40 (right) row
+    (40, 0): 40, (40, 10): 60, (40, 20): 80, (40, 30): 40, (40, 40): 40,
+    (40, 50): 60, (40, 60): 60, (40, 70): 80, (40, 80): 80,
+
+    # 50 (top-left corner) row — invariant under left/top, collapses for right/bottom
+    (50, 0): 50, (50, 10): 50, (50, 20): 50, (50, 30): 50, (50, 40): 50,
+    (50, 50): 50, (50, 60): 50, (50, 70): 70, (50, 80): 70,
+
+    # 60 (top-right corner) row
+    (60, 0): 60, (60, 10): 60, (60, 20): 60, (60, 30): 60, (60, 40): 60,
+    (60, 50): 60, (60, 60): 60, (60, 70): 80, (60, 80): 80,
+
+    # 70 (bottom-left corner) row
+    (70, 0): 70, (70, 10): 50, (70, 20): 70, (70, 30): 70, (70, 40): 70,
+    (70, 50): 50, (70, 60): 50, (70, 70): 70, (70, 80): 70,
+
+    # 80 (bottom-right corner) row
+    (80, 0): 80, (80, 10): 60, (80, 20): 80, (80, 30): 80, (80, 40): 80,
+    (80, 50): 60, (80, 60): 60, (80, 70): 80, (80, 80): 80,
+
+    # 9X (surround) row — transparency rule: passes children through
+    (90, 0): 0, (91, 0): 0, (92, 0): 0, (93, 0): 0, (94, 0): 0,
+    (95, 0): 0, (96, 0): 0, (97, 0): 0, (99, 0): 0,
+    (90, 10): 10, (91, 10): 10, (92, 10): 10, (93, 10): 10, (94, 10): 10,
+    (95, 10): 10, (96, 10): 10, (97, 10): 10, (99, 10): 10,
+    (90, 20): 20, (91, 20): 20, (92, 20): 20, (93, 20): 20, (94, 20): 20,
+    (95, 20): 20, (96, 20): 20, (97, 20): 20, (99, 20): 20,
+    (90, 30): 30, (91, 30): 30, (92, 30): 30, (93, 30): 30, (94, 30): 30,
+    (95, 30): 30, (96, 30): 30, (97, 30): 30, (99, 30): 30,
+    (90, 40): 40, (91, 40): 40, (92, 40): 40, (93, 40): 40, (94, 40): 40,
+    (95, 40): 40, (96, 40): 40, (97, 40): 40, (99, 40): 40,
+    (90, 50): 50, (91, 50): 50, (92, 50): 50, (93, 50): 50, (94, 50): 50,
+    (95, 50): 50, (96, 50): 50, (97, 50): 50, (99, 50): 50,
+    (90, 60): 60, (91, 60): 60, (92, 60): 60, (93, 60): 60, (94, 60): 60,
+    (95, 60): 60, (96, 60): 60, (97, 60): 60, (99, 60): 60,
+    (90, 70): 70, (91, 70): 70, (92, 70): 70, (93, 70): 70, (94, 70): 70,
+    (95, 70): 70, (96, 70): 70, (97, 70): 70, (99, 70): 70,
+    (90, 80): 80, (91, 80): 80, (92, 80): 80, (93, 80): 80, (94, 80): 80,
+    (95, 80): 80, (96, 80): 80, (97, 80): 80, (99, 80): 80,
+}
+
+
+def compose(parent: int, child: int) -> int:
+    """Compose parent position with child position per spec §2.3 table.
+
+    Raises:
+        CompositionError: if (parent, child) is a geometrically invalid pair.
+    """
+    try:
+        return COMPOSE_TABLE[(parent, child)]
+    except KeyError as e:
+        raise CompositionError(
+            f"Invalid composition: parent={parent}, child={child}"
+        ) from e

cjk_semantic_split-0.1.0.dist-info/METADATA

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: cjk-semantic-split
+Version: 0.1.0
+Summary: Recursive atomic decomposition of CJK characters with 9-grid spatial encoding
+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,cjk,decomposition,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
+
+Recursive atomic decomposition of CJK characters 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('好')]
+```
+
+## 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 踩                 # DSL string
+python -m chinese_decompose 踩 --format json   # JSON output
+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
+
+```python
+from chinese_decompose import set_primitives
+
+set_primitives({"木", "火", "水", ...})  # process-local override
+```
+
+## License
+
+MIT — see `LICENSE`.

cjk_semantic_split-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+chinese_decompose/__init__.py,sha256=IL1rJLukrojVwZ5r5q1hakFxJDPRJyKwe5Ln0KWntgg,97
+chinese_decompose/__main__.py,sha256=nQ3Bof4LyuuCSEW0dloPbInX1lP_B5GHeJdvket43Tw,3790
+chinese_decompose/api.py,sha256=wN0ZE3qgtjr8R9Xt3Ds6AxpoQ0-KaqFXrNAqq2-BRu4,4538
+chinese_decompose/dsl.py,sha256=30YvTLrKdqDlBsmaGahVCaeZqjZGZaHfnHkLezPCIYc,3844
+chinese_decompose/errors.py,sha256=CB0GrYVJkVqbgwO71npxI7OT5atJ3B5XB3ocHLHbErk,857
+chinese_decompose/loader.py,sha256=Ron4PWFdFTm05pWVFDlJSM_xQBf8AL5JfmV94MzaapI,4083
+chinese_decompose/primitives.py,sha256=K1Mi6UvlLe6Xpdn58NBSPTULhy9O6ciFJZveYzscu4A,1320
+chinese_decompose/split.py,sha256=mbx1d02WesFJ296DHCfS1PRANd4yhqU3HiR-mmUstLk,1858
+chinese_decompose/structures.py,sha256=rvwxuLzFPKWy6otREzgv-fO_5AvfIe0tI2UVf0O3vjY,5137
+chinese_decompose/data/decomp_l1.json,sha256=PkyhKO7K-2YcYWBuMWni1vADV6Wc7Z-y_ZQ51i1cY2U,425
+chinese_decompose/data/decomp_l2.json,sha256=226RW1qW_YelrkKcSAYKYwun-3RZ0rqXlS2TH5A2fkg,51
+chinese_decompose/data/decomp_l3.json,sha256=MxBMGfms0j_wP_WujpyCoa2DisNESnXvfYDJvYqxsoY,129
+chinese_decompose/data/decomp_patches.json,sha256=3PlQwvVUd_fwNm5auYiUdnnmP5xACSGDxgLYuzNWbVs,51
+chinese_decompose/data/primitives.json,sha256=b7ljpLXr3dAQWZLBe-akyWo-fyKDIBNZwOimba5w6yE,1700
+cjk_semantic_split-0.1.0.dist-info/METADATA,sha256=_j5KpPPTjGOp0E_PyONjv9-yggqvplBqgP5ludaYv7o,3889
+cjk_semantic_split-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cjk_semantic_split-0.1.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+cjk_semantic_split-0.1.0.dist-info/RECORD,,

cjk_semantic_split-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cjk_semantic_split-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+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.